home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / misc / volume29 / parseargs / part02 / Intro next >
Encoding:
Text File  |  1992-05-19  |  4.9 KB  |  118 lines
  1.  
  2.                                   PARSEARGS
  3.  
  4.                         extracted from Eric Allman's
  5.  
  6.                             NIFTY UTILITY LIBRARY
  7.  
  8.                           Created by Eric P. Allman
  9.                              <eric@Berkeley.EDU>
  10.  
  11.                          Modified by Peter da Silva
  12.                             <peter@Ferranti.COM>
  13.  
  14.                    Modified and Rewritten by Brad Appleton
  15.                           <brad@SSD.CSD.Harris.COM>
  16.  
  17.  
  18.  Welcome to parseargs! Dont let the initial size of this package scare you.
  19.  over 75% of it is English text, and more than 50% of the source is comments.
  20.  
  21.  Parseargs is a set of functions to parse command-line arguments. Unlike
  22.  getopt and its variants, parseargs does more than just split up the
  23.  command-line into some canonical form. Parseargs will actually parse the
  24.  command-line, assigning the appropriate command-line values to the
  25.  corresponding variables, and will verify the command-line syntax (and print
  26.  a usage message if necessary). Furthermore, many features of it's parsing
  27.  behavior are configurable at run-time. Some of these features include the
  28.  following:
  29.  
  30.      o  Prompting the user for missing arguments
  31.      o  Allowing keywords (+count=4) and/or options (-c4)
  32.      o  Checking for default arguments in an environment variable
  33.      o  Ignoring bad syntax instead of terminating
  34.      o  Ignoring upper/lower case on the command-line
  35.      o  Controlling the location of non-positional parameters
  36.      o  Controlling the contents (syntax and verbosity) of usage messages
  37.      o  Having long usage messages piped through a paging program
  38.  
  39.  Parseargs also allows for options that take an optional argument, and
  40.  options that take a (possibly optional) list of one or more arguments.
  41.  In addition, parseargs may be configured at compile-time to parse
  42.  command-lines in accordance with the native command-syntax of any of the
  43.  following operating systems:
  44.  
  45.      o  Unix
  46.      o  VAX/VMS
  47.      o  OS/2
  48.      o  MS-DOS
  49.      o  AmigaDOS
  50.  
  51.  Parseargs consists of a set of C-functions to parse arguments from the
  52.  command-line, from files, from strings, from linked-lists, and from
  53.  string-vectors. Also included is a command-line interface which will parse
  54.  arguments for shell scripts (sh, csh/tcsh/itcsh, ksh, bash, zsh, and rc),
  55.  awk-scripts, perl-scripts and tcl-scripts.
  56.  
  57.  The basic structure used by parseargs is the argument-descriptor (sometimes
  58.  called "argdesc" for brevity).  An array/string of argdescs is declared by
  59.  the user to describe the command in question.  The resulting argdesc-array
  60.  is passed to all the parseargs functions and is used to hold all information
  61.  about the command. a sample argdesc-array is shown below.
  62.  
  63.     STARTOFARGS,
  64.     { 'a', ARGVALOPT, argStr,   &area,    "AREAcode : optional area-code" },
  65.     { 'g', ARGLIST,   argStr,   &groups,  "newsGROUPS : groups to test" },
  66.     { 'r', ARGOPT,    argInt,   &count,   "REPcount : repetition factor" },
  67.     { 's', ARGOPT,    argChar,  &sepch,   "SEPchar : field separator" },
  68.     { 'x', ARGOPT,    argBool,  &xflag,   "Xflag : turn on X-mode" },
  69.     { ' ', ARGREQ,    argStr,   &name,    "name : name to use" },
  70.     { ' ', ARGLIST,   argStr,   &args,    "args : any remaining arguments" },
  71.     ENDOFARGS
  72.  
  73.  Once the above array/string is declared it is a simple matter to invoke
  74.  parseargs from C as in the following example:
  75.  
  76.     status = parseargs( argv, argdesc_array );
  77.  
  78.  or from a shell script as in the following example:
  79.  
  80.     echo "$ARGDESC_STR" | parseargs -s sh -- "$0" "$@" >tmp$$
  81.     test  $? = 0  &&  . tmp$$
  82.     /bin/rm -f tmp$$
  83.  
  84.  And before you know it, your command-line had been parsed, all variables 
  85.  have been assigned their corresponding values from the command-line, syntax
  86.  have been verified, and a usage message (if required) has been printed. 
  87.  
  88.  Under UNIX, the command-line syntax (using single character options) for the
  89.  above command would be:
  90.  
  91.     cmdname [-a [<areacode>]] [-g <newsgroups>...] [-r <repcount>]
  92.             [-s <sepchar>] [-x]  <name>  [<args>...]
  93.  
  94.  The UNIX command-line syntax using keywords (or long options) would be:
  95.  
  96.     cmdname [+area [<areacode>]] [+groups <newsgroups>...] [+rep <repcount>]
  97.             [+sep <sepchar>] [+x]  <name>  [<args>...]
  98.  
  99.  The VMS command-line syntax would be the following:
  100.  
  101.     cmdname [/AREA[=<areacode>]] [/GROUPS=<newsgroups>[,<newsgroups>...]]
  102.             [/REP=<repcount>] [/SEP=<sepchar>] [/X]  <name>
  103.             [<args>[,<args>...]]
  104.  
  105.  The MS-DOS and OS/2 command-line syntax would be the following (unless the
  106.  environment variable $SWITCHAR is '-' in which case UNIX syntax is used):
  107.  
  108.     cmdname [/a[=<areacode>]] [/g=<newsgroups>...] [/r=<repcount>]
  109.             [/s=<sepchar>] [/x]  <name>  [<args>...]
  110.  
  111.  The AmigaDOS command-line syntax would be the following:
  112.  
  113.     cmdname [AREA [<areacode>]] [GROUPS <newsgroups>...] [REP <repcount>]
  114.             [SEP <sepchar>] [X]  <name>  [<args>...]
  115.  
  116.  
  117.  Please look at the README files and manpages for more detailed information!
  118.