home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / EFFO / forum7.lzh / RICO / MAN / man.argproc next >
Text File  |  1988-09-26  |  5KB  |  150 lines
  1.  
  2. argproc - process command line arguments
  3.  
  4. SYNOPSIS
  5.  
  6.      #include <argproc.h>
  7.  
  8.      long argproc(argc, argv, format [ , pointer ] . . .  )
  9.      int argc;
  10.      char *argv[], *format;
  11.  
  12.      Format string contents:
  13.     -  introduces one or more switches with single-letter names
  14.     =  is same as -, but sets a boolean telling whether each switch 
  15.        actually appeared on the command line
  16.     {} surround switches with long names
  17.     %s, %d, %f, %hd, %ld, %lf, etc. may appear alone to indicate 
  18.        positional parameters, or after a switch name to indicate 
  19.        arguments to that switch.  These are processed by sscanf().
  20.     ,  separates arguments of a single switch
  21.     [] surround optional arguments
  22.  
  23. NOTICE
  24.  
  25.      Argproc is a routine written by Steve Colwell at S.R. Systems.
  26.      It is being posted to Usenet to stimulate discussion about
  27.      command line argument parsers, and may be freely used and copied
  28.      for any purpose.  This routine has been in daily use for over a year
  29.      now; however, the version being posted was modified to use vsprintf
  30.      instead of _doprnt, and has been tested only lightly.
  31.  
  32. DESCRIPTION
  33.  
  34.      This routine provides an easy  way  to  parse  command  line
  35.      arguments.   The  main  routine passes its argc, argv, and a
  36.      scanf-type format string to argproc, which parses  the  com-
  37.      mand  line  for  parameters and switches as described below,
  38.      returning the various values in the pointed-to variables.
  39.      It does not alter argv[].
  40.  
  41.      Each entry in the format string has  one  of  the  following
  42.      forms:
  43.  
  44.      -XYZ X, Y, and Z are the one-char names of boolean flags.
  45.  
  46.      -X%s %s is a scanf-type format specification, which is  used
  47.           only if -X precedes it.
  48.  
  49.      -X[%s] %s is a optional scanf-type format specification, which 
  50.      may or may not be supplied after the -X.
  51.          -X[%d,%s] is allowed, but -X%d[,%s] is not supported.
  52.  
  53.      =X   X is a boolean flag, a boolean value is put in the associated
  54.       variable.  The '=' may be used in place of the '-' in any
  55.       of the above formats.
  56.  
  57.      {=XYZ}
  58.       XYZ is a many-char name for a single boolean flag.
  59.      {-outfile%s}
  60.       'outfile' is a many-char name for a flag with a string argument.
  61.  
  62.      %s   the next argument that doesn't start with - is taken as a %s 
  63.           type.
  64.  
  65.      Generally, anywhere a "%d" or "%s" is listed above, ANY scanf-style
  66.      format specifier may appear.
  67.  
  68.      The only way to have a switch with a greater than  one  char
  69.      name  is  by  using the braces.  For example, "{-longname}".
  70.      All other flag names are only one character long.  The flags
  71.      are  detected anywhere in the argument list, no matter where
  72.      they appear in the format string.
  73.  
  74.      A single argument may contain more than one format  command.
  75.      For  example,  "%d,%d"  gets  two  integers,  seperated by a
  76.      comma, from one argument.  This form  implies  two  relevant
  77.      bits in the returned bit map as well as two variables in the
  78.      variable list.
  79.  
  80.      A format may use the scanf "%*c" form to throw away an argu-
  81.      ment  or  a  part  of  an  argument.   In this case a bit is
  82.      assigned, but no variable is used as there is  no  value  to
  83.      receive.   This may be used to get two ints separated by any
  84.      char (ie. "%d%*c%d" to read 5,6 5-6 etc).
  85.  
  86.      The order of switches in the format string doesn't imply
  87.      that the switches must be given in any order on the commandline.
  88.  
  89. RETURN VALUE
  90.  
  91.      The return value is -1 for error.
  92.  
  93.      If there was no error, one bit is set for each unit of the 
  94.      format string which was successfully parsed.
  95.      This turns out to be difficult to use in practice, especially when
  96.      adding new options; I suggest using the = notation instead.
  97.      (A unit is a flag or argument format command in the format string.
  98.       For example, "-moyx"  has  four units and "-X%d" has two units.
  99.       The leftmost unit  is  assigned bit  0,  the  second unit is bit 1, 
  100.       etc.  If there are more than 32 "units" in the format string,
  101.       only the first 32 have bits in the return value.
  102.       This is one reason why the equals sign "=x" notation was added.)
  103.  
  104. EXAMPLES
  105.  
  106.      Always call lose_title(argv[0]) first thing in main().
  107.  
  108.      boolean x, y, z;
  109.      argproc(argc,argv,"=xy =z", &x, &y, &z);
  110.  
  111.      short a = 5;
  112.      argproc(argc,argv,"-a%hd", &a);
  113.  
  114.      char infile[100];
  115.      static char logfile[100] = "";
  116.      argproc(argc,argv,"{-logfile%s} %s", logfile, infile);
  117.  
  118.      char ofile[100], pfile[100];
  119.      boolean pGiven;
  120.      argproc(argc,argv,"-o%s =p[%s]", ofile, &pGiven, pfile);
  121.  
  122.      See also demo.c.
  123.  
  124. DIAGNOSTICS
  125.  
  126.      If the user enters an unknown option, argproc usually prints a message to
  127.      stderr and exits with a status of 1.
  128.      However, if the first character of the format string is 'W',
  129.      argproc prints an error message and returns with a value of -1.
  130.      If the first character of the format string is 'N',
  131.      argproc places an error message in the global ErrString, and returns 
  132.      with a value of -1.
  133.      See 'lose.doc'.
  134.  
  135. BUGS
  136.  
  137.      Longer switch names must occur before shorter ones to override them;
  138.      that is, the format string "-f {-fc}" will never allow the flag
  139.      -fc to be found, it will just give the error "no flag -c".
  140.  
  141.      Does not support the "--" convention.
  142.  
  143.      Does not allow spaces between an option and its argument
  144.      (e.g. "-o foo" does NOT match the format "-o%s"; "-ofoo" does).
  145.  
  146. LIBRARY
  147.  
  148.      Use argproc.l
  149.  
  150.