GRASS Programmer's Manual  6.4.2(2012)
opt.h
Go to the documentation of this file.
00001 /* LIBDGL -- a Directed Graph Library implementation
00002  * Copyright (C) 2002 Roberto Micarelli
00003  *
00004  * This program is free software; you can redistribute it and/or modify
00005  * it under the terms of the GNU General Public License as published by
00006  * the Free Software Foundation; either version 2 of the License, or
00007  * (at your option) any later version.
00008  *
00009  * This program is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00012  * GNU General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU General Public License
00015  * along with this program; if not, write to the Free Software
00016  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
00017  */
00018 
00019 /* best view tabstop=4
00020  */
00021 
00022 /*@*********************************************************************
00023  * @pack:       GNO_PACK
00024  * @descr:      Command line options utility.
00025  *
00026  * @notes:      Support to easily parse command line options. Some concepts
00027  *                      were taken from the posix getopt() family functions, while
00028  *                      our specific experience in C programming suggested us a
00029  *                      proprietary implementation to make source code more readable
00030  *                      at life easier (I hope).
00031  *                      Option format:
00032  *
00033  *                      syntax                          name
00034  *                      ----------------------------------------------
00035  *                      --option=value          long-parametric
00036  *                      --option                        long-boolean
00037  *                      -option value           short-parametric
00038  *                      -option                         short-boolean
00039  *
00040  *              C sample:
00041  *              ----------------------------------------------
00042  *              #include <stdio.h>
00043  *              #include <opt.h>
00044  *
00045  *              int main( int argc , char ** argv )
00046  *              {
00047  *                      Boolean         fHelp;
00048  *                      Boolean         fTcp;
00049  *                      Boolean         fUdp;
00050  *                      char    *       pszProtocol;
00051  *                      char    *       pszInterface;
00052  *                      int                     i;
00053  *
00054  *                      GNO_BEGIN
00055  *                      GNO_SWITCH( "h", "help", False , & fHelp , "Print this help." )
00056  *                      GNO_SWITCH( "t", "tcp", False , & fTcp , NULL )
00057  *                      GNO_SWITCH( "u", "udp", False , & fUdp , NULL )
00058  *                      GNO_OPTION( "p", "protocol", "tcp" , & pszProtocol , NULL )
00059  *                      GNO_OPTION( "i", "interface", "eth0" , & pszInterface , NULL )
00060  *                      GNO_END
00061  *
00062  *
00063  *                      if ( GNO_PARSE( argc , argv ) < 0 )
00064  *                      {
00065  *                              return 1;
00066  *                      }
00067  *
00068  *                      if ( fHelp == True )
00069  *                      {
00070  *                              GNO_HELP( "t_opt usage" );
00071  *                              return 0;
00072  *                      }
00073  *
00074  *                      printf ( "t/tcp  = %s\n", (fTcp  == True) ? "True" : "False" );
00075  *                      printf ( "u/udp  = %s\n", (fUdp  == True) ? "True" : "False" );
00076  *                      printf ( "p/protocol  = <%s>\n", pszProtocol );
00077  *                      printf ( "i/interface = <%s>\n", pszInterface );
00078  *
00079  *                      GNO_FREE();
00080  *
00081  *                      printf( "orphan options:\n" );
00082  *
00083  *                      for ( i = 0 ; i < argc ; i ++ )
00084  *                      {
00085  *                              if ( argv[ i ] )
00086  *                              {
00087  *                                      printf( "arg %d: %s\n", i, argv[i ] );
00088  *                              }
00089  *                              else
00090  *                              {
00091  *                                      printf( "arg %d: --\n", i );
00092  *                              }
00093  *                      }
00094  *                      return 0;
00095  *              }
00096  *                                              
00097  **********************************************************************/
00098 
00099 #ifndef _GNOPT_H_
00100 #define _GNOPT_H_
00101 
00102 #ifdef __cplusplus
00103 extern "C"
00104 {
00105 #endif
00106 
00107 /***********************************************************************
00108  *                              DEFINES
00109  **********************************************************************/
00110     /*@*--------------------------------------------------------------------
00111      * @defs:       GNO_FLG
00112      * @descr:      flags used to set the nFlg field in the GnoOption_s
00113      *                      SWITCH    = boolean option required
00114      *
00115      * @see:        GnoOption_s
00116      *
00117      *--------------------------------------------------------------------*/
00118 
00119 #define GNO_FLG_SWITCH          0x01
00120 
00121     /*@*--------------------------------------------------------------------
00122      * @defs:       True/False
00123      * @descr:      one more useful (?) true/false definition
00124      *
00125      *--------------------------------------------------------------------*/
00126 #define True  1
00127 #define False 0
00128 
00129 /***********************************************************************
00130  *                              STRUCTS/UNIONS/TYPES/FUNCDEFS
00131  **********************************************************************/
00132     /*@*--------------------------------------------------------------------
00133      * @type:       Boolean
00134      * @descr:      wasn't it better to use 'int'?
00135      *--------------------------------------------------------------------*/
00136     typedef int Boolean;
00137 
00138     /*@*--------------------------------------------------------------------
00139      * @type:       GnoOption_s
00140      * @descr:      This structure describes an option. We intend to use an array
00141      *          of GnoOption_s, terminated by a 'NULL' entry (one containing
00142      *                      all binary-zero fields), and to pass it to GnoParse() together
00143      *                      with the typical argc,argv couple of main() args. The array's
00144      *                      entries are looked-up and filled with coherent argc,argv
00145      *                      values. Some fields are statically filled by user while other
00146      *                      are returned by the GnoParse() function.
00147      *                      Fields set by the user:
00148      *
00149      *                      nFlg      = So far the only supported flag is GNO_FLG_SWITCH
00150      *                                  to address a boolean option type.
00151      *                      fDef      = The default value for a boolean option.
00152      *                      pszDef    = The default value for a parametric option.
00153      *                      pszShort  = The short name of the option.
00154      *                      pszLong   = The long name of the option.
00155      *                      pfValue   = Pointer to a boolean option return value.
00156      *                      ppszValue = Pointer to a parametric option return value.
00157      *                      pszDescr  = A brief option description
00158      *
00159      *                      Fields set by GnoParse():
00160      *
00161      *                      iArg       = argv option index
00162      *                      *ppszValue = pointer to parametric option value 
00163      *                      *pfValue   = True/False
00164      *
00165      *                      User supplied fields are mandatory only within specific
00166      *                      conditions:
00167      *
00168      *                      - at least one of pszShort/pszLong must be specified
00169      *                      - fDef and pfValue apply to a boolean option only
00170      *                      - pszDef and ppszValue apply to a parametric option only
00171      *                      - pszDescr is optional
00172      *
00173      * @see:        GnoParse(), GNO_FLG
00174      *
00175      *--------------------------------------------------------------------*/
00176 
00177     typedef struct GnoOption
00178     {
00179         int iArg;               /* returned argv option index */
00180         int nFlg;               /* flags describing the option */
00181         Boolean fDef;           /* default returned value for a boolean option */
00182         char *pszDef;           /* default returned value for a parametric option */
00183         char *pszShort;         /* short-option recogniser */
00184         char *pszLong;          /* long-option recogniser */
00185         Boolean *pfValue;       /* address to return a boolean option */
00186         char **ppszValue;       /* address to return a parametric option */
00187         char *pszDescr;         /* a brief option description */
00188 
00189     } GnoOption_s;
00190 
00191 
00192 /***********************************************************************
00193  *                              MACROS
00194  **********************************************************************/
00195     /*@*--------------------------------------------------------------------
00196      *
00197      * @macro:      GNO_BEGIN
00198      * @descr:      Begin an option array declaration
00199      * 
00200      * @notes:      The best use is to start option declaration immediately after
00201      *                      the automatic-variable declaration in the main() function.
00202      *
00203      *--------------------------------------------------------------------*/
00204 #define GNO_BEGIN GnoOption_s _aopt[] = {
00205 
00206     /*@*--------------------------------------------------------------------
00207      *
00208      * @macro:      GNO_OPTION
00209      * @descr:      Declare a parametric option
00210      *
00211      * 
00212      * @args:       I:      chsopt  =       short option character
00213      *                      I:      pszlopt ->      long option psz
00214      *                      I:      pszdef  ->      default-returned psz
00215      *                      I:      ppszv   ->      user-addressed return variable pointer
00216      *
00217      *--------------------------------------------------------------------*/
00218 #define GNO_OPTION(pszsopt,pszlopt,pszdef,ppszv,pszdescr) \
00219                         { 0, 0, 0, pszdef, pszsopt, pszlopt, NULL, ppszv, pszdescr },
00220 
00221     /*@*--------------------------------------------------------------------
00222      *
00223      * @macro:      GNO_SWITCH
00224      * @descr:      Declare a boolean option
00225      * 
00226      * @args:       I:      chsopt  =       short option character
00227      *                      I:      pszlopt ->      long option psz
00228      *                      I:      fdef    =       default-returned Boolean
00229      *                      I:      pfv             ->      user-addressed return variable pointer
00230      *
00231      *--------------------------------------------------------------------*/
00232 #define GNO_SWITCH(pszsopt,pszlopt,fdef,pfv,pszdescr) \
00233                         {       \
00234                                 0, \
00235                                 GNO_FLG_SWITCH, \
00236                                 fdef, NULL, \
00237                                 pszsopt, pszlopt, \
00238                                 pfv, NULL, \
00239                                 pszdescr \
00240                         },
00241 
00242     /*@*--------------------------------------------------------------------
00243      *
00244      * @macro:      GNO_PARSE
00245      * @descr:      Parse a GnoOption_s array declaration
00246      * 
00247      * @args:       I:      argc    =       count of argv entries
00248      *                      I:      argv    ->      array of sz pointers
00249      *
00250      *--------------------------------------------------------------------*/
00251 #define GNO_PARSE(argc,argv) GnoParse( (argc), (argv), _aopt )
00252 
00253     /*@*--------------------------------------------------------------------
00254      *
00255      * @macro:      GNO_END
00256      * @descr:      Terminate an option array declaration
00257      * 
00258      *--------------------------------------------------------------------*/
00259 #define GNO_END { 0, 0, 0, NULL, NULL, NULL, NULL, NULL, NULL } };
00260 
00261     /*@*--------------------------------------------------------------------
00262      *
00263      * @macro:      GNO_HELP
00264      *
00265      * @descr:      Print a brief option's help on the standard error
00266      *
00267      * @args:       I:      pszhead ->      help header string
00268      * 
00269      *--------------------------------------------------------------------*/
00270 #define GNO_HELP(pszhead) GnoHelp( pszhead , _aopt )
00271 
00272     /*@*--------------------------------------------------------------------
00273      *
00274      * @macro:      GNO_FREE
00275      *
00276      * @descr:      Free resources created by a previously parsed array
00277      *
00278      * 
00279      *--------------------------------------------------------------------*/
00280 #define GNO_FREE() GnoFree( _aopt )
00281 
00282 
00283 /***********************************************************************
00284  *                              FUNCTION PROTOTYPES
00285  **********************************************************************/
00286 
00287     extern int GnoParse(int argc, char **argv, GnoOption_s * pOpt);
00288 
00289     extern void GnoFree(GnoOption_s * pOpt);
00290 
00291     extern void GnoHelp(char *pszHead, GnoOption_s * pOpt);
00292 
00293 
00294 #ifdef __cplusplus
00295 }
00296 #endif
00297 
00298 #endif                          /* top of file */
00299 
00300 /***************************** END OF FILE ****************************/
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines