Enlightenment CVS committal
Author : mej
Project : eterm
Module : libast
Dir : eterm/libast/include
Modified Files:
libast.h libast_internal.h
Log Message:
Fri Apr 4 22:59:45 2003 Michael Jennings (mej)
Finally finished documenting libast.h.
===================================================================
RCS file: /cvsroot/enlightenment/eterm/libast/include/libast.h,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -3 -r1.34 -r1.35
--- libast.h 2 Apr 2003 04:07:48 -0000 1.34
+++ libast.h 5 Apr 2003 04:00:15 -0000 1.35
@@ -30,6 +30,8 @@
* including all required system headers and LibAST Object headers.
*
* @author Michael Jennings <[EMAIL PROTECTED]>
+ * @version $Revision: 1.35 $
+ * @date $Date: 2003/04/05 04:00:15 $
*/
#ifndef _LIBAST_H_
@@ -1589,6 +1591,7 @@
/******************************* OPTIONS GOOP **********************************/
+/[EMAIL PROTECTED]/
/**
* @name Option Flags
* Flags for individual options.
@@ -1602,10 +1605,9 @@
* non-type-related information, such as flagging preparsed or
* deprecated options.
*
- * @see DOXGRP_OPT
* @ingroup DOXGRP_OPT
*/
-/[EMAIL PROTECTED]/
+
/** No flags. No flags. */
#define SPIFOPT_FLAG_NONE (0)
/** Boolean option. This flag marks a boolean option. */
@@ -1664,6 +1666,7 @@
#define SPIFOPT_FLAG_MODMASK (0xf800)
/[EMAIL PROTECTED]/
+/[EMAIL PROTECTED]/
/**
* @name Parser Settings
* Flags which alter the behavior of the parser itself.
@@ -1675,10 +1678,9 @@
* that you do wish to manipulate these flags, use the
* SPIFOPT_FLAGS_*() macros.
*
- * @see DOXGRP_OPT
* @ingroup DOXGRP_OPT
*/
-/[EMAIL PROTECTED]/
+
/** Postparse flag. This flag denotes whether or not the initial
* option parsing pass has been done. The first call to the
* spifopt_parse() function will parse only those options which have
@@ -1688,6 +1690,7 @@
#define SPIFOPT_SETTING_POSTPARSE (1UL << 0)
/[EMAIL PROTECTED]/
+/[EMAIL PROTECTED]/
/**
* @name Option Declaration Convenience Macros
* Macros which simplify the building of the options list.
@@ -1703,10 +1706,9 @@
* recommended in order to enhance readability and reduce the
* probability of human error.
*
- * @see DOXGRP_OPT
* @ingroup DOXGRP_OPT
*/
-/[EMAIL PROTECTED]/
+
/**
* Primary option declaration macro.
*
@@ -2046,71 +2048,320 @@
SPIFOPT_OPTION(0, l, d, (SPIFOPT_FLAG_ABSTRACT | SPIFOPT_FLAG_PREPARSE), f, 0)
/[EMAIL PROTECTED]/
+/[EMAIL PROTECTED]/
/**
* @name Option Flag Macros
- * Macros which provide access to option type information.
+ * Macros which provide access to option flag information.
*
- *
+ * These macros provide access to option type and flag information
+ * while abstracting the actual method of storage and retrieval. Each
+ * macro takes exactly one parameter, the offset within the options
+ * list.
*
- * @see DOXGRP_OPT
* @ingroup DOXGRP_OPT
*/
-/[EMAIL PROTECTED]/
-#define SPIFOPT_TYPE(opt) (((spifopt_t) (opt)).flags &
SPIFOPT_FLAG_TYPEMASK)
+
+/**
+ * Type macro.
+ *
+ * Retrieves the type flag. Use of this macro is discouraged; use one
+ * of the other macros instead.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return The type flag (SPIFOPT_FLAG_*)
+ */
#define SPIFOPT_OPT_TYPE(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_TYPEMASK)
+/**
+ * Boolean option test. Tests whether or not the given option is boolean.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not boolean, non-zero if it is.
+ */
#define SPIFOPT_OPT_IS_BOOLEAN(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_BOOLEAN)
-#define SPIFOPT_OPT_IS_STRING(n) (SPIFOPT_OPT_FLAGS(n) & SPIFOPT_FLAG_STRING)
+/**
+ * Counter option test. Tests whether or not the given option is a counter.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not a counter, non-zero if it is.
+ */
+#define SPIFOPT_OPT_IS_COUNTER(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_COUNTER)
+/**
+ * Integer option test. Tests whether or not the given option is an integer.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not an integer, non-zero if it is.
+ */
#define SPIFOPT_OPT_IS_INTEGER(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_INTEGER)
+/**
+ * String option test. Tests whether or not the given option is a string.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not a string, non-zero if it is.
+ */
+#define SPIFOPT_OPT_IS_STRING(n) (SPIFOPT_OPT_FLAGS(n) & SPIFOPT_FLAG_STRING)
+/**
+ * Argument list option test. Tests whether or not the given option
+ * is an argument list.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not an argument list, non-zero if it is.
+ */
#define SPIFOPT_OPT_IS_ARGLIST(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_ARGLIST)
+/**
+ * Abstract option test. Tests whether or not the given option is abstract.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not abstract, non-zero if it is.
+ */
#define SPIFOPT_OPT_IS_ABSTRACT(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_ABSTRACT)
+/**
+ * Preparse option test. Tests whether or not the given option is to
+ * be preparsed.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not to be pre-parsed, non-zero if it is.
+ */
#define SPIFOPT_OPT_IS_PREPARSE(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_PREPARSE)
+/**
+ * Deprecated option test. Tests whether or not the given option is deprecated.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not deprecated, non-zero if it is.
+ */
#define SPIFOPT_OPT_IS_DEPRECATED(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_DEPRECATED)
-#define SPIFOPT_OPT_NEEDS_VALUE(n) (SPIFOPT_OPT_FLAGS(n) &
(SPIFOPT_FLAG_STRING | SPIFOPT_FLAG_INTEGER | SPIFOPT_FLAG_ARGLIST))
+/**
+ * Array option test. Tests whether or not the given option is an array.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option is not an array, non-zero if it is.
+ */
+#define SPIFOPT_OPT_IS_ARRAY(n) (SPIFOPT_OPT_FLAGS(n) & SPIFOPT_FLAG_ARRAY)
+/**
+ * Value required option test. Tests whether or not the given option
+ * requires a value.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return 0 if option does not require a value, non-zero if it does.
+ */
+#define SPIFOPT_OPT_NEEDS_VALUE(n) (SPIFOPT_OPT_FLAGS(n) &
SPIFOPT_FLAG_TYPEMASK_VALUE)
/[EMAIL PROTECTED]/
+/[EMAIL PROTECTED]/
/**
* @name Option Structure Access Macros
* Macros which provide access to individual structure components.
*
- *
+ * These macros provide an easy method for accessing the various
+ * members of a single option structure (spifopt_t_struct) within the
+ * options list without needing to know how the options list, or the
+ * options within it, are stored.
*
- * @see DOXGRP_OPT
* @ingroup DOXGRP_OPT
*/
-/[EMAIL PROTECTED]/
-#define SPIFOPT_OPT_SHORT(n) (SPIFOPT_OPTLIST(n).short_opt)
-#define SPIFOPT_OPT_LONG(n) (SPIFOPT_OPTLIST(n).long_opt)
-#define SPIFOPT_OPT_DESC(n) (SPIFOPT_OPTLIST(n).desc)
-#define SPIFOPT_OPT_FLAGS(n) (SPIFOPT_OPTLIST(n).flags)
-#define SPIFOPT_OPT_VALUE(n) (SPIFOPT_OPTLIST(n).value)
-#define SPIFOPT_OPT_MASK(n) (SPIFOPT_OPTLIST(n).mask)
+
+/**
+ * Short form. Returns the short form of the option.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return The short (char) form of the option.
+ */
+#define SPIFOPT_OPT_SHORT(n) (SPIFOPT_OPTLIST_GET_OPT(n).short_opt)
+/**
+ * Long form. Returns the long form of the option.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return The long (const char *) form of the option.
+ */
+#define SPIFOPT_OPT_LONG(n) (SPIFOPT_OPTLIST_GET_OPT(n).long_opt)
+/**
+ * Description. Returns the description of the option.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return The description (const char *) of the option.
+ */
+#define SPIFOPT_OPT_DESC(n) (SPIFOPT_OPTLIST_GET_OPT(n).desc)
+/**
+ * Flags. Returns the flags for the option.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return The flags (spif_uint16_t) for the option.
+ */
+#define SPIFOPT_OPT_FLAGS(n) (SPIFOPT_OPTLIST_GET_OPT(n).flags)
+/**
+ * Value pointer. Returns the value pointer for the option.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return The value pointer (void *) for the option.
+ */
+#define SPIFOPT_OPT_VALUE(n) (SPIFOPT_OPTLIST_GET_OPT(n).value)
+/**
+ * Bitmask. Returns the bitmask for the option.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return The bitmask (spif_uint32_t) for the option.
+ */
+#define SPIFOPT_OPT_MASK(n) (SPIFOPT_OPTLIST_GET_OPT(n).mask)
/[EMAIL PROTECTED]/
+/[EMAIL PROTECTED]/
/**
* @name Option Parser Settings Macros
* Macros which provide access to the option parser settings.
*
- *
+ * These macros provide abstracted access to various settings used by
+ * the option parser.
*
- * @see DOXGRP_OPT
* @ingroup DOXGRP_OPT
*/
-/[EMAIL PROTECTED]/
-#define SPIFOPT_OPTLIST(n) (spifopt_settings.opt_list[((n) <
(spifopt_settings.num_opts) ? (n) : (0))])
+
+/**
+ * Retrieves a single option structure.
+ *
+ * This macro returns a single option structure (spifopt_t_struct)
+ * from the options list. This is mostly for internal use.
+ *
+ * @param n The index of the desired option in the options list.
+ * @return The option structure (spifopt_t_struct).
+ */
+#define SPIFOPT_OPTLIST_GET_OPT(n) (spifopt_settings.opt_list[((n) <
(spifopt_settings.num_opts) ? (n) : (0))])
+/**
+ * Sets the option list.
+ *
+ * This macro should be called by client programs to set the option
+ * list. It must be a spifopt_t * of some type (probably a
+ * spifopt_t []). Once set, it must not be manipulated directly; only
+ * via the LibAST-supplied macros.
+ *
+ * @param l The options list variable (a spifopt_t pointer or array).
+ */
#define SPIFOPT_OPTLIST_SET(l) (spifopt_settings.opt_list = ((spifopt_t *)
(l)))
+/**
+ * Obtains the number of options.
+ *
+ * This macro returns the total number of options in the options list.
+ *
+ * @return The number of options in the list.
+ */
#define SPIFOPT_NUMOPTS_GET() (spifopt_settings.num_opts)
+/**
+ * Sets the number of options.
+ *
+ * This macro sets the number of options in the options list. It
+ * should be called immediately after SPIFOPT_OPTLIST_SET() and
+ * @em before any functions or macros which use the options list. The
+ * most common way to handle this is to use a fixed array for the
+ * options list and call
+ *
+ * @code
+ * SPIFOPT_NUMOPTS_SET(sizeof(option_list) / sizeof(spifopt_t))
+ * @endcode
+ *
+ * to set the option count.
+ *
+ * @param n The number of elements in the options list.
+ */
#define SPIFOPT_NUMOPTS_SET(n) (spifopt_settings.num_opts = (n))
+/**
+ * Obtains the option parser flag settings.
+ *
+ * This macro returns the value of the parser settings flags. In most
+ * cases, you should use SPIFOPT_FLAGS_IS_SET() instead.
+ *
+ * @return The value of the parser settings flags.
+ */
#define SPIFOPT_FLAGS_GET() (spifopt_settings.flags)
+/**
+ * Sets an option parser settings flag.
+ *
+ * This macro sets one or more parser settings flags. There are
+ * currently no client-managed parser flags, so you should avoid this
+ * macro.
+ *
+ * @param m The flag (or set of bitwise-or'd flags) to turn on.
+ */
#define SPIFOPT_FLAGS_SET(m) (spifopt_settings.flags |= (m))
+/**
+ * Checks whether or not an option parser settings flag is set.
+ *
+ * This macro tests one or more parser settings flags. There are
+ * currently no client-managed parser flags, so you should avoid this
+ * macro.
+ *
+ * @param m The flag (or set of bitwise-or'd flags) to check.
+ * @return 0 if none of the selected flags are set, non-zero if at
+ * least one is.
+ */
#define SPIFOPT_FLAGS_IS_SET(m) (spifopt_settings.flags & (m))
+/**
+ * Clears an option parser settings flag.
+ *
+ * This macro clears one or more parser settings flags. There are
+ * currently no client-managed parser flags, so you should avoid this
+ * macro.
+ *
+ * @param m The flag (or set of bitwise-or'd flags) to turn off.
+ */
#define SPIFOPT_FLAGS_CLEAR(m) (spifopt_settings.flags &= ~(m))
+/**
+ * Gets the bad option count.
+ *
+ * This macro retrieves the count of bad options encountered during
+ * option parsing.
+ *
+ * @return The number of bad options encountered.
+ */
#define SPIFOPT_BADOPTS_GET() (spifopt_settings.bad_opts)
+/**
+ * Sets the bad option count.
+ *
+ * This macro sets the count of bad options encountered during option
+ * parsing. This macro should not be used by client programs.
+ *
+ * @param n The number of bad options encountered.
+ */
#define SPIFOPT_BADOPTS_SET(n) (spifopt_settings.bad_opts = (n))
+/**
+ * Gets the bad option setting.
+ *
+ * This macro retrieves the setting for the number of bad options
+ * allowed before parsing is aborted and the help screen is displayed.
+ *
+ * @return The number of bad options allowed.
+ */
#define SPIFOPT_ALLOWBAD_GET() (spifopt_settings.allow_bad)
+/**
+ * Sets the bad option setting.
+ *
+ * This macro sets the number of bad options allowed before parsing is
+ * aborted and the help screen is displayed. This macro should be
+ * called prior to option parsing.
+ *
+ * @param n The number of bad options allowed.
+ */
#define SPIFOPT_ALLOWBAD_SET(n) (spifopt_settings.allow_bad = (n))
-#define SPIFOPT_INDENT_GET() (spifopt_settings.indent)
-#define SPIFOPT_INDENT_SET(n) (spifopt_settings.indent = (n))
+/**
+ * Gets the help handler function pointer.
+ *
+ * This macro retrieves the pointer to the function which will be
+ * called to display program help, due either to a help option or
+ * an excess number of option parsing errors. If this value is not
+ * set by the client (via the SPIFOPT_HELPHANDLER_SET() macro), the
+ * default handler is the built-in spifopt_usage() function.
+ *
+ * @return The function pointer for the help/usage screen function.
+ */
#define SPIFOPT_HELPHANDLER ((spifopt_settings.help_handler) ?
(spifopt_settings.help_handler) : (spifopt_usage))
+/**
+ * Sets the help handler function pointer.
+ *
+ * This macro sets the pointer to the function which will be called to
+ * display program help, due either to a help option or an excess
+ * number of option parsing errors. If the client fails to call this
+ * macro prior to option parsing, the built-in spifopt_usage()
+ * function is used instead.
+ *
+ * @param f A function pointer of type spifopt_helphandler_t.
+ */
#define SPIFOPT_HELPHANDLER_SET(f) (spifopt_settings.help_handler = (f))
/[EMAIL PROTECTED]/
===================================================================
RCS file: /cvsroot/enlightenment/eterm/libast/include/libast_internal.h,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -3 -r1.12 -r1.13
--- libast_internal.h 8 Mar 2003 05:01:37 -0000 1.12
+++ libast_internal.h 5 Apr 2003 04:00:18 -0000 1.13
@@ -21,6 +21,18 @@
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
+/**
+ * @file libast_internal.h
+ * LibAST header file for internal-use-only stuff.
+ *
+ * This file contains all macros, structure definitions, etc. which
+ * are restricted to internal LibAST use only.
+ *
+ * @author Michael Jennings <[EMAIL PROTECTED]>
+ * @version $Revision: 1.13 $
+ * @date $Date: 2003/04/05 04:00:18 $
+ */
+
#ifndef _LIBAST_INTERNAL_H_
#define _LIBAST_INTERNAL_H_
-------------------------------------------------------
This SF.net email is sponsored by: ValueWeb:
Dedicated Hosting for just $79/mo with 500 GB of bandwidth!
No other company gives more support or power for your dedicated server
http://click.atdmt.com/AFF/go/sdnxxaff00300020aff/direct/01/
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
