brad@hcx1.ssd.csd.harris.com (Brad Appleton) (04/26/91)
Submitted-by: Brad Appleton <brad@hcx1.ssd.csd.harris.com>
Posting-number: Volume 18, Issue 101
Archive-name: parseargs/patch04a
Patch-To: parseargs: Volume 17, Issue 45-57
This is patch04 for parseargs. It is a four part patch that you will need
to unshar in order. It fixes some major bugs, a few minor ones, and
corrects some more errors in the documentation. Two new files are given here
(patchlevel.h & doc/effects.inc). Two old files are resubmitted (Makefile &
doc/Makefile) amd two patchfiles are included (PATCH and DOCPATCH).
______________________ "And miles to go before I sleep." ______________________
Brad Appleton Harris Corp., Computer Systems Division
Software Engineer 2101 West Cypress Creek Road, M/S 161
brad@ssd.csd.harris.com Fort Lauderdale, FL 33309-1892 USA
...!uunet!hcx1!brad Phone: (305) 973-5360
~~~~~~~~~~~~~~~~~~~~ Disclaimer: I said it, not my company! ~~~~~~~~~~~~~~~~~~~
#!/bin/sh
# This is a shell archive (produced by shar 3.49)
# To extract the files from this archive, save it to a file, remove
# everything above the "!/bin/sh" line above, and type "sh file_name".
#
# made 04/24/1991 21:50 UTC by kent@sparky.IMD.Sterling.COM
#
# existing files WILL be overwritten
#
# This is part 1 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
#
# This shar contains:
# length mode name
# ------ ---------- ------------------------------------------
# 66103 -rw-rw-r-- DOCPATCH
# 4610 -rw-rw-r-- Makefile
# 79034 -rw-rw-r-- PATCH
# 2667 -rw-rw-r-- doc/Makefile
# 1060 -rw-rw-r-- doc/effects.inc
# 2409 -rw-rw-r-- patchlevel.h
#
if test -r _shar_seq_.tmp; then
echo 'Must unpack archives in sequence!'
echo Please unpack part `cat _shar_seq_.tmp` next
exit 1
fi
# ============= DOCPATCH ==============
echo 'x - extracting DOCPATCH (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'DOCPATCH' &&
*** /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 ****
X called when an argument of that particular type is matched
X by one of the argument parsing function in parseargs(3).
X When such an argument is matched, its argument translation
! routines is invoked and is passed (1) the address of the
X argument descriptor for the matched argument, (2) the possi-
X ble argument string for that matched argument, and (3) a
! boolean filed that is TRUE only if the second parameter
X points to temporary storage (indicating that some copying
X may need to be done instead of just pointing to the same
X object).
--- 42,51 ----
X called when an argument of that particular type is matched
X by one of the argument parsing function in parseargs(3).
X When such an argument is matched, its argument translation
! routine is invoked and is passed (1) the address of the
X argument descriptor for the matched argument, (2) the possi-
X ble argument string for that matched argument, and (3) a
! boolean field that is TRUE only if the second parameter
X points to temporary storage (indicating that some copying
X may need to be done instead of just pointing to the same
X object).
***************
*** 229,235 ****
X followed by the type of the items in the vector.
X
X SEE ALSO
! parseargs(3), parseargs(3), parsecntl(1),
X
X
X
--- 229,235 ----
X followed by the type of the items in the vector.
X
X SEE ALSO
! parseargs(3), parseargs(1), parsecntl(3)
X
X
X
*** /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 ****
X parseargs - parse command line arguments in shell scripts
X
X 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 ...]
X
X OPTIONS
X -U just print program usage, do not parse the
X command line
X
--- 9,22 ----
X parseargs - parse command line arguments in shell scripts
X
X SYNOPSIS
! parseargs [-#UMCAlouip1] [-S separator] [-T string]
! [-F string] [-a arg-spec] [-e name] [-f file]
! [-s shell] -- name [arguments ...]
X
X OPTIONS
+ -# just print the version and patchlevel, do not
+ parse the command line
+
X -U just print program usage, do not parse the
X command line
X
***************
*** 20,25 ****
--- 23,31 ----
X -M just print (n|t)roff -man manual page
X template, do not parse the command line
X
+ -S separator field-separator-string used to delimit array
+ elements (default=
+
X -T string string to use for true boolean arguments
X (default=``TRUE'')
X
***************
*** 26,31 ****
--- 32,40 ----
X -F string string to use for false boolean arguments
X (default=``'')
X
+ -C Ignore the difference between upper and lower
+ case when parsing single character options.
+
X -A modify array behavior for the specified shell.
X
X -a arg-spec argument specification string
***************
*** 48,76 ****
X
X -p prompt the user for missing required arguments
X
- -i ignore bad command-line syntax and continue
- processing (instead of aborting)
X
- ARGUMENTS
- -- Indicates that any remaining options are
- intended for the calling program.
X
- name name of calling program
X
X
X
X
- Page 1
X
X
X
X
X
X
! PARSEARGS(1) PARSEARGS(1)
X
X
X
X arguments arguments to calling program
X
X DESCRIPTION
--- 57,89 ----
X
X -p prompt the user for missing required arguments
X
X
X
X
+ Page 1
X
X
X
X
X
X
+ PARSEARGS(1) PARSEARGS(1)
X
X
X
! -i ignore bad command-line syntax and continue
! processing (instead of aborting)
X
+ -1 Force any and all non-positional parameters to
+ be specified before any positional parameters
+ on the command-line.
X
+ ARGUMENTS
+ -- Indicates that any remaining options are
+ intended for the calling program.
X
+ name name of calling program
+
X arguments arguments to calling program
X
X DESCRIPTION
***************
*** 98,131 ****
X on standard output that is suitable for input to nroff or
X troff using the -man macro package.
X
X The argument specification string contains one entry for
! each possible flag. Entries in the arguments specification
X string are separated by commas. Each entry has five comma-
X separated fields: a name, some flags, a type, a variable-
X name, and a prompt. Each of these fields are described
X below:
X
- 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.
X
- 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
X
X
-
X Page 2
X
X
--- 111,131 ----
X on standard output that is suitable for input to nroff or
X troff using the -man macro package.
X
+ Given no other arguments parseargs -# prints on standard
+ output, the current version and patchlevel of the running
+ version of parseargs.
+
+
X The argument specification string contains one entry for
! each possible flag. Entries in the argument specification
X string are separated by commas. Each entry has five comma-
X separated fields: a name, some flags, a type, a variable-
X name, and a prompt. Each of these fields are described
X below:
X
X
X
X
X Page 2
X
X
***************
*** 137,154 ****
X
X
X
! implemented by the programmer; parseargs already
! knows which pre-defined argument types take an
! argument. ARGVALOPT can be ``ored'' in to
X indicate that an argument to the option may be
X optionally supplied on the command-line, but is
! not required. ARGVALREQ can be ``ored'' in to
X indicate that an argument to the option is
X required (this is the default behavior for options
! that take arguments). ARGLIST can be ``ored'' in
X (using the `|' character) to indicate that an
X argument is actually a list of one or more
! arguments from the command line. ARGHIDDEN can be
X ``ored'' in to indicate a flag that should not be
X printed in usage messages - for example, flags
X intended for internal debugging purposes.
--- 137,165 ----
X
X
X
! 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
X indicate that an argument to the option may be
X optionally supplied on the command-line, but is
! not required. ARGVALREQ may be ``ored'' in to
X indicate that an argument to the option is
X required (this is the default behavior for options
! that take arguments). ARGLIST may be ``ored'' in
X (using the `|' character) to indicate that an
X argument is actually a list of one or more
! arguments from the command line. ARGHIDDEN may be
X ``ored'' in to indicate a flag that should not be
X printed in usage messages - for example, flags
X intended for internal debugging purposes.
***************
*** 177,194 ****
X The argument specification string must be terminated by the
X single string: ``ENDOFARGS''.
X
- 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.
X
- 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
X
X
X
--- 188,194 ----
***************
*** 203,208 ****
--- 203,220 ----
X
X
X
+ 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
X ``string'' flag. Long argument specification strings
X however, may limit the number of arguments to the script if
X there is a limit to the number of arguments and/or
***************
*** 244,263 ****
X string option. The same may also be done for a boolean flag
X that is false using the -F string option.
X
- 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.
X
X
-
-
-
X Page 4
X
X
--- 256,263 ----
***************
*** 269,274 ****
--- 269,284 ----
X
X
X
+ 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.
+
X The double-dash (``--'') which precedes the name and
X arguments of the calling program is needed in order for
X parseargs to be able to distinguish options to itself from
***************
*** 280,285 ****
--- 290,310 ----
X options) are to be permitted by specifying the -o (-l)
X option on the command-line.
X
+ 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).
+
X OPTIONS WITH OPTIONAL ARGUMENTS
X Options that may take an optional argument need special
X consideration. The shell programmer needs to know whether
***************
*** 297,302 ****
--- 322,340 ----
X the shell variable associated with the option in the
X argument description string.
X
+
+
+ Page 5
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X ARGUMENT LISTS
X Parseargs treats ARGLIST arguments in a special way. The
X method used for setting up an argument list depends largely
***************
*** 321,340 ****
X positional parameters of the calling program will be re-
X assigned to the contents of the argument list.
X
-
-
-
- Page 5
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X For the Plan 9 shell (rc), if the variable name
X corresponding to the ARGLIST argument is ``*'', then the
X positional parameters of the calling program will be re-
--- 359,364 ----
***************
*** 344,349 ****
--- 368,374 ----
X ARGLIST argument is ``ARGV'', then the positional parameters
X of the calling program will be re-assigned to the contents
X of the argument list.
+
X Bourne Shell Argument Lists
X
X For the Bourne shell, if the associated variable name is NOT
***************
*** 356,362 ****
X contains an IFS character (such as a space or a tab), then
X that particular word will be treated by the Bourne shell as
X two distinct words.
-
X Also for the Bourne shell, If the associated variable name
X is NOT ``--'' and the -A option WAS specified, then that
X variable is treated as the root name of an array that is set
--- 381,386 ----
***************
*** 363,368 ****
--- 387,406 ----
X using the following syntax:
X name1='arg1'
X name2='arg2'
+
+
+
+ Page 6
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X ...
X and the variable ``name_count'' will be set to contain the
X number of items in the array. The user may then step
***************
*** 387,406 ****
X overwritten by the set command).
X It should be noted that there is a bug in versions of the
X Korn shell earlier than 11/16/88a, in which the following:
-
-
-
- Page 6
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X set -A name 'arg1' 'arg2' ...
X causes the positional parameters to be overwritten as an
X unintentional side-effect. If your version of the Korn shell
--- 425,430 ----
***************
*** 409,414 ****
--- 433,439 ----
X must save them yourself before you call parseargs. This may
X be accomplished by the following:
X set -A save_parms "$@"
+
X C and TC Shell Argument Lists
X
X For the C and TC shells, ARGLIST variables are treated as
***************
*** 418,436 ****
X in $name[2], etc ..., and all items may be given by $name.
X Notice that Korn shell arrays start at index zero whereas C
X and TC shell word-lists start at index one.
-
X Bourne-Again Shell Argument Lists
X
X At present, the Free Software Foundation's Bourne-Again
X shell is treated exactly the same as the Bourne Shell. This
X will change when bash supports arrays.
X Plan 9 Shell Argument Lists
X
X For the Plan 9 shell, if the associated variable name is not
! ``*'' then it is considered to be word-list and set using
X the following syntax:
X name=( 'arg1' 'arg2' ... )
-
X Awk Argument Lists
X For awk, if the -A option is not given, then the output for
X thes variable-list will be a line with the variable name,
--- 443,474 ----
X in $name[2], etc ..., and all items may be given by $name.
X Notice that Korn shell arrays start at index zero whereas C
X and TC shell word-lists start at index one.
X Bourne-Again Shell Argument Lists
X
X At present, the Free Software Foundation's Bourne-Again
X shell is treated exactly the same as the Bourne Shell. This
X will change when bash supports arrays.
+
X Plan 9 Shell Argument Lists
X
X 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)
!
!
!
X the following syntax:
X name=( 'arg1' 'arg2' ... )
X Awk Argument Lists
X For awk, if the -A option is not given, then the output for
X thes variable-list will be a line with the variable name,
***************
*** 442,448 ****
X If the -A option is given, then the associated variable is
X considered the root name of an array. The ouput for the
X array will consist of two lines for each item in the list
! (as in the following expample):
X name1
X arg1
X
--- 480,486 ----
X If the -A option is given, then the associated variable is
X considered the root name of an array. The ouput for the
X array will consist of two lines for each item in the list
! (as in the following example):
X name1
X arg1
X
***************
*** 452,477 ****
X and the variable ``name_count'' will have an output line
X showing the number of items in the array.
X
-
-
-
-
- Page 7
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X Perl Argument Lists
X
X For perl, each argument list is considered an array and is
X set using the following syntax:
! @name=( arg1 , arg2 , ... );
X A Final Note on Argument Lists
X
X The word-lists used by the C shell, the arrays used by the
--- 490,501 ----
X and the variable ``name_count'' will have an output line
X showing the number of items in the array.
X
X Perl Argument Lists
X
X For perl, each argument list is considered an array and is
X set using the following syntax:
! @name=( 'arg1' , 'arg2' , ... );
!
X A Final Note on Argument Lists
X
X The word-lists used by the C shell, the arrays used by the
***************
*** 495,500 ****
--- 519,538 ----
X ARGLISTs and ARGVECs set in ``CMD_ARGS'' will be appended
X from the command-line if they are selected).
X
+
+
+
+ Page 8
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X It is important to note that the contents of the
X ``CMD_ARGS'' environment variable are NOT expanded by the
X shell and hence any special characters (such as quotes or
***************
*** 519,538 ****
X of parsecntl(3). The user may set his (or her) own desired
X parsing behavior through the use of the ``PARSECNTL''
X environment variable. By indicating any number of flags
-
-
-
- Page 8
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X (possibly negated) the user will directly modify the
X behavior of the parseargs library. Flags may be combined by
X placing a `+' or `|' character in between flags. A switch is
--- 557,562 ----
***************
*** 551,570 ****
X Ignore
X Ignore any unrecognized or improperly specified
X 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.
X
X OptsOnly
X Under UNIX, setting this flag will disable the parsing
X of long-option syntax. This will cause all arguments
! starting with '+' to always be treated as a positional
X parameter (instead of a long-option).
X
X KwdsOnly
X Under UNIX, setting this flag disables the parsing of
X single-character options. This will cause all
! arguments starting with '-' to always be treated as a
X positional parameter (instead of an option).
X
X LoptsOnly
--- 575,608 ----
X Ignore
X Ignore any unrecognized or improperly specified
X 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.
X
X OptsOnly
X Under UNIX, setting this flag will disable the parsing
X of long-option syntax. This will cause all arguments
! starting with `+' to always be treated as a positional
X parameter (instead of a long-option).
X
+
+
+
+ Page 9
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X KwdsOnly
X Under UNIX, setting this flag disables the parsing of
X single-character options. This will cause all
! arguments starting with `-' to always be treated as a
X positional parameter (instead of an option).
X
X LoptsOnly
***************
*** 585,609 ****
X one positional argument.
X
X CaseIgnore
X
-
-
- 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).
-
X If the environment variable ``PARSECNTL'' is empty or
X undefined, then the parsing behavior set by the programmer
X is used. If the programmer has not explicitly used
--- 623,633 ----
X one positional argument.
X
X 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).
X
X If the environment variable ``PARSECNTL'' is empty or
X undefined, then the parsing behavior set by the programmer
X is used. If the programmer has not explicitly used
***************
*** 627,638 ****
X only a command-line synopsis is printed (this is also
X refferred to as ``terse'' mode). The other two ``modes''
X 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.
X
X
X Quiet
X No usage message of any kind is displayed.
X
--- 651,676 ----
X only a command-line synopsis is printed (this is also
X refferred to as ``terse'' mode). The other two ``modes''
X control the displaying of option syntax and long-option
X
X
+
+ 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.
+
X Quiet
X No usage message of any kind is displayed.
X
***************
*** 651,670 ****
X Description
X The command description is printed.
X
-
-
-
- Page 10
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X Terse
X Terse mode, just print command-line synopsis.
X
--- 689,694 ----
***************
*** 680,685 ****
--- 704,710 ----
X KeyWords
X Same as LongOpts.
X
+
X If the environment variable ``USAGECNTL'' is empty or
X undefined, then the default usage level (which is presently
X ``Verbose + Options'') will be used.
***************
*** 689,697 ****
X specification for a Bourne shell script:
X
X #!/bin/sh
-
X RepCount=2;
X Verbose="";
X ARGSPEC="
X 'c', ARGOPT, argInt, RepCount, 'count {# times to repeat}',
X 'v', ARGOPT, argBool, Verbose, 'verbose {turn on verbose mode}',
--- 714,736 ----
X specification for a Bourne shell script:
X
X #!/bin/sh
X RepCount=2;
X Verbose="";
+
+
+
+
+ Page 11
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X ARGSPEC="
X 'c', ARGOPT, argInt, RepCount, 'count {# times to repeat}',
X 'v', ARGOPT, argBool, Verbose, 'verbose {turn on verbose mode}',
***************
*** 701,708 ****
X ' ', ARGOPT|ARGLIST, listStr, Files, 'files {files to process}',
X ENDOFARGS
X "
X
- eval `echo "$ARGUMENTS" | parseargs -s sh -- $0 "$@"`
X
X This describes a Bourne shell script accepting up to three
X flag arguments and one or two positional arguments, plus a
--- 740,747 ----
X ' ', ARGOPT|ARGLIST, listStr, Files, 'files {files to process}',
X ENDOFARGS
X "
+ eval `echo "$ARGSPEC" | parseargs -s sh -- $0 "$@"`
X
X
X This describes a Bourne shell script accepting up to three
X flag arguments and one or two positional arguments, plus a
***************
*** 717,736 ****
X FALSE (an empty string).
X
X -X A Boolean ``X Rated'' flag. This is not
-
-
-
- Page 11
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X printed in the usage message.
X
X The two positional arguments are both strings, as is the
--- 756,761 ----
***************
*** 758,763 ****
--- 783,802 ----
X associated command line variables, and then prints its
X command usage.
X
+
+
+
+ Page 12
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X #!/bin/sh
X # test.sh - Bourne shell script to test out the parseargs command!
X #
***************
*** 783,802 ****
X
X ## parse command-line and save assignments in a temporary file ##
X parseargs -s sh -e ARGUMENTS -u -- "$NAME" "$@" >/tmp/tmp$$
-
-
-
- Page 12
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X if [ $? -ne 0 ]
X then rm -f /tmp/tmp$$; exit 2 ## non-zero status (usage given)
X fi
--- 822,827 ----
***************
*** 825,838 ****
X Parseargs may exit with one of the following status codes:
X
X
X -1 Some type of system error occurred during execution,
X causing the program to exit prematurely.
X
X 0 Normal exit status (no problems were encountered).
X
! 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
X displayed.
X
X 2 A command line syntax error was encountered by
--- 850,876 ----
X Parseargs may exit with one of the following status codes:
X
X
+
+
+ Page 13
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X -1 Some type of system error occurred during execution,
X causing the program to exit prematurely.
X
X 0 Normal exit status (no problems were encountered).
X
! 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
X displayed.
X
X 2 A command line syntax error was encountered by
***************
*** 848,868 ****
X 4 A syntax error was encountered in the argument
X specification string that was specified to parseargs.
X
-
-
-
-
- Page 13
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X FILES
X /usr/local/parseargs.pl
X This file defines a perl function named parseargs to
--- 886,891 ----
***************
*** 892,897 ****
--- 915,934 ----
X -f-arg
X
X will properly assign the string ``-arg'' to the option
+
+
+
+ Page 14
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X whereas the following:
X -f -arg
X
***************
*** 916,934 ****
X Hence multiple ``leading dash'' arguments may specified as
X follows:
X
-
-
- Page 14
-
-
-
-
-
-
- PARSEARGS(1) PARSEARGS(1)
-
-
-
X -f-dash_arg1 -f-dash_arg2 ...
X
X BUGS
--- 953,958 ----
***************
*** 957,962 ****
--- 981,1000 ----
X
X Parseargs cannot properly preserve any newlines in shell
X variables if the eval command is used to read its output
+
+
+
+ Page 15
+
+
+
+
+
+
+ PARSEARGS(1) PARSEARGS(1)
+
+
+
X (this is a shortcoming of the eval command, not of
X parseargs). If the user is concerned about this particular
X case, then the user should redirect the output from
***************
*** 966,975 ****
X or characters following a newline may be lost, in any
X variables that are set by parseargs.
X
- 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.
-
X AUTHOR
X Brad Appleton (brad@ssd.csd.harris.com)
X Harris Computer Systems, Fort Lauderdale, FL USA
--- 1004,1009 ----
***************
*** 984,990 ****
X
X
X
! Page 15
X
X
X
--- 1018,1056 ----
X
X
X
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
! Page 16
X
X
X
*** /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 ****
X
X
X NAME
! parseargs, usage - parse command line argument vectors
X
X SYNOPSIS
X #include <parseargs.h>
X
! 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 )
X
X DESCRIPTION
X Given a vector of string-valued arguments such as that
--- 6,23 ----
X
X
X NAME
! parseargs - parse command line argument vectors
X
X SYNOPSIS
X #include <parseargs.h>
X
! 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;
X
X DESCRIPTION
X Given a vector of string-valued arguments such as that
***************
*** 27,50 ****
X argument values that are syntactically incorrect.
X
X 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).
X
X Given an ArgList and an argdesc array, lparseargs will parse
! arguments in an ArgList in much the same manner as par-
! seargs.
X
X 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
X vector of whitespace separated tokens and then attempt to
X parse the resultant vector as if it were given as argv[] on
X the command-line. NO special treatment is given to charac-
--- 28,50 ----
X argument values that are syntactically incorrect.
X
X 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).
X
X Given an ArgList and an argdesc array, lparseargs will parse
! arguments in an ArgList in the same manner as parseargs.
X
X 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
X vector of whitespace separated tokens and then attempt to
X parse the resultant vector as if it were given as argv[] on
X the command-line. NO special treatment is given to charac-
***************
*** 52,62 ****
X Sparseargs will always assume that any whitespace characters
X are intended as argument separators.
X
-
X Vparseargs takes an argdesc array, the number of arguments
X 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
X
X
X
--- 52,62 ----
X Sparseargs will always assume that any whitespace characters
X are intended as argument separators.
X
X Vparseargs takes an argdesc array, the number of arguments
X 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
X
X
X
***************
*** 71,86 ****
X
X
X
! 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).
X
-
X Given an argdesc array, usage will print the usage for the
X given command in the format specified by the user's
X USAGECNTL environment variable.
X
X THE ARGUMENT STRUCTURE
X The basic type used by the parseargs library is the argument
X descriptor (or "argdesc" for short). An ARGDESC structure is
--- 71,90 ----
X
X
X
! 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
X Given an argdesc array, usage will print the usage for the
X given command in the format specified by the user's
X USAGECNTL environment variable.
X
+ 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.
+
X THE ARGUMENT STRUCTURE
X The basic type used by the parseargs library is the argument
X descriptor (or "argdesc" for short). An ARGDESC structure is
***************
*** 120,131 ****
X this field must correspond to the name of one of the
X argument type functions described in argtype(3).
X
- ARBPTR ad_valp;
- This field is a generic pointer to the storage used to
- represent the internal value of the command-line
X
X
-
X Page 2
X
X
--- 124,131 ----
***************
*** 137,149 ****
X
X
X
! 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.
X
X const char *ad_prompt;
X This field contains the long-name of the argument and
--- 137,152 ----
X
X
X
! 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.
X
X const char *ad_prompt;
X This field contains the long-name of the argument and
***************
*** 155,161 ****
X contains any uppercase characters, then the substring
X of long-name consisting of all uppercase characters is
X used as the argument keyword and the entire long-name
! is used as the name of the argument (if a value my be
X supplied). The long-name may be matched by supplying a
X unique prefix of either the argument keyword or the
X argument name.
--- 158,164 ----
X contains any uppercase characters, then the substring
X of long-name consisting of all uppercase characters is
X used as the argument keyword and the entire long-name
! is used as the name of the argument (if a value may be
X supplied). The long-name may be matched by supplying a
X unique prefix of either the argument keyword or the
X argument name.
***************
*** 173,179 ****
X char *InFile;
X char *OutFile = CHARNULL;
X BOOL XRated = FALSE;
! struct namelist *Files = NULL;
X
X ARGDESC Args[] =
X {
--- 176,182 ----
X char *InFile;
X char *OutFile = CHARNULL;
X BOOL XRated = FALSE;
! ArgList *Files = ARGLISTNULL;
X
X ARGDESC Args[] =
X {
***************
*** 183,197 ****
X ' ', ARGREQ, argStr, __ &InFile, "INPUTfile {input file}",
X ' ', ARGOPT, argStr, __ &OutFile, "OUTPUTfile {output file}",
X 'X', ARGHIDDEN, argBool, __ &XRated, "XratedMODE {naughty stuff!}",
! ' ', ARGOPT|ARGLIST, argStr, __ &Files, "File {files to be read}",
X ENDOFARGS
X };
X
X
X
-
-
-
X Page 3
X
X
--- 186,197 ----
X ' ', ARGREQ, argStr, __ &InFile, "INPUTfile {input file}",
X ' ', ARGOPT, argStr, __ &OutFile, "OUTPUTfile {output file}",
X 'X', ARGHIDDEN, argBool, __ &XRated, "XratedMODE {naughty stuff!}",
! ' ', ARGLIST, listStr, __ &Files, "File {files to be read}",
X ENDOFARGS
X };
X
X
X
X Page 3
X
X
***************
*** 379,386 ****
X arg_sdesc(ad)
X Return the description of an argument. If a description
X was supplied, the ARGDESCRIBED flag will be set and the
! description will immediately follow the terminating NUL
! byte of the string name.
X
X ARG_isDESCRIBED(ad)
X Evaluates to TRUE only if an argument description was
--- 379,386 ----
X arg_sdesc(ad)
X Return the description of an argument. If a description
X was supplied, the ARGDESCRIBED flag will be set and the
! description will immediately follow the terminating
! NULL byte of the string name.
X
X ARG_isDESCRIBED(ad)
X Evaluates to TRUE only if an argument description was
***************
*** 448,454 ****
X usage messages.
X
X CMD MACROS
! Parseargs.h defines a set of macros to allow a more "self
X documenting" approach to declaring argument-descriptor
X arrays. The "old-style" is still accepted (but if used it is
X recommended that the STARTOFARGS macro is used in conjunc-
--- 448,454 ----
X usage messages.
X
X CMD MACROS
! <parseargs.h> defines a set of macros to allow a more "self
X documenting" approach to declaring argument-descriptor
X arrays. The "old-style" is still accepted (but if used it is
X recommended that the STARTOFARGS macro is used in conjunc-
***************
*** 606,625 ****
X Ignore
X Ignore any unrecognized or improperly specified
X 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.
X
X OptsOnly
X Under UNIX, setting this flag will disable the parsing
X of long-option syntax. This will cause all arguments
! starting with '+' to always be treated as a positional
X parameter (instead of a long-option).
X
X KwdsOnly
X Under UNIX, setting this flag disables the parsing of
X single-character options. This will cause all argu-
! ments starting with '-' to always be treated as a posi-
X tional parameter (instead of an option).
X
X LoptsOnly
--- 606,625 ----
X Ignore
X Ignore any unrecognized or improperly specified
X 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.
X
X OptsOnly
X Under UNIX, setting this flag will disable the parsing
X of long-option syntax. This will cause all arguments
! starting with `+' to always be treated as a positional
X parameter (instead of a long-option).
X
X KwdsOnly
X Under UNIX, setting this flag disables the parsing of
X single-character options. This will cause all argu-
! ments starting with `-' to always be treated as a posi-
X tional parameter (instead of an option).
X
X LoptsOnly
***************
*** 640,648 ****
X positional argument.
X
X 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
X equivalent).
X
X If the environment variable ``PARSECNTL'' is empty or unde-
--- 640,648 ----
X positional argument.
X
X 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
X equivalent).
X
X If the environment variable ``PARSECNTL'' is empty or unde-
***************
*** 683,691 ****
X ferred to as ``terse'' mode). The other two ``modes'' con-
X trol the displaying of option syntax and long-option syntax.
X 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.
X
X Quiet
X No usage message of any kind is displayed.
--- 683,692 ----
X ferred to as ``terse'' mode). The other two ``modes'' con-
X trol the displaying of option syntax and long-option syntax.
X 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.
X
X Quiet
X No usage message of any kind is displayed.
***************
*** 719,725 ****
X
X
X
-
X Page 11
X
X
--- 720,725 ----
***************
*** 759,766 ****
X vectors however need a set of flags for each item they con-
X tain. Once an arg-list has been created, it may be deallo-
X cated using the function listFree. ListFree takes one param-
! eter: first of which is the address of the first item in the
! arg-list.
X
X An alternative to argument-lists is argument vectors (or
X arg-vectors). Arg-vectors use the ARGVEC flag instead of
--- 759,765 ----
X vectors however need a set of flags for each item they con-
X tain. Once an arg-list has been created, it may be deallo-
X cated using the function listFree. ListFree takes one param-
! eter: the address of the first item in the arg-list.
X
X An alternative to argument-lists is argument vectors (or
X arg-vectors). Arg-vectors use the ARGVEC flag instead of
***************
*** 769,775 ****
X responsible for handling vectors of its type (although some
X argXxx functions such as the boolean types do not support
X vectors). An arg-vector is a structure which contains a
! count, an array of elements (i.e. an argc/argv pair), and an
X array of flags, one for each element of argv. There are two
X macros in defined in <parseargs.h> which are used for arg-
X vectors. ARGVEC_T may be used to declare a vector structure
--- 768,774 ----
X responsible for handling vectors of its type (although some
X argXxx functions such as the boolean types do not support
X vectors). An arg-vector is a structure which contains a
! count, an array of elements (i.e. an argc,argv pair), and an
X array of flags, one for each element of argv. There are two
X macros in defined in <parseargs.h> which are used for arg-
X vectors. ARGVEC_T may be used to declare a vector structure
***************
*** 783,788 ****
--- 782,788 ----
X
X ( StrVec.array[ StrVec.count ] == (char *)NULL )
X
+ is always true, and character-vectors will always have an
X
X
X
***************
*** 797,803 ****
X
X
X
- is always true, and character-vectors will always have an
X extra NUL-character at the end such that:
X
X ( CharVec.array[ CharVec.count ] == '\0' )
--- 797,802 ----
***************
*** 849,854 ****
--- 848,854 ----
X printf( "String[%d]=%s, flags=%x\n",
X i, StrVec.array[i], StrVec.flags[i] );
X
+ for ( i = 0 ; i < NumVec.count ; i++ )
X
X
X
***************
*** 863,869 ****
X
X
X
- for ( i = 0 ; i < NumVec.count ; i++ )
X printf( "Number[%d]=%s, flags=%x\n",
X i, NumVec.array[i], NumVec.flags[i] );
X
--- 863,868 ----
***************
*** 884,901 ****
X
X BOOL argXxx( ARGDESC *ad, char *vp, BOOL copyf )
X
! 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.
X
X If the type function successfully converts the value, and
X uses the entire value, it should return TRUE. If the type
--- 883,900 ----
X
X BOOL argXxx( ARGDESC *ad, char *vp, BOOL copyf )
X
! 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
SHAR_EOF
true || echo 'restore of DOCPATCH failed'
echo 'End of part 1'
echo 'File DOCPATCH is continued in part 2'
echo 2 > _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.