Usenet 1994 October

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

/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / misc / volume18 / parseargs / patch04a / DOCPATCH < prev

Wrap

Text File | 1991-04-26 | 47.4 KB | 1,651 lines

*** /hx1d3/lp/brad/parseargs_patch03/parseargs/argtype3.txt Wed Apr 10 09:55:51 1991 --- argtype3.txt Mon Apr 15 08:31:00 1991 *************** *** 42,51 **** called when an argument of that particular type is matched by one of the argument parsing function in parseargs(3). When such an argument is matched, its argument translation ! routines is invoked and is passed (1) the address of the argument descriptor for the matched argument, (2) the possi- ble argument string for that matched argument, and (3) a ! boolean filed that is TRUE only if the second parameter points to temporary storage (indicating that some copying may need to be done instead of just pointing to the same object). --- 42,51 ---- called when an argument of that particular type is matched by one of the argument parsing function in parseargs(3). When such an argument is matched, its argument translation ! routine is invoked and is passed (1) the address of the argument descriptor for the matched argument, (2) the possi- ble argument string for that matched argument, and (3) a ! boolean field that is TRUE only if the second parameter points to temporary storage (indicating that some copying may need to be done instead of just pointing to the same object). *************** *** 229,235 **** followed by the type of the items in the vector. SEE ALSO ! parseargs(3), parseargs(3), parsecntl(1), --- 229,235 ---- followed by the type of the items in the vector. SEE ALSO ! parseargs(3), parseargs(1), parsecntl(3) *** /hx1d3/lp/brad/parseargs_patch03/parseargs/parseargs1.txt Wed Apr 10 09:55:52 1991 --- parseargs1.txt Mon Apr 15 08:31:18 1991 *************** *** 9,19 **** parseargs - parse command line arguments in shell scripts SYNOPSIS ! parseargs [-U] [-M] [-T string] [-F string] [-A] [-a arg- ! spec] [-e name] [-f file] [-l] [-o] [-s shell] ! [-u] [-i] [-p] -- name [arguments ...] OPTIONS -U just print program usage, do not parse the command line --- 9,22 ---- parseargs - parse command line arguments in shell scripts SYNOPSIS ! parseargs [-#UMCAlouip1] [-S separator] [-T string] ! [-F string] [-a arg-spec] [-e name] [-f file] ! [-s shell] -- name [arguments ...] OPTIONS + -# just print the version and patchlevel, do not + parse the command line + -U just print program usage, do not parse the command line *************** *** 20,25 **** --- 23,31 ---- -M just print (n|t)roff -man manual page template, do not parse the command line + -S separator field-separator-string used to delimit array + elements (default= + -T string string to use for true boolean arguments (default=``TRUE'') *************** *** 26,31 **** --- 32,40 ---- -F string string to use for false boolean arguments (default=``'') + -C Ignore the difference between upper and lower + case when parsing single character options. + -A modify array behavior for the specified shell. -a arg-spec argument specification string *************** *** 48,76 **** -p prompt the user for missing required arguments - -i ignore bad command-line syntax and continue - processing (instead of aborting) - ARGUMENTS - -- Indicates that any remaining options are - intended for the calling program. - name name of calling program - Page 1 ! PARSEARGS(1) PARSEARGS(1) arguments arguments to calling program DESCRIPTION --- 57,89 ---- -p prompt the user for missing required arguments + Page 1 + PARSEARGS(1) PARSEARGS(1) ! -i ignore bad command-line syntax and continue ! processing (instead of aborting) + -1 Force any and all non-positional parameters to + be specified before any positional parameters + on the command-line. + ARGUMENTS + -- Indicates that any remaining options are + intended for the calling program. + name name of calling program + arguments arguments to calling program DESCRIPTION *************** *** 98,131 **** on standard output that is suitable for input to nroff or troff using the -man macro package. 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: - name 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 ``-x'' - prefix) are indicated by passing a ``space'' - character. - flags Flags modifying the semantics of this entry. - These should have one of ARGREQ to indicate a - required argument or ARGOPT to indicate an - optional argument (ARGOPT is the default unless - ARGREQ is specified). ARGPOS can be ``ored'' in - to indicate a positional argument that may also be - keyword matched. ARGNOVAL 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 - Page 2 --- 111,131 ---- on standard output that is suitable for input to nroff or troff using the -man macro package. + Given no other arguments parseargs -# prints on standard + output, the current version and patchlevel of the running + version of parseargs. + + The argument specification string contains one entry for ! each possible flag. Entries in the argument 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: Page 2 *************** *** 137,154 **** ! implemented by the programmer; parseargs already ! knows which pre-defined argument types take an ! argument. ARGVALOPT can be ``ored'' in to indicate that an argument to the option may be optionally supplied on the command-line, but is ! not required. ARGVALREQ can be ``ored'' in to indicate that an argument to the option is required (this is the default behavior for options ! that take arguments). ARGLIST 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. ARGHIDDEN can be ``ored'' in to indicate a flag that should not be printed in usage messages - for example, flags intended for internal debugging purposes. --- 137,165 ---- ! name 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 ``-x'' ! prefix) are indicated by passing a ``space'' ! character. ! ! flags Flags modifying the semantics of this entry. ! These should have one of ARGREQ to indicate a ! required argument or ARGOPT to indicate an ! optional argument (ARGOPT is the default unless ! ARGREQ is specified). ARGPOS may be ``ored'' in ! to indicate a positional argument that may also be ! keyword matched. ARGVALOPT may be ``ored'' in to indicate that an argument to the option may be optionally supplied on the command-line, but is ! not required. ARGVALREQ may be ``ored'' in to indicate that an argument to the option is required (this is the default behavior for options ! that take arguments). ARGLIST may be ``ored'' in (using the `|' character) to indicate that an argument is actually a list of one or more ! arguments from the command line. ARGHIDDEN may be ``ored'' in to indicate a flag that should not be printed in usage messages - for example, flags intended for internal debugging purposes. *************** *** 177,194 **** The argument specification string must be terminated by the single string: ``ENDOFARGS''. - Note that the comma character (',') is used to separate all - fields within an entry, and to separate the entries - themselves. For this reason, no field in any entry may - contain a comma unless it appears inside of double or single - quotes. - 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 -a --- 188,194 ---- *************** *** 203,208 **** --- 203,220 ---- + Note that the comma character (',') is used to separate all + fields within an entry, and to separate the entries + themselves. For this reason, no field in any entry may + contain a comma unless it appears inside of double or single + quotes. + + 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 -a ``string'' 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 *************** *** 244,263 **** string option. The same may also be done for a boolean flag that is false using the -F string option. - 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 - parseargs was invoked. The only exception to this is that if - the -u option is specified, then the positional parameters - are unset before any shell variable assignments (which may - reset the positional parameters) are made. - - - Page 4 --- 256,263 ---- *************** *** 269,274 **** --- 269,284 ---- + 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 + parseargs was invoked. The only exception to this is that if + the -u option is specified, then the positional parameters + are unset before any shell variable assignments (which may + reset the positional parameters) are made. + The double-dash (``--'') which precedes the name and arguments of the calling program is needed in order for parseargs to be able to distinguish options to itself from *************** *** 280,285 **** --- 290,310 ---- options) are to be permitted by specifying the -o (-l) option on the command-line. + SPECIFYING PARSE-BEHAVIOR + The -C, -p, -i, and -1 switches may be used to modify the + command-line parsing behavior of the invoking script. + Specifying -C will cause case-differences in single- + character options to be ignored. Specifying -p will cause + the user to be interactively prompted for any missing + required arguments. Specifying -i will cause syntactically + incorrect arguments to be ignored (instead of having a usage + message printed and execution terminated). Specifying -1 + will force all non-positional parameters to precede any + positional parameters on the command-line (hence anything on + the command-line after a positional parameter that resembles + a keyword parameter will nevertheles be interpreted as a + positional parameter). + OPTIONS WITH OPTIONAL ARGUMENTS Options that may take an optional argument need special consideration. The shell programmer needs to know whether *************** *** 297,302 **** --- 322,340 ---- the shell variable associated with the option in the argument description string. + + + Page 5 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + ARGUMENT LISTS Parseargs treats ARGLIST arguments in a special way. The method used for setting up an argument list depends largely *************** *** 321,340 **** positional parameters of the calling program will be re- assigned to the contents of the argument list. - - - - Page 5 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - For the Plan 9 shell (rc), if the variable name corresponding to the ARGLIST argument is ``*'', then the positional parameters of the calling program will be re- --- 359,364 ---- *************** *** 344,349 **** --- 368,374 ---- ARGLIST argument is ``ARGV'', then the positional parameters of the calling program will be re-assigned to the contents of the argument list. + Bourne Shell Argument Lists For the Bourne shell, if the associated variable name is NOT *************** *** 356,362 **** contains an IFS character (such as a space or a tab), then that particular word will be treated by the Bourne shell as two distinct words. - Also for the Bourne shell, If the associated variable name is NOT ``--'' and the -A option WAS specified, then that variable is treated as the root name of an array that is set --- 381,386 ---- *************** *** 363,368 **** --- 387,406 ---- using the following syntax: name1='arg1' name2='arg2' + + + + Page 6 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + ... and the variable ``name_count'' will be set to contain the number of items in the array. The user may then step *************** *** 387,406 **** overwritten by the set command). It should be noted that there is a bug in versions of the Korn shell earlier than 11/16/88a, in which the following: - - - - Page 6 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - set -A name 'arg1' 'arg2' ... causes the positional parameters to be overwritten as an unintentional side-effect. If your version of the Korn shell --- 425,430 ---- *************** *** 409,414 **** --- 433,439 ---- must save them yourself before you call parseargs. This may be accomplished by the following: set -A save_parms "$@" + C and TC Shell Argument Lists For the C and TC shells, ARGLIST variables are treated as *************** *** 418,436 **** in $name[2], etc ..., and all items may be given by $name. Notice that Korn shell arrays start at index zero whereas C and TC shell word-lists start at index one. - Bourne-Again Shell Argument Lists At present, the Free Software Foundation's Bourne-Again shell is treated exactly the same as the Bourne Shell. This will change when bash supports arrays. Plan 9 Shell Argument Lists 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: name=( 'arg1' 'arg2' ... ) - Awk Argument Lists For awk, if the -A option is not given, then the output for thes variable-list will be a line with the variable name, --- 443,474 ---- in $name[2], etc ..., and all items may be given by $name. Notice that Korn shell arrays start at index zero whereas C and TC shell word-lists start at index one. Bourne-Again Shell Argument Lists At present, the Free Software Foundation's Bourne-Again shell is treated exactly the same as the Bourne Shell. This will change when bash supports arrays. + Plan 9 Shell Argument Lists For the Plan 9 shell, if the associated variable name is not ! ``*'' then it is considered to be a word-list and set using ! ! ! ! Page 7 ! ! ! ! ! ! ! PARSEARGS(1) PARSEARGS(1) ! ! ! the following syntax: name=( 'arg1' 'arg2' ... ) Awk Argument Lists For awk, if the -A option is not given, then the output for thes variable-list will be a line with the variable name, *************** *** 442,448 **** If the -A 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): name1 arg1 --- 480,486 ---- If the -A 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 example): name1 arg1 *************** *** 452,477 **** and the variable ``name_count'' will have an output line showing the number of items in the array. - - - - - Page 7 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - Perl Argument Lists For perl, each argument list is considered an array and is set using the following syntax: ! @name=( arg1 , arg2 , ... ); A Final Note on Argument Lists The word-lists used by the C shell, the arrays used by the --- 490,501 ---- and the variable ``name_count'' will have an output line showing the number of items in the array. Perl Argument Lists For perl, each argument list is considered an array and is set using the following syntax: ! @name=( 'arg1' , 'arg2' , ... ); ! A Final Note on Argument Lists The word-lists used by the C shell, the arrays used by the *************** *** 495,500 **** --- 519,538 ---- ARGLISTs and ARGVECs set in ``CMD_ARGS'' will be appended from the command-line if they are selected). + + + + Page 8 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + It is important to note that the contents of the ``CMD_ARGS'' environment variable are NOT expanded by the shell and hence any special characters (such as quotes or *************** *** 519,538 **** of parsecntl(3). The user may set his (or her) own desired parsing behavior through the use of the ``PARSECNTL'' environment variable. By indicating any number of flags - - - - Page 8 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - (possibly negated) the user will directly modify the behavior of the parseargs library. Flags may be combined by placing a `+' or `|' character in between flags. A switch is --- 557,562 ---- *************** *** 551,570 **** Ignore 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 and ! program execution is terminated. OptsOnly Under UNIX, 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). KwdsOnly Under UNIX, 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). LoptsOnly --- 575,608 ---- Ignore Ignore any unrecognized or improperly specified command-line arguments and continue execution of the ! program. Normally, if a required argument is unmatched ! (or an argument is improperly specified), a usage ! message is printed program execution is terminated. OptsOnly Under UNIX, 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). + + + + Page 9 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + KwdsOnly Under UNIX, 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). LoptsOnly *************** *** 585,609 **** one positional argument. CaseIgnore - - - Page 9 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - - Setting this flag causes character-case to be ignored - when attempting to match single-character argument - names (i.e. causes "-i" and "-I" will be considered - equivalent). - If the environment variable ``PARSECNTL'' is empty or undefined, then the parsing behavior set by the programmer is used. If the programmer has not explicitly used --- 623,633 ---- one positional argument. CaseIgnore + Setting this flag will cause character-case to be + ignored when attempting to match single-character + argument names (i.e. causes "-i" and "-I" to be + considered equivalent). If the environment variable ``PARSECNTL'' is empty or undefined, then the parsing behavior set by the programmer is used. If the programmer has not explicitly used *************** *** 627,638 **** only a command-line synopsis is printed (this is also refferred to as ``terse'' mode). The other two ``modes'' control the displaying of option syntax and long-option - syntax. A mode may be explicitly disabled by preceding its - corresponding string with the `!' character. The ``modes'' - which correspond to the possible values of the ``USAGECNTL'' - environment variable are given by the following table. Quiet No usage message of any kind is displayed. --- 651,676 ---- only a command-line synopsis is printed (this is also refferred to as ``terse'' mode). The other two ``modes'' control the displaying of option syntax and long-option + + Page 10 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + + syntax. A mode may be explicitly disabled by preceding its + corresponding string with the `!' or `-' character. The + ``modes'' which correspond to the possible values of the + ``USAGECNTL'' environment variable are given by the + following table. + Quiet No usage message of any kind is displayed. *************** *** 651,670 **** Description The command description is printed. - - - - Page 10 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - Terse Terse mode, just print command-line synopsis. --- 689,694 ---- *************** *** 680,685 **** --- 704,710 ---- KeyWords Same as LongOpts. + If the environment variable ``USAGECNTL'' is empty or undefined, then the default usage level (which is presently ``Verbose + Options'') will be used. *************** *** 689,697 **** specification for a Bourne shell script: #!/bin/sh - RepCount=2; Verbose=""; ARGSPEC=" 'c', ARGOPT, argInt, RepCount, 'count {# times to repeat}', 'v', ARGOPT, argBool, Verbose, 'verbose {turn on verbose mode}', --- 714,736 ---- specification for a Bourne shell script: #!/bin/sh RepCount=2; Verbose=""; + + + + + Page 11 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + ARGSPEC=" 'c', ARGOPT, argInt, RepCount, 'count {# times to repeat}', 'v', ARGOPT, argBool, Verbose, 'verbose {turn on verbose mode}', *************** *** 701,708 **** ' ', ARGOPT|ARGLIST, listStr, Files, 'files {files to process}', ENDOFARGS " - eval `echo "$ARGUMENTS" | parseargs -s sh -- $0 "$@"` This describes a Bourne shell script accepting up to three flag arguments and one or two positional arguments, plus a --- 740,747 ---- ' ', ARGOPT|ARGLIST, listStr, Files, 'files {files to process}', ENDOFARGS " + eval `echo "$ARGSPEC" | parseargs -s sh -- $0 "$@"` This describes a Bourne shell script accepting up to three flag arguments and one or two positional arguments, plus a *************** *** 717,736 **** FALSE (an empty string). -X A Boolean ``X Rated'' flag. This is not - - - - Page 11 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - printed in the usage message. The two positional arguments are both strings, as is the --- 756,761 ---- *************** *** 758,763 **** --- 783,802 ---- associated command line variables, and then prints its command usage. + + + + Page 12 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + #!/bin/sh # test.sh - Bourne shell script to test out the parseargs command! # *************** *** 783,802 **** ## parse command-line and save assignments in a temporary file ## parseargs -s sh -e ARGUMENTS -u -- "$NAME" "$@" >/tmp/tmp$$ - - - - Page 12 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - if [ $? -ne 0 ] then rm -f /tmp/tmp$$; exit 2 ## non-zero status (usage given) fi --- 822,827 ---- *************** *** 825,838 **** Parseargs may exit with one of the following status codes: -1 Some type of system error occurred during execution, causing the program to exit prematurely. 0 Normal exit status (no problems were encountered). ! 1 The calling program specified the -U or the -M option ! to parseargs, or specified an argUsage flag on the ! command line. Only the appropriate message is displayed. 2 A command line syntax error was encountered by --- 850,876 ---- Parseargs may exit with one of the following status codes: + + + Page 13 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + -1 Some type of system error occurred during execution, causing the program to exit prematurely. 0 Normal exit status (no problems were encountered). ! 1 The calling program specified the -#, the -U or the -M ! option to parseargs, or specified an argUsage flag on ! the command line. Only the appropriate message is displayed. 2 A command line syntax error was encountered by *************** *** 848,868 **** 4 A syntax error was encountered in the argument specification string that was specified to parseargs. - - - - - Page 13 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - FILES /usr/local/parseargs.pl This file defines a perl function named parseargs to --- 886,891 ---- *************** *** 892,897 **** --- 915,934 ---- -f-arg will properly assign the string ``-arg'' to the option + + + + Page 14 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + whereas the following: -f -arg *************** *** 916,934 **** Hence multiple ``leading dash'' arguments may specified as follows: - - - Page 14 - - - - - - - PARSEARGS(1) PARSEARGS(1) - - - -f-dash_arg1 -f-dash_arg2 ... BUGS --- 953,958 ---- *************** *** 957,962 **** --- 981,1000 ---- Parseargs cannot properly preserve any newlines in shell variables if the eval command is used to read its output + + + + Page 15 + + + + + + + PARSEARGS(1) PARSEARGS(1) + + + (this is a shortcoming of the eval command, not of parseargs). If the user is concerned about this particular case, then the user should redirect the output from *************** *** 966,975 **** or characters following a newline may be lost, in any variables that are set by parseargs. - Parseargs(1) is subject to the same caveats as parseargs(3). - Refer to the CAVEATS section of the parseargs(3) manual - page(s) for more information. - AUTHOR Brad Appleton (brad@ssd.csd.harris.com) Harris Computer Systems, Fort Lauderdale, FL USA --- 1004,1009 ---- *************** *** 984,990 **** ! Page 15 --- 1018,1056 ---- ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! Page 16 *** /hx1d3/lp/brad/parseargs_patch03/parseargs/parseargs3.txt Wed Apr 10 09:56:01 1991 --- parseargs3.txt Mon Apr 15 08:31:33 1991 *************** *** 6,22 **** NAME ! parseargs, usage - parse command line argument vectors SYNOPSIS #include <parseargs.h> ! 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, int argc, ... ) ! void usage( const ARGDESC *argd ) DESCRIPTION Given a vector of string-valued arguments such as that --- 6,23 ---- NAME ! parseargs - parse command line argument vectors SYNOPSIS #include <parseargs.h> ! 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, int argc, ... ); ! void usage( const ARGDESC *argd ); ! extern const char *ProgName; DESCRIPTION Given a vector of string-valued arguments such as that *************** *** 27,50 **** argument values that are syntactically incorrect. Given a readable input stream and an argdesc array, fpar- ! seargs will parse arguments in a file in much the same ! manner as parseargs. A maximum-line length of 255 charac- ! ters is imposed. NO ``escaping'' of any kind is performed. ! Comments of a limited form are permitted: if the first non- ! whitespace character on a line is a '#' (or '!' for VMS) ! then that entire line is considered a comment and is ! ignored. If a value is provided for an argument that is NOT ! a list or a vector, then the value MUST be on the same line ! as the argument (in other words, ``-v val'' is fine but ! ``-v\nval'' is a not). Given an ArgList and an argdesc array, lparseargs will parse ! arguments in an ArgList in much the same manner as par- ! seargs. Given a single string and an argdesc array, sparseargs will ! parse arguments from a string in much the same manner as ! parseargs. 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 argv[] on the command-line. NO special treatment is given to charac- --- 28,50 ---- argument values that are syntactically incorrect. Given a readable input stream and an argdesc array, fpar- ! seargs will parse arguments in a file in the same manner as ! parseargs. A maximum-line length of 255 characters is ! imposed. NO ``escaping'' of any kind is performed. Comments ! of a limited form are permitted: if the first non-whitespace ! character on a line is a '#' (or '!' for VMS) then that ! entire line is considered a comment and is ignored. If a ! value is provided for an argument that is NOT a list or a ! vector, then the value MUST be on the same line as the argu- ! ment (in other words, ``-v val'' is fine but ``-v\nval'' is ! a not). Given an ArgList and an argdesc array, lparseargs will parse ! arguments in an ArgList in the same manner as parseargs. Given a single string and an argdesc array, sparseargs will ! parse arguments from a string in much the manner as par- ! seargs. 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 argv[] on the command-line. NO special treatment is given to charac- *************** *** 52,62 **** Sparseargs will always assume that any whitespace characters are intended as argument separators. - 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 ! parseargs. Unlike sparseargs, vparseargs assumes that all --- 52,62 ---- Sparseargs will always assume that any whitespace characters are intended as argument separators. Vparseargs takes an argdesc array, the number of arguments to parse, and a (possibly NULL terminated) list of ! argument-strings and parses them in the same manner as par- ! seargs. Unlike sparseargs, vparseargs assumes that all ! parameters are already split up into tokens, hence any *************** *** 71,86 **** ! parameters are already split up into tokens, hence any whi- ! tespace characters contained in any of the string-parameters ! are used as is (and will be considered a part of an argument ! name or value). - Given an argdesc array, usage will print the usage for the given command in the format specified by the user's USAGECNTL environment variable. THE ARGUMENT STRUCTURE The basic type used by the parseargs library is the argument descriptor (or "argdesc" for short). An ARGDESC structure is --- 71,90 ---- ! 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). Given an argdesc array, usage will print the usage for the given command in the format specified by the user's USAGECNTL environment variable. + After returning from any of the aforementioned functions, + the global string ProgName will contain the name of the com- + mand corresponding to the argument-descriptor array that was + most recently operated upon by one the functions in the par- + seargs(3) function library. + THE ARGUMENT STRUCTURE The basic type used by the parseargs library is the argument descriptor (or "argdesc" for short). An ARGDESC structure is *************** *** 120,131 **** this field must correspond to the name of one of the argument type functions described in argtype(3). - ARBPTR ad_valp; - This field is a generic pointer to the storage used to - represent the internal value of the command-line - Page 2 --- 124,131 ---- *************** *** 137,149 **** ! argument. It may be a pointer to a number, a boolean ! value, a string, a list, or anything else for which ! there exists a corresponding arg-type function to use ! in the ad_type field. In the case of of parseargs(1) ! this field must be the name of the corresponding shell ! variable which will eventually hold the value of the ! argument given on the command-line. const char *ad_prompt; This field contains the long-name of the argument and --- 137,152 ---- ! ARBPTR ad_valp; ! This field is a generic pointer to the storage used to ! represent the internal value of the command-line argu- ! ment. It may be a pointer to a number, a boolean value, ! a string, a list, or anything else for which there ! exists a corresponding arg-type function to use in the ! ad_type field. In the case of of parseargs(1) this ! field must be the name of the corresponding shell vari- ! able which will eventually hold the value of the argu- ! ment given on the command-line. const char *ad_prompt; This field contains the long-name of the argument and *************** *** 155,161 **** contains any uppercase characters, then the substring of long-name consisting of all uppercase characters is used as the argument keyword and the entire long-name ! is used as the name of the argument (if a value my be supplied). The long-name may be matched by supplying a unique prefix of either the argument keyword or the argument name. --- 158,164 ---- contains any uppercase characters, then the substring of long-name consisting of all uppercase characters is used as the argument keyword and the entire long-name ! is used as the name of the argument (if a value may be supplied). The long-name may be matched by supplying a unique prefix of either the argument keyword or the argument name. *************** *** 173,179 **** char *InFile; char *OutFile = CHARNULL; BOOL XRated = FALSE; ! struct namelist *Files = NULL; ARGDESC Args[] = { --- 176,182 ---- char *InFile; char *OutFile = CHARNULL; BOOL XRated = FALSE; ! ArgList *Files = ARGLISTNULL; ARGDESC Args[] = { *************** *** 183,197 **** ' ', ARGREQ, argStr, __ &InFile, "INPUTfile {input file}", ' ', ARGOPT, argStr, __ &OutFile, "OUTPUTfile {output file}", 'X', ARGHIDDEN, argBool, __ &XRated, "XratedMODE {naughty stuff!}", ! ' ', ARGOPT|ARGLIST, argStr, __ &Files, "File {files to be read}", ENDOFARGS }; - - - Page 3 --- 186,197 ---- ' ', ARGREQ, argStr, __ &InFile, "INPUTfile {input file}", ' ', ARGOPT, argStr, __ &OutFile, "OUTPUTfile {output file}", 'X', ARGHIDDEN, argBool, __ &XRated, "XratedMODE {naughty stuff!}", ! ' ', ARGLIST, listStr, __ &Files, "File {files to be read}", ENDOFARGS }; Page 3 *************** *** 379,386 **** arg_sdesc(ad) Return the description of an argument. If a description was supplied, the ARGDESCRIBED flag will be set and the ! description will immediately follow the terminating NUL ! byte of the string name. ARG_isDESCRIBED(ad) Evaluates to TRUE only if an argument description was --- 379,386 ---- arg_sdesc(ad) Return the description of an argument. If a description was supplied, the ARGDESCRIBED flag will be set and the ! description will immediately follow the terminating ! NULL byte of the string name. ARG_isDESCRIBED(ad) Evaluates to TRUE only if an argument description was *************** *** 448,454 **** usage messages. CMD MACROS ! Parseargs.h defines a set of macros to allow a more "self documenting" approach to declaring argument-descriptor arrays. The "old-style" is still accepted (but if used it is recommended that the STARTOFARGS macro is used in conjunc- --- 448,454 ---- usage messages. CMD MACROS ! <parseargs.h> defines a set of macros to allow a more "self documenting" approach to declaring argument-descriptor arrays. The "old-style" is still accepted (but if used it is recommended that the STARTOFARGS macro is used in conjunc- *************** *** 606,625 **** Ignore 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 and ! program execution is terminated. OptsOnly Under UNIX, 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). KwdsOnly Under UNIX, setting this flag disables the parsing of single-character options. This will cause all argu- ! ments starting with '-' to always be treated as a posi- tional parameter (instead of an option). LoptsOnly --- 606,625 ---- Ignore Ignore any unrecognized or improperly specified command-line arguments and continue execution of the ! program. Normally, if a required argument is unmatched ! (or an argument is improperly specified), a usage mes- ! sage is printed program execution is terminated. OptsOnly Under UNIX, 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). KwdsOnly Under UNIX, setting this flag disables the parsing of single-character options. This will cause all argu- ! ments starting with `-' to always be treated as a posi- tional parameter (instead of an option). LoptsOnly *************** *** 640,648 **** positional argument. CaseIgnore ! Setting this flag causes character-case to be ignored ! when attempting to match single-character argument ! names (i.e. causes "-i" and "-I" will be considered equivalent). If the environment variable ``PARSECNTL'' is empty or unde- --- 640,648 ---- positional argument. CaseIgnore ! Setting this flag will cause character-case to be ! ignored when attempting to match single-character argu- ! ment names (i.e. causes "-i" and "-I" to be considered equivalent). If the environment variable ``PARSECNTL'' is empty or unde- *************** *** 683,691 **** ferred to as ``terse'' mode). The other two ``modes'' con- trol the displaying of option syntax and long-option syntax. A mode may be explicitly disabled by preceding its ! corresponding string with the `!' character. The ``modes'' ! which correspond to the possible values of the ``USAGECNTL'' ! environment variable are given by the following table. Quiet No usage message of any kind is displayed. --- 683,692 ---- ferred to as ``terse'' mode). The other two ``modes'' con- trol the displaying of option syntax and long-option syntax. A mode may be explicitly disabled by preceding its ! corresponding string with the `!' or `-' character. The ! ``modes'' which correspond to the possible values of the ! ``USAGECNTL'' environment variable are given by the follow- ! ing table. Quiet No usage message of any kind is displayed. *************** *** 719,725 **** - Page 11 --- 720,725 ---- *************** *** 759,766 **** vectors however need a set of flags for each item they con- tain. Once an arg-list has been created, it may be deallo- cated using the function listFree. ListFree takes one param- ! eter: first of which is the address of the first item in the ! arg-list. An alternative to argument-lists is argument vectors (or arg-vectors). Arg-vectors use the ARGVEC flag instead of --- 759,765 ---- vectors however need a set of flags for each item they con- tain. Once an arg-list has been created, it may be deallo- cated using the function listFree. ListFree takes one param- ! eter: the address of the first item in the arg-list. An alternative to argument-lists is argument vectors (or arg-vectors). Arg-vectors use the ARGVEC flag instead of *************** *** 769,775 **** responsible for handling vectors of its type (although some argXxx functions such as the boolean types do not support vectors). An arg-vector is a structure which contains a ! count, an array of elements (i.e. an argc/argv pair), and an array of flags, one for each element of argv. There are two macros in defined in <parseargs.h> which are used for arg- vectors. ARGVEC_T may be used to declare a vector structure --- 768,774 ---- responsible for handling vectors of its type (although some argXxx functions such as the boolean types do not support vectors). An arg-vector is a structure which contains a ! count, an array of elements (i.e. an argc,argv pair), and an array of flags, one for each element of argv. There are two macros in defined in <parseargs.h> which are used for arg- vectors. ARGVEC_T may be used to declare a vector structure *************** *** 783,788 **** --- 782,788 ---- ( StrVec.array[ StrVec.count ] == (char *)NULL ) + is always true, and character-vectors will always have an *************** *** 797,803 **** - is always true, and character-vectors will always have an extra NUL-character at the end such that: ( CharVec.array[ CharVec.count ] == '\0' ) --- 797,802 ---- *************** *** 849,854 **** --- 848,854 ---- printf( "String[%d]=%s, flags=%x\n", i, StrVec.array[i], StrVec.flags[i] ); + for ( i = 0 ; i < NumVec.count ; i++ ) *************** *** 863,869 **** - for ( i = 0 ; i < NumVec.count ; i++ ) printf( "Number[%d]=%s, flags=%x\n", i, NumVec.array[i], NumVec.flags[i] ); --- 863,868 ---- *************** *** 884,901 **** BOOL argXxx( ARGDESC *ad, char *vp, BOOL copyf ) ! The 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 vp (which will be NULL if the ARGNOVAL flag was set for ! the corresponding entry in the arg-descriptor table). The ! copyf flag is TRUE if the vp 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 vp points to a temporary buffer area. If the type function successfully converts the value, and uses the entire value, it should return TRUE. If the type --- 883,900 ---- BOOL argXxx( ARGDESC *ad, char *vp, BOOL copyf ) ! The ad 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 ad->ad_valp. ! The string value to be converted is passed in vp (which will ! be NULL if the ARGNOVAL flag was set for the corresponding ! entry in the arg-descriptor table). The copyf flag is TRUE ! if the vp string value must be copied when saved. Most