opt.doc

这是一款很好用的工具包

_________________________________________________________________

NNAAMMEE
     Opt_Parse, Opt_PrintUsage - Manage command line options

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ooppttiioonn..hh>>

     int OOpptt__PPaarrssee(_a_r_g_c_, _a_r_g_v_, _o_p_t_i_o_n_A_r_r_a_y_, _n_u_m_O_p_t_i_o_n_s_, _f_l_a_g_s)

     void OOpptt__PPrriinnttUUssaaggee(_c_o_m_m_a_n_d_N_a_m_e_, _o_p_t_i_o_n_A_r_r_a_y_, _n_u_m_O_p_t_i_o_n_s)

AARRGGUUMMEENNTTSS
     int      _a_r_g_c           (in)      Number   of  arguments  on
                                       command line.

     char     _*_*_a_r_g_v         (in/out)  Command   line   arguments
                                       passed to main program.

     char     _*_c_o_m_m_a_n_d_N_a_m_e   (in)      Name  of the program being
                                       run, usually _a_r_g_v[0].

     Option   _*_o_p_t_i_o_n_A_r_r_a_y   (in)      An   array    of    option
                                       descriptions.

     int      _n_u_m_O_p_t_i_o_n_s     (in)      Number   of   elements  in
                                       optionArray,       usually
                                       obtained     using     the
                                       OOpptt__NNuummbbeerr   macro,   e.g.
                                       OOpptt__NNuummbbeerr(optionArray).

     int      _f_l_a_g_s          (in)      If non-zero, then it spec-
                                       ifies one  or  more  flags
                                       that  control  the parsing
                                       of  arguments.   Different
                                       flags    may    be   OR'ed
                                       together.  The only  flags
                                       currently    defined   are
                                       OPT_ALLOW_CLUSTERING   and
_______________________________________O_P_T___O_P_T_I_O_N_S___F_I_R_S_T_._________

DDEESSCCRRIIPPTTIIOONN
     OOpptt__PPaarrssee  parses  the  command  line arguments of a program
     according to an array of option descriptions.  Starting with
     _a_r_g_v[1], it parses as many options as it can and returns the
     rest of the options in the  _a_r_g_v  array,  compacted  to  the
     beginning  of the array (starting with _a_r_g_v[1]).  The return
     value indicates how many options are returned  in  the  _a_r_g_v
     array  (including  _a_r_g_v[0]).  Opt_Parse returns options that
     don't start with ``-'' unless they are arguments for options
     that  it parses.  OOpptt__PPaarrssee also returns any options follow-
     ing an OOPPTT__RREESSTT option (see below for more details).

     Each element of the  array  _o_p_t_i_o_n_A_r_r_a_y  has  the  following
     structure: ttyyppeeddeeff ssttrruucctt Option {
         iinntt _t_y_p_e;
         cchhaarr*_k_e_y;
         cchhaarr*_v_a_l_u_e_P_t_r;
         cchhaarr*_d_o_c_M_s_g; } Option;

     The  _k_e_y field is a string that identifies this option.  For
     example, if _k_e_y is ffoooo, then this Option will match  a  --ffoooo
     command-line option.  If _k_e_y is the empty string (``'') then
     it matches a -- command-line option.  If  _k_e_y  is  NULL,  the
     Option will not match any command-line options (this feature
     is  only  useful  for  OPT_DOC  options).    _D_o_c_M_s_g   is   a
     documentation string to print out as part of a help message.
     The _t_y_p_e field determines what to do  when  this  Option  is
     matched.   It  also  determines  the meaning of the _v_a_l_u_e_P_t_r
     field.  _T_y_p_e should always be specified  using  one  of  the
     following macros:

     OOPPTT__TTRRUUEE
          Treats  _v_a_l_u_e_P_t_r  as  the  address  of  an integer, and
          stores the value 1 in that integer.

     OOPPTT__FFAALLSSEE
          Treats _v_a_l_u_e_P_t_r as the address of an integer and stores
          the value 0 in that integer.

     OOPPTT__CCOONNSSTTAANNTT(_v_a_l_u_e)
          This  is  a generalized form of OPT_TRUE and OPT_FALSE.
          Treats _v_a_l_u_e_P_t_r as the address of an integer and stores
          _v_a_l_u_e  in that integer.  _V_a_l_u_e must be a positive inte-
          ger.

     OOPPTT__IINNTT
          The next argument after the one matching _k_e_y must  con-
          tain an integer string in the format accepted by ssttrrttooll
          (e.g. ``0'' and ``0x'' prefixes may be used to  specify
          octal  or hexadecimal numbers, respectively).  _V_a_l_u_e_P_t_r
          will be treated as the address of an integer,  and  the
          value  given by the next argument will be stored there.

     OOPPTT__TTIIMMEE
          The next argument after the one matching _k_e_y must  con-
          tain  a  string  that  is  parsable as a date and time.
          Currently, only two formats are recognized: _s_e_c_o_n_d_s

          and _y_y.._m_m.._d_d.._h_h.._m_m.._s_s

          The first form is simply the number  of  seconds  since
          the  start  of the epoch (1 January 1970, 0 hours GMT).
          The second form specifies the year (e.g., 91 or  1991),
          month  (1-12),  day of the month, hours (0-23), minutes
          (0-59), and seconds (0-59).  All fields must be  speci-
          fied.   _V_a_l_u_e_P_t_r  will  be  treated as the address of a
          ttiimmee__tt (defined in <<ttiimmee..hh>>), and the given  time  will
          be stored there.  All times are in terms of the current
          timezone and daylight savings rules.

          Note that this flavor can  clobber  the  static  buffer
          used by the llooccaallttiimmee library routine.

     OOPPTT__FFLLOOAATT
          The  next argument after the one matching _k_e_y must con-
          tain a floating-point number in the format accepted  by
          ssttrrttooll.   _V_a_l_u_e_P_t_r will be treated as the address of an
          double-precision floating point value,  and  the  value
          given by the next argument will be stored there.

     OOPPTT__SSTTRRIINNGG
          Treats  _v_a_l_u_e_P_t_r  as  the  address  of  a (char *), and
          stores a pointer to the next argument in  the  location
          pointed to by _v_a_l_u_e_P_t_r.
     OOPPTT__DDOOCC
          This  option is intended primarily as a way of printing
          extra documentation during help message printouts.   It
          isn't  normally  used as an actual option (and normally
          its _k_e_y field is NULL).  If it is invoked as an option,
          then  the  same thing happens as for the ``-?'' option:
          descriptions get printed for all options in _o_p_t_i_o_n_A_r_r_a_y
          and OOpptt__PPaarrssee calls exit(0) to terminate the process.

     OOPPTT__RREESSTT
          This  option  is  used  by programs that allow the last
          several of their options to be the name and/or  options
          for  some  other  program.   If  an  OOPPTT__RREESSTT option is
          found,  then  OOpptt__PPaarrssee  doesn't  process  any  of  the
          remaining arguments;  it returns them all at the begin-
          ning of _a_r_g_v.  In addition, OOpptt__PPaarrssee  treats  _v_a_l_u_e_P_t_r
          as  the address of an integer value, and stores in that
          value the index of the first of the OOPPTT__RREESSTT options in
          the  returned _a_r_g_v.  This allows the program to distin-
          guish  the  OOPPTT__RREESSTT  options  from  other  unprocessed
          options that preceeded the OOPPTT__RREESSTT.

     OOPPTT__FFUUNNCC
          When  one  of these options is encountered, _v_a_l_u_e_P_t_r is
          treated as the address of  a  function  which  is  then
          called   with   the  following  calling  sequence:  iinntt
          _f_u_n_c_(_o_p_t_S_t_r_i_n_g_, _n_e_x_t_A_r_g_)
              cchhaarr    *_o_p_t_S_t_r_i_n_g;
              cchhaarr    *_n_e_x_t_A_r_g; { }

          The _o_p_t_S_t_r_i_n_g parameter points to the  current  option,
          and  _n_e_x_t_A_r_g  points  to  the next option from _a_r_g_v (or
          NULL if there aren't any more options in _a_r_g_v.  If _f_u_n_c
          uses  _n_e_x_t_A_r_g  as an argument to the current option (so
          that Opt_Parse should skip it), then it  should  return
          1.  Otherwise it should return 0.

     OOPPTT__GGEENNFFUUNNCC
          Treat  _v_a_l_u_e_P_t_r  as  the address of a function and pass
          all of the remaining arguments to it in  the  following
          way: iinntt _g_e_n_f_u_n_c_(_o_p_t_S_t_r_i_n_g_, _a_r_g_c_, _a_r_g_v_)
              cchhaarr    *_o_p_t_S_t_r_i_n_g;
              iinntt _a_r_g_c;
              cchhaarr    **_a_r_g_v; { }

          _A_r_g_c and _a_r_g_v refer to all of the options after the one
          that triggered the call, and _o_p_t_S_t_r_i_n_g  points  to  the
          triggering  option.  _G_e_n_f_u_n_c should behave in a fashion
          similar to OOpptt__PPaarrssee:  parse as many of  the  remaining
          arguments  as  it can, then return any that are left by
          compacting them to the beginning of _a_r_g_v  (starting  at
          _a_r_g_v[0]).   _G_e_n_f_u_n_c  should  return a count of how many
          arguments are left  in  _a_r_g_v_;  OOpptt__PPaarrssee  will  process
          them.


FFLLAAGGSS
     OOPPTT__AALLLLOOWW__CCLLUUSSTTEERRIINNGG
          This  will  permit  several  options  to  be  clustered
          together with a single ``-'', e.g., ``foo  -abc''  will
          be   handled   the  same  way  as  ``foo  -a  -b  -c''.
          OPT_ALLOW_CLUSTERING  is  likely  to  cause   confusing
          behavior unless each option is identified with a single
          character.


     OOPPTT__OOPPTTIIOONNSS__FFIIRRSSTT
          This causes OOpptt__PPaarrssee to stop parsing the command  line
          anytime  something  that  is not an option is detected.
          Thus, a program that takes some options followed  by  a
          command  to execute (along with that command's options)
          can parse  its  own  options  using  OPT_OPTIONS_FIRST.
          When the command to execute is encountered, assuming it
          does not begin with a hyphen, OOpptt__PPaarrssee will return the
          command and its arguments starting at _a_r_g_v[1], ignoring
          any arguments with hyphens  following  the  first  non-
          option.

UUSSAAGGEE MMEESSSSAAGGEE
     OOpptt__PPrriinnttUUssaaggee  may be invoked to print out all the documen-
     tation strings (plus option names and default values) for  a
     command's options.  If OOpptt__PPaarrssee encounters an option ``-?''
     or ``-help'', then it will  call  OOpptt__PPrriinnttUUssaaggee  and  exit.
     Note:   in  some  shells  the  question-mark must be escaped
     (e.g., ``foo -\?'' in _c_s_h).


EEXXAAMMPPLLEE
     Here is an example definition of a set  of  option  descrip-
     tions  and  some  sample command lines that use the options.
     Note the effect on argc and argv;   command  arguments  that
     get  interpreted  as options or option values are eliminated
     from argv, and argc is updated to reflect reduced number  of
     arguments.  /*
      * Define and set default values for globals.
      */  Boolean  debugFlag  =  FALSE;  int  numReps = 100; char
     defaultFileName[] = "out"; char *fileName = defaultFileName;
     Boolean exec = FALSE;

     /*
      * Define option descriptions.
      */ Option optionArray[] = {
         OPT_TRUE,  "X",  (char *) &debugFlag, "Turn on debugging
     printfs",
         OPT_INT, "N", (char  *)  &numReps,  "Number  of  repeti-
     tions",
         OPT_STRING, "of", (char *) &fileName, "Output filename",
         OPT_REST, "x", (char *) &exec,
             "File to exec, followed by any  arguments  (must  be
     last argument).", };

     main(argc, argv)
         int argc;
         char *argv[]; {
         Opt_Parse(argc,            argv,            optionArray,
     Opt_Number(optionArray),
                 OPT_ALLOW_CLUSTERING);

         /*
          * the rest of the program.
          */ }

     Note that default values can be  assigned  to  option  vari-
     ables.   Also, numOptions gets calculated by the compiler in
     this example.  Here are some example command lines and their
     effects.   prog  -N  200 infile      # just sets the numReps
     variable to 200 prog -of out200 infile  # sets  fileName  to
     reference  "out200" prog -XN 10 infile      # sets the debug
     flag, also sets numReps In all of the  above  examples,  the
     return  value  from  Opt_Parse  will  be  2, _a_r_g_v[0] will be
     ``prog'', _a_r_g_v[1] will be ``infile'', and  _a_r_g_v[2]  will  be
     NULL.

KKEEYYWWOORRDDSS
     arguments, command line, options