Main Page | Compound List | File List | Compound Members | File Members

parse_options.h

Go to the documentation of this file.
00001 /*
00002  *  Copyright (c) KONINKLIJKE PHILIPS ELECTRONICS N.V. 2000-2006
00003  *  All rights reserved.
00004  *  For licensing and warranty information, see the file COPYING.LGPLv21.txt
00005  *  in the root directory of this package.
00006  *
00007  *  Philips Research Laboratories
00008  *  Eindhoven, The Netherlands
00009  *
00010  *  CVS id      :  $Id: parse_options.h,v 1.2 2006/02/06 12:57:49 kock Exp $
00011  *
00012  *  Origin      :  This file originates from package mtk at
00013  *                 http://sourceforge.net/projects/pfspd
00014  *
00015  */
00016 
00017 #ifndef PARSE_OPTIONS_H_INCLUDED
00018 #define PARSE_OPTIONS_H_INCLUDED
00019 
00020 #include <stdio.h>
00021 
00022 typedef struct
00023 {
00024     char *name;
00025     char *type;
00026     char *default_value;
00027     void *var;
00028     char *help;
00029 } option_t;
00030 
00031 /*----------------------------------------------------------------------------
00032  *
00033  *  SHORT MANUAL
00034  *
00035  *  We distinguish between "arguments" and "options". A option looks
00036  *  like "-name", possibly followed by a value, i.e. "-name value".
00037  *  All argv[i] not covered by options are arguments.
00038  *
00039  *  For arguments, the name shall NOT start with a hyphen. The name is only
00040  *  used for printing the help text. The type shall be "str", "strlist" or
00041  *  "[strlist]". The default value shall be NULL (i.e. arguments are always
00042  *  mandatory!)
00043  *
00044  *  For options default may be non-NULL. In this case it must be a constant
00045  *  string, representing the string the user would have typed. When the default
00046  *  value is NULL, the option is mandatory.
00047  *
00048  *  Memory allocation:
00049  *    Memory for string options is allocated dynamically. Strings from the
00050  *    command-line or ini-file are copied into this memory and the allocated
00051  *    memory pointer is returned to the application. This is necessary when
00052  *    the string was read from an ini-file.
00053  *    Note: this memory is not explicitly freed since parse_options can
00054  *          not determine when you don't need the memory anymore.
00055  *
00056  *  Possible types:
00057  *    cmd            The variable should be an "int". This types is similar
00058  *                   to "bool", but when given it overrules all other options.
00059  *                   At most one command option may be specified.
00060  *    str            The variable should be a "char *"
00061  *    str{a,b,c,d,e} The variable should be an "char *". The user must supply
00062  *                   a string from the set.
00063  *    strlist        The variable should be a "char **". This type can only
00064  *                   be used for arguments (not options). The user must supply
00065  *                   at least one argument. After parsing, the variable will
00066  *                   contain a list of strings. The end is marked with a
00067  *                   NULL string.
00068  *    [strlist]      The variable should be a "char **". Simular to "strlist",
00069  *                   but now the string list may be empty (i.e. the first
00070  *                   string is already NULL).
00071  *    enum           The variable should be an "int". The user must supply a
00072  *                   string from the set, which should be encoded as
00073  *                   {-s1,-s2,..,-sn} in the "option.name" string.
00074  *    bool           The variable should be an "int". When a boolean option
00075  *                   "-filter" exists, the user may also enter "-no-filter"
00076  *                   which sets the boolean to false. The default value
00077  *                   "true" set the default to true (1), everything else
00078  *                   sets the default to false (0).
00079  *
00080  *    int            The variable should be an "int". The user must supply
00081  *                   an integer value. Without prefix, it is in decimal
00082  *                   notation; a 0X or 0x denotes hexadecimal notation.
00083  *    int[min,max]   The variable should be an "int". The user must supply a
00084  *                   value between min and max (including boundaries).
00085  *                   Again, it is either decimal or hexadecimal.
00086  *    int{a,b,c,d,e} The variable should be an "int". The user must supply
00087  *                   a string from the set. It is translated to a value 0,1,...
00088  *                   according to the position of the string in the set.
00089  *    double         The variable should be a "double".
00090  *    float          The variable should be a "float".
00091  *    char           The variable should be a "char"
00092  *
00093  *
00094  *    type#n         The variable should be type[n] (array of n items of type).
00095  *                   The user must supply a list of n items, each seperated by a
00096  *                   comma. This construction is only supported for types:
00097  *                      "int"            ->  "int#n"
00098  *                      "int{a,b,..}"    ->  "int{a,b,..}#n"
00099  *                      "int[min,max]"   ->  "int[min,max]#n"
00100  *                      "double".        ->  "double#n".
00101  *                   Example: for "int[0,10]#2", the user must supply
00102  *                   two values, like "2,6".
00103  *
00104  *
00105  *  The option list must be closed with an all-NULL line (See below)
00106  *
00107  * Example option table:
00108  *
00109  *       Name          Type              Default  Variable addr  Description text
00110  *
00111  * option_t options[] =
00112  * {
00113  *     { "-help",      "cmd",            NULL,    &cmdl.help,    "Print a help text"            },
00114  *     { "-readme",    "cmd",            NULL,    &cmdl.readme,  "Print the readme text file"   },
00115  *     { "-version",   "cmd",            NULL,    &cmdl.version, "Print the version"            },
00116  *     { "-verbose",   "bool",           "false", &verbose,      "Verbose printing"             },
00117  *     { "arg1",       "str",            NULL,    &arg1,         "Input file"                   },
00118  *     { "args2" ,     "[strlist]",      NULL,    &args2,        "Special files"                },
00119  *     { "arg3" ,      "str",            NULL,    &arg3,         "Output file 1"                },
00120  *     { "arg4" ,      "str",            NULL,    &arg4,         "Output file 2"                },
00121  *     { "-age",       "int",            "23",    &age,          "Age of the user"              },
00122  *     { "-day",       "int[0,31]",      NULL,    &day,          "Day of use"                   },
00123  *     { "-pi",        "double",         "3.14",  &pi,           "Definition of PI"             },
00124  *     { "-weight",    "float",          NULL,    &weight,       "Weight of user"               },
00125  *     { "-initial",   "char",           NULL,    &initital,     "First initial of user"        },
00126  *     { "-outtype",   "str{pfspd,pgm}", "pfspd", &outtype,      "Output type"                  },
00127  *     { "-phase",     "int{a,b,c,d,e}", NULL,    &phase,        "Phase"                        },
00128  *     { "-coefs",     "int#4",          NULL,    &coefs,        "Filter coefs"                 },
00129  *     { "{-a,-b,-c}", "enum",           "-b",    &mode,         "Conversion mode"              },
00130  *     { NULL,         NULL,             NULL,    NULL,          NULL                           }
00131  * };
00132  *
00133  * Example executions:
00134  *
00135  *   example -help
00136  *     Print the help text
00137  *
00138  *   example -readme
00139  *     Print the readme text
00140  *
00141  *   example -version
00142  *     Print the version string(s)
00143  *   
00144  *   example in out1 out2 -day 11
00145  *
00146  *   The following options were given by the user:
00147  *  in  out1 out2 -age 23 -day 11 -pi 3.1400 -no-verbose -outtype pfspd -b
00148  *
00149  *   example in out1 out2 -day 11 -pi 4.2 -verbose
00150  *
00151  *   The following options were given by the user:
00152  *  in  out1 out2 -age 23 -day 11 -pi 4.2000 -verbose -outtype pfspd -b
00153  *
00154  *   example in f1 f2 f3 out1 out2 -day 11 -pi 4.2 -verbose
00155  *
00156  *   The following options were given by the user:
00157  *  in f1 f2 f3 out1 out2 -age 23 -day 11 -pi 4.2000 -verbose -outtype pfspd -b
00158  *
00159  *
00160  * INI-FILES
00161  *
00162  * Two ini-file formats are supported:
00163  *
00164  * 1) standard
00165  *    The syntax of the ini-file is the same as that of the command line, except
00166  *    that options are not placed on one line but each on seperate lines. The '#'
00167  *    character denotes a comment in the ini file.
00168  *
00169  * 2) windows
00170  *    Ini-files containing '[xxx]' in the first non-empty line are interpreted
00171  *    according the Windows format (xxx: any text). Lines may contain
00172  *    [<heading>] or <name>=<val> or may be empty. The option names and values
00173  *    are converted to argc/argv format and parsed by _parse_options. Lines are
00174  *    interpreted as follows:
00175  *
00176  *       [arguments]    subsequent lines are treated as arguments
00177  *       <name>=<val>   <val> is added to argv
00178  *                      ignored
00179  *       [<heading>]    subsequent lines are treated as options
00180  *       <name>=        ignored
00181  *       <name>         error
00182  *       =<val>         error
00183  *       <name>=true    -<name> is added to argv
00184  *       <name>=false   -no-<name> is added to argv
00185  *       <name>=<val>   -<name> <val> is added to argv
00186  *
00187  *    Additional rules:
00188  *
00189  *       Arguments must appear in the order expected by the application.
00190  *       Options and [] sections may appear in any order.
00191  *       The <heading> string only distinguishes between arguments and options.
00192  *       The <name> string may be preceded by spaces and/or tabs.
00193  *       The <val> string may contains spaces.
00194  *       There may be spaces and/or tabs between <name>, =, and <val>.
00195  *       Any line may end with a comment starting with '#'.
00196  *       Comments may be preceded by spaces and/or tabs.
00197  *----------------------------------------------------------------------------
00198  */
00199 
00200 #ifdef __cplusplus
00201 extern "C" {
00202 #endif /* __cplusplus */
00203 
00204 /*
00205  * Print a list of all arguments and options
00206  * to a string (sprint), file (fprint) or stdout (print).
00207  *
00208  * Arguments:
00209  * s          String used to write the result
00210  * len        Number of bytes available in s
00211  * f          File pointer, opened for writing
00212  * appl_name  Name of the application
00213  * options    Specification of the options
00214  *
00215  * Return value:
00216  *     success: 1, failure: 0
00217  */
00218 extern int sprint_options(char *s, int len, char *appl_name, option_t options[]);
00219 extern int fprint_options(FILE *f, char *appl_name, option_t options[]);
00220 extern int print_options(char *appl_name, option_t options[]);
00221 
00222 /*
00223  * Print a list of the values of all arguments and options
00224  * to a string (sprint), file (fprint) or stdout (print).
00225  *
00226  * Note: Command options are not printed. This functions is
00227  *       intended to be used when normal arguments/options are given.
00228  *
00229  * Arguments:
00230  * s          String used to write the result
00231  * len        Number of bytes available in s
00232  * f          File pointer, opened for writing
00233  * prefix     String at beginning of printing
00234  * options    Specification of the options
00235  *
00236  * Return value:
00237  *     success: 1, failure: 0
00238  */
00239 extern int sprint_option_values(char *s, int len, char *prefix, option_t options[]);
00240 extern int fprint_option_values(FILE *f, char *prefix, option_t options[]);
00241 extern int print_option_values(char *prefix, option_t options[]);
00242 
00243 /*
00244  * Parse ini-file and command line.
00245  * In case of incorrect options, error messages are printed
00246  * to stderr.
00247  *
00248  * Arguments:
00249  * appl_name  Name of the application; used in error printing.
00250  * argc       Length of the "argv" array.
00251  * argv[]     List of strings.
00252  * options    The list of possible options/arguments
00253  *
00254  * Return value:
00255  *     success: zero, failure: non-zero
00256  */
00257 extern int parse_options(char *appl_name, int argc, char *argv[], option_t options[]);
00258 
00259 #ifdef __cplusplus
00260 } /* extern "C" */
00261 #endif /* __cplusplus */
00262 
00263 #endif /* end of #ifndef PARSE_OPTIONS_H_INCLUDED */

Generated on Wed Feb 15 14:52:42 2006 for util by doxygen 1.3.2