Usenet 1994 October

home *** CD-ROM | disk | FTP | other *** search

/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / misc / volume17 / parseargs / part04 < prev next >

Wrap

Internet Message Format | 1991-03-18 | 61.3 KB

From: brad@hcx1.ssd.csd.harris.com (Brad Appleton) Newsgroups: comp.sources.misc Subject: v17i049: parseargs - functions to parse command line arguments, Part04/12 Message-ID: <1991Mar17.200651.17871@sparky.IMD.Sterling.COM> Date: 17 Mar 91 20:06:51 GMT Approved: kent@sparky.imd.sterling.com X-Checksum-Snefru: a0790335 6200296b 01972989 8e18cf04 Submitted-by: Brad Appleton <brad@hcx1.ssd.csd.harris.com> Posting-number: Volume 17, Issue 49 Archive-name: parseargs/part04 This is part 4 of parseargs #!/bin/sh # this is Part.04 (part 4 of a multipart archive) # do not concatenate these parts, unpack them in order with /bin/sh # file parseargs/doc/parseargs.man1 continued # if test ! -r _shar_seq_.tmp; then echo 'Please unpack part 1 first!' exit 1 fi (read Scheck if test "$Scheck" != 4; then echo Please unpack part "$Scheck" next! exit 1 else exit 0 fi ) < _shar_seq_.tmp || exit 1 if test ! -f _shar_wnt_.tmp; then echo 'x - still skipping parseargs/doc/parseargs.man1' else echo 'x - continuing file parseargs/doc/parseargs.man1' sed 's/^X//' << 'SHAR_EOF' >> 'parseargs/doc/parseargs.man1' && .TP 14 \fB\-F\fP \fIstring\fP string to use for false boolean arguments (\fIdefault=``\^''\fP\|) .TP 14 \fB\-A\fP modify array behavior for the specified shell. .TP 14 \fB\-a\fP \fIarg-spec\fP argument specification string .TP 14 \fB\-e\fP\ \fIname\fP read the arg-spec string from the environment variable named \fIname\fP .TP 14 \fB\-f\fP \fIfile\fP read the arg-spec from \fIfile\fP (\fIdefault=stdin\fP) .TP 14 \fB\-l\fP Long-options only. Disable the parsing of (single-character) options. .TP 14 \fB\-o\fP Options only. Disable the parsing of long-options (keywords). .TP 14 \fB\-s\fP \fIshell\fP use \fIshell\fP command syntax\| (\fIdefault=``sh''\fP\|) .TP 14 \fB\-u\fP unset positional parameters before assigning variables .TP 14 \fB\-p\fP prompt the user for missing required arguments .TP 14 \fB\-i\fP ignore bad command-line syntax and continue processing (instead of aborting) .\"----------------------------------------------------------- .SH ARGUMENTS .TP 14 \fI\-\^\-\fP Indicates that any remaining options are intended for the calling program. .TP 14 \fIname\fP name of calling program .TP 14 \fIarguments\fP arguments to calling program .\"----------------------------------------------------------- .so parseargs1.inc .\"----------------------------------------------------------- .PP The argument specification string contains one entry for each possible flag. Entries in the arguments specification string are separated by commas. Each entry has five comma-separated fields: a name, some flags, a type, a variable-name, and a prompt. Each of these fields are described below: .TP 10 \fIname\fP The single character name of the associated flag. For example, to indicate that the program is expecting a ``\-x'' flag, this field would contain \'x\'. Positional arguments (those without a ``\-\fIx\fP'' prefix) are indicated by passing a ``space'' character. .TP 10 \fIflags\fP Flags modifying the semantics of this entry. These should have one of \s-1ARGREQ\s+1 to indicate a required argument or \s-1ARGOPT\s+1 to indicate an optional argument (\s-1ARGOPT\s+1 is the default unless \s-1ARGREQ\s+1 is specified). \s-1ARGPOS\s+1 can be ``ored'' in to indicate a positional argument that may also be keyword matched. \s-1ARGNOVAL\s+1 can be ``ored'' in to indicate that an argument is an option or a keyword that does not use an accompanying argument (such as a boolean flag). This flag is only required for corresponding argument types that are implemented by the programmer; \fBparseargs\fP already knows which pre-defined argument types take an argument. \s-1ARGVALOPT\s+1 can be ``ored'' in to indicate that an argument to the option may be optionally supplied on the command-line, but is not required. \s-1ARGVALREQ\s+1 can be ``ored'' in to indicate that an argument to the option is required (this is the default behavior for options that take arguments). \s-1ARGLIST\s+1 can be ``ored'' in (using the `\^|\^' character) to indicate that an argument is actually a list of one or more arguments from the command line. \s-1ARGHIDDEN\s+1 can be ``ored'' in to indicate a flag that should not be printed in usage messages \(em for example, flags intended for internal debugging purposes. .TP 10 \fItype\fP The type of the argument. Existing types include \fIargUsage\fP (print usage message and exit), \fIargBool\fP and \fIargSBool\fP (set Boolean flags), \fIargUBool\fP (unset Boolean flags), \fIargStr\fP (string-valued arguments), \fIargChar\fP (char-valued arguments), \fIargInt\fP (native integer arguments), \fIargShort\fP (short integer arguments), \fIargLong\fP (long integer arguments), \fIargFloat\fP (short floating point arguments), \fIargDouble\fP (long floating point arguments), and \fIargDummy\fP (only used as part of usage message, not matched on command-line). .TP 10 \fIvariable\fP The name of the shell variable that should receive the converted value. .TP 10 \fIprompt\fP The string used when prompting interactively for argument values, and printed in usage messages. This string may be followed by a textual description that is enclosed in parentheses, square brackets, curly braces, or angle brackets. .PP The argument specification string must be terminated by the single string: ``ENDOFARGS''. .PP Note that the comma character (',') is used to separate all fields within an entry, and to separate the entries themselves. For this reason, \fIno field in any entry may contain a comma unless it appears inside of double or single quotes\fP. .PP .B Parseargs will parse all command-line arguments for the calling script and match them against the argument specification string provided. The argument specification string is read from standard input by default but may not come from a terminal. The argument specification string may be supplied as a single string argument by using the \fB\-a\fP ``\fIstring\fP'' flag. Long argument specification strings however, may limit the number of arguments to the script if there is a limit to the number of arguments and/or characters that may appear on the command line. For this reason, the argument specification string may be stored: in an environment variable using the \fB-e\fP \fIname\fP option; in a file and read using the \fB\-f\fP \fIfile\fP option; or read from standard input. When using the \fB\-e\fP option, the user must remember to use the name of an environment variable (not a mere shell variable)! The default behavior is to read the argument specification from standard input. .\"----------------------------------------------------------- .so shells.inc .\"----------------------------------------------------------- .PP The double-dash (``\fB\-\^\-\fP'') which precedes the name and arguments of the calling program is needed in order for \fBparseargs\fP to be able to distinguish options to itself from options for the calling program. .PP The default behavior of parseargs is allow both single-character options and long-options (keywords) on the command-line. The user may specify that only options (long-options) are to be permitted by specifying the \fB\-o\fP (\fB\-l\) option on the command-line. .\"---------------------------------------------------------------- .so argvalopt.inc .\"---------------------------------------------------------------- .so sh_arrays.inc .\"---------------------------------------------------------------- .so env_args.inc .\"---------------------------------------------------------------- .so env_parse.inc .\"---------------------------------------------------------------- .so env_usage.inc .\"---------------------------------------------------------------- .SH EXAMPLES .PP As a first example, consider the following argument specification for a Bourne shell script: .PP .nf .\" *** font 4 is the "typewriter-style" non-proportional font on my machine *** .ft 4 .sp 8p #!/bin/sh .sp 8p RepCount=2; Verbose=""; .sp 8p ARGSPEC=" X 'c', ARGOPT, argInt, RepCount, 'count {# times to repeat}', X 'v', ARGOPT, argBool, Verbose, 'verbose {turn on verbose mode}', X ' ', ARGREQ, argStr, InFile, 'input {file to read from}', X ' ', ARGOPT, argStr, OutFile, 'output {file to write to}', X 'X', ARGHIDDEN, argBool, XRated, 'xrated {naughty! naughty!}', X ' ', ARGOPT|ARGLIST, listStr, Files, 'files {files to process}', ENDOFARGS " .sp 8p eval `echo "$ARGUMENTS" | parseargs \-s sh \-\|\- $0 "$@"` .sp 8p .ft R .fi .PP This describes a Bourne shell script accepting up to three flag arguments and one or two positional arguments, plus a list of additional file arguments. Only the first positional argument is required. The possible flags (in UNIX) are: .RS .TP 10 \fB\-c\fP \fIcount\fP An integer repetition count. This defaults to two. .TP 10 \fB\-v\fP A Boolean ``verbose'' flag. It defaults to \s-1FALSE\s+1 (an empty string). .TP 10 \fB\-X\fP A Boolean ``X Rated'' flag. This is not printed in the usage message. .RE .PP The two positional arguments are both strings, as is the final list. If we were to invoke the above script with the following command line: .sp 8p .RS \f4cmdname \-v input_file output_file file1 file2\fP .RE .sp 8p Then, after invoking \fBparseargs\fP, the following shell variables would contain the following values: .sp 8p .RS \f4$RepCount\fP would evaluate to ``\f42\fP\^'' .sp 4p \f4$Verbose\fP would evaluate to ``\f4\s-1TRUE\s+1\fP\^'' .sp 4p \f4$InFile\fP would evaluate to ``\f4input_file\fP\^'' .sp 4p \f4$OutFile\fP would evaluate to ``\f4output_file'\fP\^' .sp 4p \f4$Files\fP would evaluate to ``\f4file1 file2\fP\^'' .sp 4p \f4$XRated\fP would be unset and would evaluate to an empty string (``\^''). .RE .sp .PP Now let's present a more complete example. The following page shows a Bourne shell script which uses \fBparseargs\fP to parse its command line, echoes the settings of all its associated command line variables, and then prints its command usage. X .nf .\" *** font 4 is the "typewriter-style" non-proportional font on my machine *** .ft 4 .so ../test.sh .ft R .fi .\"----------------------------------------------------------- .SH DIAGNOSTICS \fBParseargs\fP may exit with one of the following status codes: X .TP 5 -1 Some type of system error occurred during execution, causing the program to exit prematurely. .TP 5 \|\|0 Normal exit status (no problems were encountered). .TP 5 \|\|1 The calling program specified the \fB\-U\fP or the \fB\-M\fP option to \fBparseargs\fP, or specified an \fIargUsage\fP flag on the command line. Only the appropriate message is displayed. .TP 5 \|\|2 A command line syntax error was encountered by \fBparseargs\fP. The offending command line argument may have been intended for either \fBparseargs\fP or for the calling program. .TP 5 \|\|3 The environment variable that was specified with the \fB\-e\fP option is either \s-1NULL\s+1 (has an empty value) or does not exist. Perhaps the user specified a shell variable and/or forgot to export it. .TP 5 \|\|4 A syntax error was encountered in the argument specification string that was specified to \fBparseargs\fP. .\"----------------------------------------------------------- .SH FILES .IP "\fI/usr/local/parseargs.pl\fP" This file defines a \fIperl\fP function named \fIparseargs\fP to parse arguments more conveniently for perl-scripts. The function is both documented and implemented in this file. The user should ``require'' this file in his/her perl-script before invoking the function. .IP "\fI/usr/local/parseargs.awk\fP" This file defines an \fIawk\fP function named \fIparseargs\fP to parse arguments more conveniently for awk-scripts. The function is both documented and implemented in this file. The user should include this file in his/her awk-script before invoking the function. .\"----------------------------------------------------------- .SH SEE ALSO .IR argtype (3), .IR parseargs (3), .IR parsecntl (3) .\"----------------------------------------------------------- .so caveats.inc .\"----------------------------------------------------------- .so bugs.inc .\"----------------------------------------------------------- .SH AUTHOR .nf Brad Appleton (\fIbrad@ssd.csd.harris.com\fP) Harris Computer Systems, Fort Lauderdale, FL USA .fi SHAR_EOF echo 'File parseargs/doc/parseargs.man1 is complete' && chmod 0664 parseargs/doc/parseargs.man1 || echo 'restore of parseargs/doc/parseargs.man1 failed' Wc_c="`wc -c < 'parseargs/doc/parseargs.man1'`" test 12151 -eq "$Wc_c" || echo 'parseargs/doc/parseargs.man1: original size 12151, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/parseargs.man3 ============== if test -f 'parseargs/doc/parseargs.man3' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/parseargs.man3 (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/parseargs.man3 (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/parseargs.man3' && .\" $Header: parseargs.3,v 2.0 89/12/24 00:56:26 eric Exp $ .TH PARSEARGS 3 .\"----------------------------------------------------------- .SH NAME parseargs, usage \- parse command line argument vectors .\"----------------------------------------------------------- .SH SYNOPSIS #include <parseargs.h> .PP .nf int parseargs( char *argv[], ARGDESC *argd ) int fparseargs( FILE *fp, ARGDESC *argd ) int lparseargs( ArgList *argls, ARGDESC *argd ) int sparseargs( char *str, ARGDESC *argd ) int vparseargs( ARGDESC *argd, ... ) void usage( const ARGDESC *argd ) .fi .\"----------------------------------------------------------- .SH DESCRIPTION .so parseargs3.inc .so fparseargs3.inc .so lparseargs3.inc .so sparseargs3.inc .so vparseargs3.inc .so usage3.inc .\"----------------------------------------------------------- .so argdesc.inc .\"----------------------------------------------------------- .SH DEFINING ARGDESC ARRAYS When defining an argdesc array, the first item in the list should be the item STARTOFARGS. Normal arguments (defined by the programmer) may then be specified as documented in this manual. The list of arguments is terminated using ENDOFARGS. .PP For example, consider the description: .sp 4p .in +2 .nf .ft 4 int RepCount = 2; BOOL Verbose = FALSE; char *InFile; char *OutFile = CHARNULL; BOOL XRated = FALSE; struct namelist *Files = NULL; X ARGDESC Args[] = { X STARTOFARGS, X 'c', ARGOPT, argInt, _\|_ &RepCount, "REPcount {# of repetitions}", X 'v', ARGOPT, argBool, _\|_ &Verbose, "Verbose {set verbose mode}", X ' ', ARGREQ, argStr, _\|_ &InFile, "INPUTfile {input file}", X ' ', ARGOPT, argStr, _\|_ &OutFile, "OUTPUTfile {output file}", X 'X', ARGHIDDEN, argBool, _\|_ &XRated, "XratedMODE {naughty stuff!}", X ' ', ARGOPT\^|\^ARGLIST, argStr, _\|_ &Files, "File {files to be read}", X ENDOFARGS }; .ft R .fi .in -2 .PP This describes a program accepting up to three flag arguments and one or two positional arguments, plus a list of additional file arguments. Only the first positional argument is required. The possible flags (in UNIX) are: .TP 10 \fB\-c\fP \fIcount\fP An integer repetition count. This defaults to two. .TP 10 \fB\-v\fP A Boolean ``verbose'' flag. It defaults to FALSE. .TP 10 \fB\-X\fP A Boolean ``X Rated'' flag. This is not printed in the usage message. .PP The two positional arguments are both strings, as is the final list. In AmigaDOS, the options would be \fBREP\fP \fBcount\fP, \fBV\fP, and \fB\s-1XMODE\s+1\fP. In \s-1VAX/VMS\s+1, the qualifiers would be \fB\s-1/REP\s+1\fP=\fIcount\fP, \fB\s-1/V\s+1\fP, and \fB\s-1/XMODE\s+1\fP. .\"----------------------------------------------------------- .so argflags.inc .\"----------------------------------------------------------- .so arg_macros.inc .\"----------------------------------------------------------- .so cmd_macros.inc .\"----------------------------------------------------------- .so defargs.inc .\"----------------------------------------------------------- .so env_args.inc .\"----------------------------------------------------------- .so env_parse.inc .\"----------------------------------------------------------- .so env_usage.inc .\"----------------------------------------------------------- .so multivals.inc .\"----------------------------------------------------------- .SH ARGUMENT TYPE FUNCTIONS The argument types recognized by .I parseargs can be extended by adding new type functions. Argument type functions are declared as: .RS .PP .nf .ft 4 BOOL argXxx( ARGDESC *ad, char *vp, BOOL copyf ) .ft R .fi .RE .PP The .I argd argument points to the descriptor for the argument being converted. Its main use is to find the location in which to store the converted value, located in argd\(->ad_valp. The string value to be converted is passed in .IR argp (which will be \s-1NULL\s+1 if the \s-1ARGNOVAL\s+1 flag was set for the corresponding entry in the arg-descriptor table). The .I copyf flag is TRUE if the .I argp string value must be copied when saved. Most non-string types are copied implicitly (for example, integer arguments are stored in binary form, so the original string value need not be saved), so this argument can usually be ignored. Put simply, this flag is TRUE when .I argp points to a temporary buffer area. .PP If the type function successfully converts the value, and uses the entire value, it should return TRUE. If the type function successfully converts the value, and uses only \fIN\fP characters of the value, it should return -\fIN\fP. Otherwise, it should print a message using .IR usrerr (3) and return FALSE. This message should be of the form \fB"invalid xxxx option 'yyyy' for Zzzz"\fP, where xxxx is the type of the option, yyyy is the string passed in vp, and zzzz is the name (taken from \fBad\(->ad_prompt\fP). The \fIargXxxx\fP function is responsible for detecting if the given argument descriptor is an \s-1ARGVEC\s+1 argument and for taking the appropriate action. .PP For example, a type function that took a filename and stored an open file pointer might be coded as: .RS .PP .nf .ft 4 #define REALLOC(ptr,size) ((! ptr) ? malloc(size) : realloc(ptr, size)) .sp 8p typedef ARGVEC_T(FILE *) FILEvec_t; .sp 8p BOOL argReadFile( ARGDESC *\|ad, char *\|vp, BOOL copyf ) { X register FILE *fp; .sp 4p X fp = fopen(vp, "r"); .sp 4p X if ( ! fp ) { X usrerr("cannot open '%s' for reading", vp); X return (FALSE); X } .sp 4p X if ( BTEST(arg_flags(ad), ARGVEC) ) { X FILEvec_t *vec = (FILEvec_t *) arg_valp(ad); X size_t size = (1 + vec->count) * (sizeof (FILE *)); .sp 4p X vec->array = (FILE **) REALLOC(vec->array, size); X if ( ! vec->array ) X syserr( "(m|re)alloc failed in argReadFile" ); .sp 4p X vec->flags = (FILE **) REALLOC(vec->flags, size); X if ( ! vec->flags ) X syserr( "(m|re)alloc failed in argReadFile" ); .sp 4p X vec->flags[ vec->count ] = arg_flags(ad); X vec->array[ (vec->count)++ ] = fp; X } X else X *(FILE *) arg_valp(ad) = fp; .sp 4p X return (TRUE); } .ft R .fi .RE .RE .\"------------------------------------------------------------------ .SH LONG OPTIONS .PP Under \s-1UNIX\s+1, Parseargs also allows for long options in addition to single character options. Long options are denoted by a `\fB+\fP' character (which may be changed using \fIkeywordprefix\fP). The keyword that is used is the first word in the prompt field of an argument descriptor entry. Long options are case insensitive! An argument to a long option may be separated from the long option by an equal sign (`=') or by one or more whitespace characters. Thus, if an entry looks like: .RS .sp 4p .nf .ft 4 \^'c', ARGOPT, argInt, _\|_ &count, "repCOUNT (# of times to repeat)", .ft R .fi .sp 4p .RE then ``\fB\-c4\fP'', ``\fB+repcount=4\fP'', ``\fB+count=4\fP'', ``\fB+repcount\04\fP'', and ``\fB+count\04\fP'' will all have the same effect. .PP The long option names for ``\fB\-?\fP'' in the default argument descriptor are ``\fB+help\fP'' and ``\fB+?\fP'' (respectively). In addition, ``\fB++\fP'' or ``\fB+endopts\fP'' may be used to indicate the end of options so that all remaining arguments will be interpreted as positional parameters (even if one begins with a `\fB+\fP' or a `\fB\-\fP'). .PP Under VAX/VMS and AmigaDOS, single-character options are not used and the ``long'' name (in the prompt field of an argument descriptor) is always used to match for possible arguments (or keywords, or qualifiers). .PP For all supported operating systems, a long option may be matched in one of two ways: it may match all uppercase characters in the prompt field, or it may match all characters in the prompt field (as in ``\fB+count=4\fP'' and ``\fB+repcount=4\fP''). .PP Under \s-1UNIX\s+1 and \s-1VAX/VMS\s+1, only the number of characters required to uniquely identify the desired argument are needed, but at least two characters must be given (unless the prompt field is itself less than two characters long). This means that using the above example, that ``\fB+rep=4\fP'' and ``\fB+cou=4\fP'' would also work but ``\fB+c=4\fP'' would \s-1NOT\s+1 (in other words, if you only want to use one character, use ``\fB\-c4\fP'' instead). .PP Under VAX/VMS, the possibilities using the above example would be: ``\fB/REPCOUNT=4\fP'', ``\fB/COUNT=4\fP'', ``\fB/REP=4\fP'', and ``\fB/COU=4\fP'', .PP Under AmigaDOS, no ``shortened'' keywords are accepted and the possibilities using the above example would be: ``\fBREPCOUNT 4\fP'', and ``\fBCOUNT 4\fP'' .\"------------------------------------------------------------------ .so returns.inc .\"------------------------------------------------------------------ .SH SEE ALSO .IR argtype (3), .IR parseargs (1), .IR syserr (3) .br The ``C Advisor'' column in .ul UNIX Review Vol. 7 No. 11. .\"----------------------------------------------------------- .so caveats.inc .\"----------------------------------------------------------- .so lib_bugs.inc .\"----------------------------------------------------------- .SH AUTHOR Eric Allman, University of California, Berkeley .SH MODIFICATIONS .PP Modified to accept a vector of arguments, better error messages, Unix keyword matching, and AmigaDOS version by Peter da Silva. .PP Rewritten by Brad Appleton. Parseargs(1); functions parsecntl, sparseargs, fparseargs, lparseargs, and vparseargs; argument types argUsage, argDummy, argUBool, and argTBool; argument flags \s-1ARGPOS\s+1, \s-1ARGVALOPT\s+1, \s-1ARGVALREQ\s+1, \s-1ARGVALGIVEN\s+1, \s-1ARGNOVAL\s+1, and \s-1ARGVEC\s+1; and \s-1VAX/VMS\s+1 version and IBM-PC version by Brad Appleton SHAR_EOF chmod 0664 parseargs/doc/parseargs.man3 || echo 'restore of parseargs/doc/parseargs.man3 failed' Wc_c="`wc -c < 'parseargs/doc/parseargs.man3'`" test 9554 -eq "$Wc_c" || echo 'parseargs/doc/parseargs.man3: original size 9554, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/parseargs1.inc ============== if test -f 'parseargs/doc/parseargs1.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/parseargs1.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/parseargs1.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/parseargs1.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -n -p '[ \t]*' -I DESCRIPTION ../parseargs.c .\"---------------------------------------------------------------------------- .SH DESCRIPTION Given a command name, a vector of string-valued arguments such as that passed to a shell script, and a specification string describing the possible arguments, .B parseargs matches actual arguments to possible arguments, converts values to the desired type, and diagnoses problems such as missing arguments, extra arguments, and argument values that are syntactically incorrect. Other behavior such as prompting the user for missing arguments and ignoring as command-line syntax may be specified on the command-line through the use of various options, or through the use of the ``\s-1PARSECNTL\s+1'' environment variable. .PP Given the command name and the argument specification string, .B parseargs \-U prints a reasonably friendly version of the usage of the calling program on standard diagnostic output. The ``verbosity'' of the usage message may be controlled through the use of the ``\s-1USAGECNTL\s+1'' environment variable. .PP Given the command name and the argument specification string, .B parseargs \-M prints a template of the command-syntax on standard output that is suitable for input to \fInroff\fP or \fItroff\fP using the \-man macro package. SHAR_EOF chmod 0664 parseargs/doc/parseargs1.inc || echo 'restore of parseargs/doc/parseargs1.inc failed' Wc_c="`wc -c < 'parseargs/doc/parseargs1.inc'`" test 1461 -eq "$Wc_c" || echo 'parseargs/doc/parseargs1.inc: original size 1461, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/parseargs3.inc ============== if test -f 'parseargs/doc/parseargs3.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/parseargs3.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/parseargs3.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/parseargs3.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -n -p '[ \t]*' -I DESCRIPTION -f parseargs ../xparse.c .\"---------------------------------------------------------------------------- .PP Given a vector of string-valued arguments such as that passed to \fImain\fP and a vector describing the possible arguments, \fIparseargs\fP matches actual arguments to possible arguments, converts values to the desired type, and diagnoses problems such as missing arguments, extra arguments, and argument values that are syntactically incorrect. SHAR_EOF chmod 0664 parseargs/doc/parseargs3.inc || echo 'restore of parseargs/doc/parseargs3.inc failed' Wc_c="`wc -c < 'parseargs/doc/parseargs3.inc'`" test 642 -eq "$Wc_c" || echo 'parseargs/doc/parseargs3.inc: original size 642, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/parsecntl.man3 ============== if test -f 'parseargs/doc/parsecntl.man3' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/parsecntl.man3 (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/parsecntl.man3 (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/parsecntl.man3' && .\"---------- TO PRINT, USE: {n,t}roff -man file ---------- .TH PARSECNTL 3 .\"----------------------------------- .SH NAME parsecntl \- get and set attributes of an argument descriptor array .\"----------------------------------- .SH SYNOPSIS #include <parseargs.h> .PP .nf int parsecntl( ARGDESC argd[\|], parsecntl_t func, parsemode_t mode, ... ) .fi X .\"----------------------------------- .so parsecntl3.inc .\"----------------------------------- .so parsecntls.inc .\"----------------------------------- .so parsemodes.inc .\"----------------------------------- .so parseflags.inc .\"----------------------------------- .so argflags.inc .\"----------------------------------- .so returns.inc .\"----------------------------------- .SH SEE ALSO .nf .IR argtype (3), .IR parseargs (3), .IR parseargs (1) .fi .\"----------------------------------- .SH AUTHOR .PP .nf Brad Appleton (\fIbrad@ssd.csd.harris.com\fP) Harris Computer Systems, Fort Lauderdale, FL USA .fi SHAR_EOF chmod 0664 parseargs/doc/parsecntl.man3 || echo 'restore of parseargs/doc/parsecntl.man3 failed' Wc_c="`wc -c < 'parseargs/doc/parsecntl.man3'`" test 974 -eq "$Wc_c" || echo 'parseargs/doc/parsecntl.man3: original size 974, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/parsecntl3.inc ============== if test -f 'parseargs/doc/parsecntl3.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/parsecntl3.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/parsecntl3.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/parsecntl3.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -n -p '[ \t]*' -I DESCRIPTION -f parsecntl ../xparse.c .\"---------------------------------------------------------------------------- .SH "DESCRIPTION" .PP .I Parsecntl will read and/or write the desired attributes of the given command-object. The attributes to be operated upon are specified by the second parameter to .I parsecntl. The desired mode (read, write, or both) are specified by the third parameter to .I parsecntl. If the operation to be performed is .I pc_\s-1ARGFLAGS\s+1, then the fourth argument to .I parsecntl should be the keyword name of the argument whose flags are to be retrieved. The last parameter to .I parsecntl is always the object to contain the attribute(s) to be read/written. If the attribute(s) are to be read (regardless of whether or not they are also being changed) then the last argument should be a pointer to an object, otherwise the last argument should be the object itself. .PP If mode is .I pc_\s-1READ\s+1, then the desired attributes are copied into the object pointed to by the last parameter. If the mode is .I pc_\s-1WRITE\s+1, then the attributes from the last parameter are copied to the command- object. If mode is .I pc_\s-1RDWR\s+1, then the attributes pointed to by the last parameter are copied to the command-object, and then the previous value of these attributes (before they were overwritten) is copied into the object pointed to by the last parameter. .PP If cntl is .I pc_\s-1ARGFLAGS\s+1, then the only valid mode is .I pc_\s-1READ\s+1. All other attributes may be written or read by .I parsecntl. SHAR_EOF chmod 0664 parseargs/doc/parsecntl3.inc || echo 'restore of parseargs/doc/parsecntl3.inc failed' Wc_c="`wc -c < 'parseargs/doc/parsecntl3.inc'`" test 1721 -eq "$Wc_c" || echo 'parseargs/doc/parsecntl3.inc: original size 1721, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/parsecntls.inc ============== if test -f 'parseargs/doc/parsecntls.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/parsecntls.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/parsecntls.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/parsecntls.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -p '[ \t]*' -s PARSE-CNTLS ../parseargs.h .\"---------------------------------------------------------------------------- .SH "FUNCTION CODES" .PP Each of the following function codes specifies an attribute that is to be manipulated by \fIparsecntl\fP. The function code is the second parameter to \fIparsecntl\fP. With the exception of .I pc_\s-1ARGFLAGS\s+1, each of the function codes corresponds to a call to \fIparsecntl\fP using four parameters ( .I pc_\s-1ARGFLAGS\s+1 uses 5 parameters). In each case, the last parameter is either the address of a buffer to write the attribute to, or the actual buffer to read the attribute from (depending upon the mode \- the third parameter to \fIparsecntl\fP). .\"--------------------------------------------- .IP "\fIpc_\s-1PARSEFLAGS\s+1" This function code is used to read and/or modify the existing parsing parsing behavior. The fourth parameter to \fIparsecntl\fP should be a combination of pc_XXXX bitmasks if the parse-flags are only being written, otherwise it should be a pointer to an \fIargMask_t\fP variable. .\"--------------------------------------------- .IP "\fIpc_\s-1ARGFLAGS\s+1" This function code may only be used to read the argument-flags of a named argument. It is an error to specify a mode that attempts to write the argument-flags with this function code. The fourth parameter to \fIparsecntl\fP should be the keyword name of the argument whose flags are to be read. The fifth (and final) argument should be a pointer to the \fIargMask_t\fP variable which will receive the resulting argument-flags. .\"--------------------------------------------- .IP "\fIpc_\s-1DEFARGS\s+1" This function code is used to query or modify the current default argument-descriptor list for the given command. The fourth parameter to \fIparsecntl\fP should be the argument-descriptor array to assign as the new default-list (or the address of an argdesc-array if the default list is being retrieved). X If a given option/qualifier does not appear to match any items in the argdesc-array, a default argdesc-array is then searched to match the option. If it is STILL unmatched then it is flagged as such. The default-argdesc array is automatically used by all programmer-defined argdesc-array but may be unset or reset using the .I pc_\s-1DEFARGS\s+1 function of .I parsecntl. In such a manner, a programmer could specify a different set of default-arguments to search for. Furthermore, default argdesc-arrays may also be assigned default argdesc-arrays, thus allowing the programmer to define a whole search-list of default argdesc-arrays for a given command. X This could prove useful in a situation where a set of commands have a few common-options and differ in their remaining ones. If the same \fImain()\fP were used for each command, then main could define one common argdesc-array and then a set of argdesc-arrays for each command. \fIMain\fP could then figure out which argdesc-array to used based on the name in \fIargv[0]\fP, and set its default argdesc-array to be the common argdesc-array, as in the following: X .nf .ft 4 #include <parseargs.h> X . X . \fIvariable declarations\fP X . X static ARGDESC common_args[] = { X STARTOFARGS, X { 'L', ARGOPT, argBool, __ &lflag, "list (list the items)" }, X { 'I', ARGOPT, argStr, __ &item, "item (item to use)" }, X ENDOFARGS }; X static ARGDESC cmd1_args[] = { X STARTOFARGS, X { 's', ARGOPT, argBool, __ &sflag, "S (set S)" }, X { 't', ARGOPT, argBool, __ &tflag, "T (set T)" }, X ENDOFARGS }; X static ARGDESC cmd2_args[] = { X STARTOFARGS, X { 'x', ARGOPT, argBool, __ &xflag, "X (set X)" }, X { 'y', ARGOPT, argBool, __ &yflag, "Y (set Y)" }, X ENDOFARGS }; X main( int argc, char *argv[] ) { X ARGDESC *cmd = cmd1_args; X int rc; X X if ( strcmp(*argv, "cmd2") == 0 ) X cmd = cmd2_args; X X rc = parsecntl( cmd, pc_DEFARGS, pc_WRITE, common_args ); X if ( rc != pe_SUCCESS ) X syserr( "unable to set default args" ); X X rc = parseargs( argv, cmd ); X . X . X . } .ft R .fi X Note that in the above call to .IR parsecntl(3), that zero will be returned upon success and non-zero upon failure. If pe_DEFARGS is returned, then cmd is already on common_args's list of defaults (and would result in an infinite loop while parsing). .\"--------------------------------------------- .IP "\fIpc_\s-1NAME\s+1\fP" .IP "\fIpc_\s-1PURPOSE\s+1\fP" .IP "\fIpc_\s-1DESCRIPTION\s+1\fP" Each of these last three function codes are used to modify or query the name, purpose, or description associated with a command. The fourth parameter to \fIparsecntl\fP should be the new string to use (or the address of the string, a \fIchar**\fP variable, to recieve the current value). SHAR_EOF chmod 0664 parseargs/doc/parsecntls.inc || echo 'restore of parseargs/doc/parsecntls.inc failed' Wc_c="`wc -c < 'parseargs/doc/parsecntls.inc'`" test 4875 -eq "$Wc_c" || echo 'parseargs/doc/parsecntls.inc: original size 4875, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/parseflags.inc ============== if test -f 'parseargs/doc/parseflags.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/parseflags.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/parseflags.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/parseflags.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -p '[ \t]*' -s PARSE-FLAGS ../parseargs.h .\"---------------------------------------------------------------------------- .SH "PARSE FLAGS" .PP The following bitmasks may be combined in order to modify the behavior of the parseargs library. The parse flags for a given may be set through the use of the \fIparsecntl\fP(3) function. .\"--------------------------------------------- .IP "\fIpa_\s-1PROMPT\s+1\fP" Prompt the user for any missing arguments that are required on the command-line. No special escaping or quoting is performed on the user input. Required arguments that expect a list of values will be repeatedly prompted for (one item per line) until a blank line (followed by a carriage return) is entered. .\"--------------------------------------------- .IP "\fIpa_\s-1IGNORE\s+1\fP" Ignore any unrecognized or improperly specified command-line arguments and continue execution of the program. Normally, if an argument is unmatched (or is improperly specified), a usage message is printed program execution is terminated. .\"--------------------------------------------- .IP "\fIpa_\s-1OPTSONLY\s+1\fP" Under \s-1UNIX\s+1, setting this flag will disable the parsing of long-option syntax. This will cause all arguments starting with `+' to always be treated as a positional parameter (instead of a long-option). .\"--------------------------------------------- .IP "\fIpa_\s-1KWDSONLY\s+1\fP" Under \s-1UNIX\s+1, setting this flag disables the parsing of single-character options. This will cause all arguments starting with `-' to always be treated as a positional parameter (instead of an option). .\"--------------------------------------------- .IP "\fIpa_\s-1FLAGS1ST\s+1\fP" Setting this flag causes the parseargs library to force any and all non-positional arguments to be specified before any positional ones. As an example, under \s-1UNIX\s+1, if this flag is \s-1SET\s+1 then .I parseargs will consider the command line "\fBcmd \-x\fI arg\fR" to consist of one option and one positional argument; however the command line "\fBcmd\fI arg -x\fR" would be considered to consist of two positional arguments (the \fB\-x\fP option will be unmatched). X If this flag is \s-1UNSET\s+1, then both of the previous examples are considered to consist of one option and one positional argument. .\"--------------------------------------------- .IP "\fIpa_\s-1ANYCASE\s+1\fP" Setting this flag will cause character-case to be ignored when attempting to match single-character argument names (i.e. causes "\fB\-i\fP" and "\fB\-I\fP" will be considered equivalent). .\"--------------------------------------------- .IP "\fIpa_\s-1ARGV0\s+1\fP" Normally, the parseargs library will assume that the first argument on the command-line is the name of the command. Setting this flag tells parseargs that this is \s-1NOT\s+1 the case and that the very first argument on the command-line is a bona-fide argument to the command. .\"--------------------------------------------- .IP "\fIpa_\s-1NOCHECK\s+1\fP" Setting this flag will prevent parseargs from checking for any required arguments that were not given on the command-line. This is useful when more than one call to the parseargs library is needed to parse all the command-line arguments (which could occur if the command-line argument came from a file or from two argv-vectors). X Keeping this flag on until the final set of arguments is parsed will cause parseargs to not check for missing arguments until the last set of arguments has been parsed (by the final call to *parseargs). .\"--------------------------------------------- .IP "\fIpa_\s-1CONTINUE\s+1\fP" Setting this flag will cause subsequent calls to the parseargs library to \s-1NOT\s+1 reset the current command-state. Hence, all arguments will not be initially set to "\s-1NOT GIVEN\s+1" and other (normal) initializations are not be performed. This is useful in conjunction with the \fIpa_\s-1NOCHECK\s+1\fP flag when more than one call to .I parseargs is required to parse all the command arguments. In this scenario, \fIpa_\s-1CONTINUE\s+1\fP should be unset (the default setting) for the very first call to .I parseargs, but should then be set before any subsequent calls to .I parseargs are made. .\"--------------------------------------------- .IP "\fIpa_\s-1NOCMDENV\s+1\fP" Setting this flag prevents parseargs from checking the \s-1\fICMD-NAME\fP_ARGS\s+1 environment variable (or symbol) for any user-defined default command arguments. .\"--------------------------------------------- .IP "\fIpa_\s-1COPYF\s+1\fP" When this flag is \s-1OFF\s+1 (the default), a value of \s-1FALSE\s+1 is provided as the \fIcopyf\fP argument to all the arg-type .I (argXxxxx) functions when an argument is matched. Setting this flag will cause a value of \s-1TRUE\s+1 to be provided as the \fIcopyf\fP argument to all the arg-type .I (argXxxxx) functions when an argument is matched. .\"--------------------------------------------- SHAR_EOF chmod 0664 parseargs/doc/parseflags.inc || echo 'restore of parseargs/doc/parseflags.inc failed' Wc_c="`wc -c < 'parseargs/doc/parseflags.inc'`" test 5108 -eq "$Wc_c" || echo 'parseargs/doc/parseflags.inc: original size 5108, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/parsemodes.inc ============== if test -f 'parseargs/doc/parsemodes.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/parsemodes.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/parsemodes.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/parsemodes.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -p '[ \t]*' -s PARSE-MODES ../parseargs.h .\"---------------------------------------------------------------------------- .SH "PARSE MODES" .PP \fIParsecntl\fP may be used to read current command attributes, write (assign) new command attributes, or both. The mode argument to parsecntl determines the which of these three alternatives are desired. If the programmer merely wishes to assign new attributes, then invoking \fIparsecntl\fP in \fIpc_\s-1WRITE\s+1\fP mode and passing the new attributes will do the job. If the programmer wishes simply to query attributes, then invoking \fIparsecntl\fP in \fIpc_\s-1READ\s+1\fP mode and passing a pointer to the desired object in which to write the attribute settings will suffice. X If the programmer wishes to assign new attributes and at the same time find out what the attributes were before making the assignment, then programmer must invoke \fIparsecntl\fP for \fIpc_\s-1RDWR\s+1\fP mode and pass a pointer to the object containing the new attribute settings; When \fIparsecntl\fP returns, then (assuming it returns 0) the desired attributes will have been assigned and the object that contained the new attribute settings will now contain the attribute settings that were in effect before \fIparsecntl\fP was invoked. SHAR_EOF chmod 0664 parseargs/doc/parsemodes.inc || echo 'restore of parseargs/doc/parsemodes.inc failed' Wc_c="`wc -c < 'parseargs/doc/parsemodes.inc'`" test 1427 -eq "$Wc_c" || echo 'parseargs/doc/parsemodes.inc: original size 1427, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/returns.inc ============== if test -f 'parseargs/doc/returns.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/returns.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/returns.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/returns.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -p '[ \t]*' -s RETURN-CODES ../parsearegs.h .\"---------------------------------------------------------------------------- .SH "RETURN VALUE" .PP The functions in the \fIparseargs\fP library will return a value of zero upon succesful completion. They may however, return any of the following status codes (which are defined in <parseargs.h>): .\"--------------------------------------------- .IP "\fIpe_\s-1SYSTEM\s+1\fP" A system error occurred. The global variable \fIerrno\fP may indicate the problem (then again, it may not). .\"--------------------------------------------- .IP "\fIpe_\s-1SUCCESS\s+1\fP" Success, no errors encountered (zero is returned). .\"--------------------------------------------- .IP "\fIpe_\s-1SYNTAX\s+1\fP" A command-line syntax error was encountered .\"--------------------------------------------- .IP "\fIpe_\s-1DEFARGS\s+1\fP" An attempt (using \fIparsecntl\fP) was made to change the default arg-search list of a command to point to an argdesc-array which already has the given command on its default arg-search list (which would cause an infinite loop when attempting to match an unknown command-line argument). .\"--------------------------------------------- .IP "\fIpe_\s-1NOMATCH\s+1\fP" Unable to match the named argument. This occurs when the argument keyword name passed to \fIparsecntl\fP (using the \fIpc_\s-1ARGFLAGS\s+1\fP functions code) was found in the given argdesc-array or in its default-list. .\"--------------------------------------------- .IP "\fIpe_\s-1BADMODE\s+1\fP" Bad mode for given command in \fIparsecntl\fP. This occurs when \fIpc_\s-1WRITE\s+1\fP or \fIpc_\s-1RDWR\s+1\fP mode is passed to .I parsecntl in conjunction with the \fIpc_ARGFLAGS\fP functions code. .I Parsecntl will not modify existing arguments. .\"--------------------------------------------- .IP "\fIpe_\s-1BADCNTL\s+1\fP" Bad command for parsecntl. This occurs if an unknown function-code was passed to \fIparsecntl\fP. SHAR_EOF chmod 0664 parseargs/doc/returns.inc || echo 'restore of parseargs/doc/returns.inc failed' Wc_c="`wc -c < 'parseargs/doc/returns.inc'`" test 2118 -eq "$Wc_c" || echo 'parseargs/doc/returns.inc: original size 2118, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/sh_arrays.inc ============== if test -f 'parseargs/doc/sh_arrays.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/sh_arrays.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/sh_arrays.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/sh_arrays.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -n -p '[ \t]*' -I DESCRIPTION -f put_argvector ../parseargs.c .\"---------------------------------------------------------------------------- .SH ARGUMENT LISTS .PP .B Parseargs treats \s-1ARGLIST\s+1 arguments in a special way. The method used for setting up an argument list depends largely upon the syntax of shell that was specified on the command line via the \fB\-s\fP option (although \s-1ARGLIST\s+1 arguments are treated exactly the same as \s-1ARGVEC\s+1 arguments). .\"--------------- .SS "Resetting the Positional Parameters to an Argument List" .PP For the Bourne, Bourne-Again, and Korn shells, if the variable name corresponding to the \s-1ARGLIST\s+1 argument is ``\fB\-\^\-\fP'', then the positional parameters of the calling program will be re-assigned to the contents of the argument list ($1 will be the first item, $2 the second item, and so on). In this particular case, the calling program may wish to use the \fB\-u\fP option to reset the positional parameters to \s-1NULL\s+1 before making any shell-variable assignments (this way, the positional parameters will be unset if the associated list of command line arguments is not encountered). .PP Similarly for the C and TC shells, if the variable name corresponding to the \s-1ARGLIST\s+1 argument is ``\fBargv\fP'', then the positional parameters of the calling program will be re-assigned to the contents of the argument list. .PP For the Plan 9 shell (rc), if the variable name corresponding to the \s-1ARGLIST\s+1 argument is ``\fB*\fP'', then the positional parameters of the calling program will be re-assigned to the contents of the argument list. .PP For the \fIawk\fP and \fIperl\fP, if the variable name corresponding to the \s-1ARGLIST\s+1 argument is ``\fBARGV\fP'', then the positional parameters of the calling program will be re-assigned to the contents of the argument list. .SS "Bourne Shell Argument Lists" .PP For the Bourne shell, if the associated variable name is \s-1NOT\s+1 ``\fB\-\^\-\fP'' and the \fB\-A\fP option was \s-1NOT\s+1 specified, then that variable is treated as a regular shell variable and is assigned using the following syntax: .sp 2p .RS \f4name\^=\^'arg1 arg2\fP \fI...\fP\f4'\fP .RE .sp 2p After invoking \fBparseargs\fP, if you wish to go through all the words in the variable \fIname\fP and one of the words in \fIname\fP contains an \s-1IFS\s+1 character (such as a space or a tab), then that particular word will be treated by the Bourne shell as two distinct words. .sp 8p Also for the Bourne shell, If the associated variable name is \s-1NOT\s+1 ``\fB\-\^\-\fP'' and the \fB\-A\fP option \s-1WAS\s+1 specified, then that variable is treated as the root name of an array that is set using the following syntax: .sp 2p .RS .nf \f4name1\^=\^'arg1'\fP \f4name2\^=\^'arg2'\fP \0\0\0 ... .fi .RE .sp 2p and the variable ``\f4name_count\fP'' will be set to contain the number of items in the array. The user may then step through all the items in the array using the following syntax: .sp 2p .RS .nf .ft 4 i=1 while [ $i -le $name_count ] ; do X eval echo "item #$i is: " \\$name$i X i=`expr $i + 1` done .ft R .fi .RE .SS "Korn Shell Argument Lists" .PP For the Korn shell, if the associated variable name is \s-1NOT\s+1 ``\fB\-\^\-\fP'', then that variable is treated as an array and is assigned using the \fB\-A\fP option of the set command. The first item will be in \f4${name[0]}\fP, the second item will be in \f4${name[1]}\fP, etc ..., and all items may be given by \f4${name[*]}\fP or \f4${name[@]}\fP. If the associated variable name is \s-1NOT\s+1 ``\fB\-\^\-\fP'' and the \fB\-A\fP option \s-1WAS\s+1 specified, then that variable is assigned using the \fB+A\fP option of the set command (which preserves any array elements that were not overwritten by the set command). .sp 2p It should be noted that there is a bug in versions of the Korn shell earlier than 11/16/88a, in which the following: .sp 2p .RS \f4set \-A name 'arg1' 'arg2'\fP \fI...\fP .RE .sp 2p causes the positional parameters to be overwritten as an unintentional side-effect. If your version of the Korn shell is earlier than this and you wish to keep the contents of your positional parameters after invoking \fBparseargs\fP than you must save them yourself before you call \fBparseargs\fP. This may be accomplished by the following: .sp 2p .RS \f4set \-A save_parms "$@"\fP .RE .SS "C and TC Shell Argument Lists" .PP For the C and TC shells, \s-1ARGLIST\s+1 variables are treated as word-lists and are assigned using the following syntax: .sp 2p .RS \f4set name = ( 'arg1' 'arg2'\fP \fI...\fP\f4 )\fP .RE .sp 2p The first item will be in \f4$name[1]\fP, the second item will be in \f4$name[2]\fP, etc ..., and all items may be given by \f4$name\fP. Notice that Korn shell arrays start at index zero whereas C and TC shell word-lists start at index one. .SS "Bourne-Again Shell Argument Lists" .PP At present, the Free Software Foundation's Bourne-Again shell is treated exactly the same as the Bourne Shell. This will change when \fIbash\fP supports arrays. .SS "Plan 9 Shell Argument Lists" .PP For the Plan 9 shell, if the associated variable name is not ``*'' then it is considered to be word-list and set using the following syntax: .nf .RS .ft 4 name=( 'arg1' 'arg2' ... ) .ft R .RE .fi .SS "Awk Argument Lists" For \fIawk\fP, if the \fB\-A\fP option is not given, then the output for thes variable-list will be a line with the variable name, followed by a line with each of the values (each value will be separated with the field separator specified using the \fB\-S\fP option - which defaults to a space). .nf .RS .ft 4 name arg1 arg2 ... .ft R .RE .fi If the \fB\-A\fP option is given, then the associated variable is considered the root name of an array. The ouput for the array will consist of two lines for each item in the list (as in the following expample): .nf .RS .ft 4 name1 arg1 X name2 arg2 X \... .ft R .RE .fi and the variable ``\f4name_count\fP'' will have an output line showing the number of items in the array. .PP .SS "Perl Argument Lists" .PP For \fIperl\fP, each argument list is considered an array and is set using the following syntax: .nf .RS .ft 4 @name=( arg1 , arg2 , ... ) .ft R .RE .fi .SS ""A Final Note on Argument Lists" .PP The word-lists used by the C shell, the arrays used by the Korn shell, the Plan 9 shell, \fIawk\fP, \fIperl\fP, and the positional parameters used by all shells (if overwritten by \fBparseargs\fP) will preserve any \s-1IFS\s+1 characters in their contents. That is to say that if an item in one of the aforementioned multi-word lists contains any \s-1IFS\s+1 characters, it will not be split up into multiple items but will remain a single item which contains \s-1IFS\s+1 characters. SHAR_EOF chmod 0664 parseargs/doc/sh_arrays.inc || echo 'restore of parseargs/doc/sh_arrays.inc failed' Wc_c="`wc -c < 'parseargs/doc/sh_arrays.inc'`" test 6926 -eq "$Wc_c" || echo 'parseargs/doc/sh_arrays.inc: original size 6926, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/shells.inc ============== if test -f 'parseargs/doc/shells.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/shells.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/shells.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/shells.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -p '[ \t]*' -s SHELLS ../parseargs.c .\"---------------------------------------------------------------------------- .SH SHELLS .PP After the command line has been parsed, \fBparseargs\fP will print on standard output, a script to set the shell variables which correspond to arguments that were present on the command-line. This script may be evaluated by redirecting it to a file and then executing the file, or by directly evaluating the output from \fBparseargs\fP (under most \s-1UNIX\s+1 shells, this could be done using \fBeval\fP). If any arguments on the command line contained any special characters that needed to be escaped from the shell, these characters will remain intact (not be evaluated by the shell) in the corresponding shell variable. .PP The \fB\-s\fP \fIshell\fP option may be used to tell \fBparseargs\fP which shell syntax to use. At present, \fBparseargs\fP only recognizes ``sh'', ``csh'', ``ksh'', ``tcsh'', ``bash'', ``rc'', ``awk'', and ``perl'' as valid command interpreters. \fIAwk\fP output is slightly different from that of the other shells in that the actual variable setting are not printed but each line of an associative array is printed (the first field is the array index, the second is the value for that index). If no shell is specified, then the Bourne shell (``sh'') will be assumed. .PP If the user wishes to use a value other than ``\s-1TRUE\s+1'' for a boolean flag that is true, this may be done using the \fB\-T\fP \fIstring\fP option. The same may also be done for a boolean flag that is false using the \fB\-F\fP \fIstring\fP option. .PP .B Parseargs will only set the values of variables that correspond to arguments that were given on the command line. If a particular argument was not supplied on the command line, then no assignment is made for the corresponding shell variable and it will have the same value that it had before .B parseargs was invoked. The only exception to this is that if the \fB\-u\fP option is specified, then the positional parameters are unset before any shell variable assignments (which may reset the positional parameters) are made. SHAR_EOF chmod 0664 parseargs/doc/shells.inc || echo 'restore of parseargs/doc/shells.inc failed' Wc_c="`wc -c < 'parseargs/doc/shells.inc'`" test 2275 -eq "$Wc_c" || echo 'parseargs/doc/shells.inc: original size 2275, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/sparseargs3.inc ============== if test -f 'parseargs/doc/sparseargs3.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/sparseargs3.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/sparseargs3.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/sparseargs3.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -n -p '[ \t]*' -I DESCRIPTION -f sparseargs ../xparse.c .\"---------------------------------------------------------------------------- .PP Given a single string and an argdesc array, \fIsparseargs\fP will parse arguments from a string in much the same manner as \fIparseargs\fP. .I Sparseargs will split the given string up into a vector of whitespace separated tokens and then attempt to parse the resultant vector as if it were given as \fIargv[]\fP on the command-line. NO special treatment is given to characters such as single-quotes, double-quotes, or anything else. \fISparseargs\fP will always assume that any whitespace characters are intended as argument separators. X SHAR_EOF chmod 0664 parseargs/doc/sparseargs3.inc || echo 'restore of parseargs/doc/sparseargs3.inc failed' Wc_c="`wc -c < 'parseargs/doc/sparseargs3.inc'`" test 836 -eq "$Wc_c" || echo 'parseargs/doc/sparseargs3.inc: original size 836, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/usage3.inc ============== if test -f 'parseargs/doc/usage3.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/usage3.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/usage3.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/usage3.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -n -p '[ \t]*' -I DESCRIPTION -f usage ../xparse.c .\"---------------------------------------------------------------------------- .PP Given an argdesc array, \fIusage\fP will print the usage for the given command in the format specified by the user's \s-1USAGECNTL\s+1 environment variable. SHAR_EOF chmod 0664 parseargs/doc/usage3.inc || echo 'restore of parseargs/doc/usage3.inc failed' Wc_c="`wc -c < 'parseargs/doc/usage3.inc'`" test 449 -eq "$Wc_c" || echo 'parseargs/doc/usage3.inc: original size 449, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/doc/vparseargs3.inc ============== if test -f 'parseargs/doc/vparseargs3.inc' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/doc/vparseargs3.inc (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/doc/vparseargs3.inc (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/doc/vparseargs3.inc' && .\"---------------------------------------------------------------------------- .\"-- This text was extracted using the following command: .\"-- xdoc -man -n -p '[ \t]*' -I DESCRIPTION -f vparseargs ../xparse.c .\"---------------------------------------------------------------------------- .PP .I Vparseargs takes an argdesc array, the number of arguments to parse, and a (possibly NULL terminated) list of argument-strings and parses them in much the same manner as \fIparseargs\fP. Unlike .I sparseargs, .I vparseargs assumes that all parameters are already split up into tokens, hence any whitespace characters contained in any of the string-parameters are used as is (and will be considered a part of an argument name or value). X SHAR_EOF chmod 0664 parseargs/doc/vparseargs3.inc || echo 'restore of parseargs/doc/vparseargs3.inc failed' Wc_c="`wc -c < 'parseargs/doc/vparseargs3.inc'`" test 737 -eq "$Wc_c" || echo 'parseargs/doc/vparseargs3.inc: original size 737, current size' "$Wc_c" rm -f _shar_wnt_.tmp fi # ============= parseargs/ibm_args.c ============== if test -f 'parseargs/ibm_args.c' -a X"$1" != X"-c"; then echo 'x - skipping parseargs/ibm_args.c (File already exists)' rm -f _shar_wnt_.tmp else > _shar_wnt_.tmp echo 'x - extracting parseargs/ibm_args.c (Text)' sed 's/^X//' << 'SHAR_EOF' > 'parseargs/ibm_args.c' && /************************************************************************* ** ^FILE: ibm_args.c - parse MS-DOS and OS/2 argument vectors ** ** ^DESCRIPTION: ** This file contains the routines used to parse MS-DOS and OS/2 ** argument vectors and to print MS-DOS and OS/2 usage messages. ** ** ^HISTORY: ** 01/02/91 Brad Appleton <brad@ssd.csd.harris.com> Created ***^^**********************************************************************/ X #include <ctype.h> #include <useful.h> #include "strfuncs.h" #include "pgopen.h" X #define PARSEARGS_PRIVATE /* include private definitions */ #include "parseargs.h" X EXTERN VOID syserr ARGS((const char *, ...)); EXTERN VOID usrerr ARGS((const char *, ...)); EXTERN char *getenv ARGS((const char *)); EXTERN VOID get_winsize ARGS((int, int *, int *)); X VERSIONID("$Header: parseargs.c,v 2.1 89/12/30 20:59:48 eric Exp $"); X /*************************************************************************** ** ^GLOBAL-VARIABLE: OptPrefix, KwdPrefix ** ** ^VISIBILITY: ** static-global (visible to all functions in this file). ** ** ^DESCRIPTION: ** OptPrefix contains the single character prefix used to precede SHAR_EOF true || echo 'restore of parseargs/ibm_args.c failed' fi echo 'End of part 4' echo 'File parseargs/ibm_args.c is continued in part 5' echo 5 > _shar_seq_.tmp exit 0 exit 0 # Just in case... -- Kent Landfield INTERNET: kent@sparky.IMD.Sterling.COM Sterling Software, IMD UUCP: uunet!sparky!kent Phone: (402) 291-8300 FAX: (402) 291-4362 Please send comp.sources.misc-related mail to kent@uunet.uu.net.