/* ----------------------------------------------------------------- */ /* Copyright (c) 2006 by Richard Harter */ /* */ /* Permission is hereby granted, free of charge, to any person */ /* obtaining a copy of this software and associated documentation */ /* files (the "Software"), to deal in the Software without */ /* restriction, including without limitation the rights to use, */ /* copy, modify, merge, publish, distribute, sublicense, and/or */ /* sell copies of the Software, and to permit persons to whom the */ /* Software is furnished to do so, subject to the following */ /* conditions: */ /* */ /* The above copyright notice and this permission notice shall be */ /* included in all copies or substantial portions of the */ /* Software. */ /* */ /* Derivative works shall include a notice that the software is a */ /* modified version of the copyrighted software. */ /* */ /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY */ /* KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE */ /* WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR */ /* PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR */ /* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER */ /* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR */ /* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ /* */ /* ----------------------------------------------------------------- */ /* */ /* Revision History */ /* */ /* 21 Nov 2007: First Public release */ /* */ /* ----------------------------------------------------------------- */ /* This include file contains the interface for the options processing software. The general idea is that the options are described with option define routines. The command line is parsed and the options are processed with a call to an option processing routine called optproc. The option processing in optproc begins with initializing all of the variables that are referred to in the definition calls. The argvec strings are then processed one by one; each option is implemented by setting the variable corresponding to that option. There can be more than one set of defined options; each such set is called an option context. The argvec strings can be processed more than once, each time with a different set of options. OPTION TYPES AND DEFINITION There are several option types with corresponding definition functions. They include: one for setting strings, one for setting flags, nine for setting numbers (short, int, and long, unsigned short, int, and long, size_t, float, double), and four for setting FILE handles (stdin, stdout, stderr, general). The string definition function, opt_define_string, has four arguments, the option name, the address of the string to be set, a default value for the string, and a help description. The flag definition function has three arguments, the option name, the address of flag to be set, and a help description. The default value for flags is always false. The integer definition functions have five arguments, the option name, the address of number to be set, a default value for the number, the base to be used, and a help description. The two real number definitions have four arguments, the option name, the address of the real number to be set, a default value, and a help description. The three special file definition functions corresponding to stdin, stdout, and stderr have three arguments, the option name, the address of a FILE pointer, and a help description. The default value for the FILE pointer is the corresponding standard file. The general file definition function has four arguments. The first is the option name, the second is address of the FILE pointer, the third is the mode in which the file is to be opened, and a help description. The default for the FILE pointer is a null pointer. RANGE CHECKING For each numeric type there is are three corresponding range validation routines, set a minimum, set a maximum, and set a range. The min and max routines have two arguments, the option name, and the value. The range routines have three arguments, the option name, the minimum, and the maximum. ALIAS DEFINITION An alias is an option name that, when processed, is replaced by a string that is parsed into argc/argv form that is then processed. Aliases are created with the opt_define_alias function which has two arguments, the alias option name and the aliased string. An alias string can contain other aliases. However an alias cannnot be directly or indirectly self-referential. OPTION PROCESSING There is one routine for processing command line arguments, optproc. Its arguments are argc and argv. It processes all arguments and returns the list of arguments that are not options and option values. Options and their values are presumed to be ahead of other arguments. The first argument that is not an option (or an option value) is treated as the first non-option argument. CONTEXT DEFINITION AND SWITCHING Contexts are specified by strings used as context labels. The default context has the empty string label. The opt_set_context function sets the current context to the context specified by its argument. All newly established contexts are empty, i.e., they have no defined options. Option definitions can be copied from one context to another with the opt_copy_options function. Options can be culled from a context with the opt_delete_option function. */ #ifndef utl_optproc_include #define utl_optproc_include 1 /* option definition functions */ void opt_define_string (char *key,char **string,char *initval, char *descr); void opt_define_flag (char *key,int * flag, char *descr); void opt_define_file (char *key,FILE **path, char *mode, char *descr); void opt_define_infile (char *key,FILE **path, char *descr); void opt_define_outfile(char *key,FILE **path, char *descr); void opt_define_errfile(char *key,FILE **path, char *descr); void opt_define_short (char *key,short * ivar, short def, int base,char *descr); void opt_define_int (char *key,int * ivar, int def, int base, char *descr); void opt_define_long (char *key,long * lvar, long def, int base, char *descr); void opt_define_float (char *key,float * fvar, float def, char *descr); void opt_define_double (char *key,double * dvar, double def, char *descr); void opt_define_alias (char *key,char * alias, char *descr); void opt_define_ushort (char *key, unsigned short * ivar, unsigned short def, int base,char *descr); void opt_define_uint (char *key, unsigned int * ivar, unsigned int def, int base, char *descr); void opt_define_ulong (char *key, unsigned long * lvar, unsigned long def, int base, char *descr); /* functions to set variable min, max, and range */ void opt_set_min_short (char *key, short minval); void opt_set_max_short (char *key, short maxval); void opt_set_range_short (char *key, short minval, short maxval); void opt_set_min_int (char *key, int minval); void opt_set_max_int (char *key, int maxval); void opt_set_range_int (char *key, int minval, int maxval); void opt_set_min_long (char *key, long minval); void opt_set_max_long (char *key, long maxval); void opt_set_range_long (char *key, long minval, long maxval); void opt_set_min_ushort (char *key, unsigned short minval); void opt_set_max_ushort (char *key, unsigned short maxval); void opt_set_range_ushort(char *key, unsigned short minval, unsigned short maxval); void opt_set_min_uint (char *key, unsigned int minval); void opt_set_max_uint (char *key, unsigned int maxval); void opt_set_range_uint (char *key, unsigned int minval, unsigned int maxval); void opt_set_min_ulong (char *key, unsigned long minval); void opt_set_max_ulong (char *key, unsigned long maxval); void opt_set_range_ulong (char *key, unsigned long minval, unsigned long maxval); /* option context functions */ void opt_set_context (char *context_name); void opt_copy_options (char *src, char *dest); void opt_delete_option(char *key); /* option processing functions */ int optproc(int, char **); /* option cleanup functions */ void opt_clear(void); #endif