Usenet 1994 October

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

/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / misc / volume19 / parseargs / patch05a / PATCH05 < prev

Wrap

Text File | 1991-05-17 | 52.7 KB | 1,248 lines

diff -cNr ../patchlevel4/Intro ./Intro *** ../patchlevel4/Intro Thu May 2 10:56:07 1991 --- ./Intro Thu May 2 14:34:14 1991 *************** *** 51,58 **** Parseargs consists of a set of C-functions to parse arguments from the command-line, from files, from strings, from linked-lists, and from string-vectors. Also included is a command-line interface which will parse ! arguments for shell scripts (sh, csh/tcsh, ksh, bash, and rc), awk-scripts, ! and perl-scripts. The basic structure used by parseargs is the argument-descriptor (sometimes called "argdesc" for brevity). An array/string of argdescs is declared by --- 51,58 ---- Parseargs consists of a set of C-functions to parse arguments from the command-line, from files, from strings, from linked-lists, and from string-vectors. Also included is a command-line interface which will parse ! arguments for shell scripts (sh, csh/tcsh/itcsh, ksh, bash, zsh, and rc), ! awk-scripts, and perl-scripts. The basic structure used by parseargs is the argument-descriptor (sometimes called "argdesc" for brevity). An array/string of argdescs is declared by *************** *** 78,86 **** or from a shell script as in the following example: echo "$ARGDESC_STR" | parseargs -s sh -- "$0" "$@" >tmp$$ ! if [ $? = 0 ] ; then ! . tmp$$ ! fi /bin/rm -f tmp$$ And before you know it, your command-line had been parsed, all variables --- 78,84 ---- or from a shell script as in the following example: echo "$ARGDESC_STR" | parseargs -s sh -- "$0" "$@" >tmp$$ ! test $? = 0 && . tmp$$ /bin/rm -f tmp$$ And before you know it, your command-line had been parsed, all variables diff -cNr ../patchlevel4/MANIFEST ./MANIFEST *** ../patchlevel4/MANIFEST Thu May 2 11:06:06 1991 --- ./MANIFEST Thu May 2 13:00:33 1991 *************** *** 6,12 **** Makefile.cpp 3 makefile template read by the C preprocessor README 1 release information amiga_args.c 4 parse AmigaDOS command-lines ! arglist.c 2 implement the listXxxx functions for arglists argtype.c 5 implement the argXxxx argument type functions doc 1 directory containing documentation doc/Makefile 2 makefile for the documentation --- 6,12 ---- Makefile.cpp 3 makefile template read by the C preprocessor README 1 release information amiga_args.c 4 parse AmigaDOS command-lines ! arglist.c 3 implement the listXxxx functions for arglists argtype.c 5 implement the argXxxx argument type functions doc 1 directory containing documentation doc/Makefile 2 makefile for the documentation *************** *** 15,21 **** doc/argflags.inc 2 describe argument flags doc/argtype.man3 3 {n,t}roff source for argtype(3) doc/argvalopt.inc 1 describe options with optional arguments ! doc/bugs.inc 2 BUGS section for parseargs(1) doc/caveats.inc 1 CAVEATS section for parseargs(1) and (3) doc/cmd_macros.inc 1 describe CMD_XXX macros doc/defargs.inc 1 describe the default argdesc-array --- 15,21 ---- doc/argflags.inc 2 describe argument flags doc/argtype.man3 3 {n,t}roff source for argtype(3) doc/argvalopt.inc 1 describe options with optional arguments ! doc/bugs.inc 1 BUGS section for parseargs(1) doc/caveats.inc 1 CAVEATS section for parseargs(1) and (3) doc/cmd_macros.inc 1 describe CMD_XXX macros doc/defargs.inc 1 describe the default argdesc-array *************** *** 44,56 **** doc/vparseargs3.inc 1 describe vparseargs(3) ibm_args.c 5 parse MS-DOS and OS/2 command-lines parseargs.awk 3 parseargs for awk ! parseargs.c 7 C source for parseargs(1) ! parseargs.h 6 include file for parseargs library parseargs.pl 2 parseargs for perl ! patchlevel.h 1 list of patches (most recent first) pgopen.c 4 pipe output to a pager pgopen.h 1 include file for pgopen.c ! stest.c 3 test progarm for parseargs(3) strfuncs.c 6 string library strfuncs.h 1 include file for strfuncs.c syserr.c 2 diagnostic message printing routines --- 44,56 ---- doc/vparseargs3.inc 1 describe vparseargs(3) ibm_args.c 5 parse MS-DOS and OS/2 command-lines parseargs.awk 3 parseargs for awk ! parseargs.c 8 C source for parseargs(1) ! parseargs.h 7 include file for parseargs library parseargs.pl 2 parseargs for perl ! patchlevel.h 2 list of patches (most recent first) pgopen.c 4 pipe output to a pager pgopen.h 1 include file for pgopen.c ! stest.c 4 test program for parseargs(3) strfuncs.c 6 string library strfuncs.h 1 include file for strfuncs.c syserr.c 2 diagnostic message printing routines *************** *** 60,69 **** test.pl 1 perl test program for parseargs(1) test.rc 1 Plan 9 shell test program for parseargs(1) test.sh 1 Bourne shell test program for parseargs(1) ! unix_args.c 4 parse Unix command-lines unix_man.c 3 print Unix manual-page templates useful.h 3 common include file for the library ! vms_args.c 5 parse VAX/VMS DCL command-lines vprintf.c 3 portable vfprintf, vprintf, and vsprintf winsize.c 3 determine # rows and # columns of window ! xparse.c 8 implement the parseargs library --- 60,70 ---- test.pl 1 perl test program for parseargs(1) test.rc 1 Plan 9 shell test program for parseargs(1) test.sh 1 Bourne shell test program for parseargs(1) ! test.zsh 2 Z shell test program for parseargs(1) ! unix_args.c 5 parse Unix command-lines unix_man.c 3 print Unix manual-page templates useful.h 3 common include file for the library ! vms_args.c 6 parse VAX/VMS DCL command-lines vprintf.c 3 portable vfprintf, vprintf, and vsprintf winsize.c 3 determine # rows and # columns of window ! xparse.c 9 implement the parseargs library diff -cNr ../patchlevel4/README ./README *** ../patchlevel4/README Thu May 2 10:56:10 1991 --- ./README Thu May 2 14:34:23 1991 *************** *** 58,106 **** CONTENTS ======== ! README : this file. ! [ Intro : introduction to parseargs -- BDA ] ! [ doc/Makefile : makefile for parseargs documentation -- BDA ] ! [ doc/* : documentation for parseargs -- BDA ] ! Makefile : a makefile for the library. ! [ Makefile.cpp : a makefile template -- BDA ] ! useful.h : a general header file, used by most everything. ! parseargs.h : headers for the argument parser. ! [ parseargs.c is now broken down into the following files : PDS ] ! unix_args.c : a command line argument parser. Popular ! response to my C Advisor column about this routine ! in UNIX Review Vol. 7 No. 11 prompted me to make ! this distribution available. ! amiga_args.c : Amiga version of unix_args.c -- PDS ! ibm_args.c : IBM-PC version of unix_args.c -- BDA ! vms_args.c : VAX/VMS version of unix_args.c -- BDA ! arglist.c : routines for ARGLIST options. -- PDS ! argtype.c : routines for other options. The argument value parsers ! for floating point values may be excluded by #defining the ! macro NOFLOAT (only if you do NOT need floating-point values). ! I had to break this out because RISC/os 4.01 from Mips doesn't ! seem to support strtod in the BSD environment. You may find you ! need to include -lm for this to work. ! strfuncs.[ch] : string-manipulation functions & ! dictionary-style searching routines. ! [ end of parseargs.c : PDS ] ! [ parseargs.c has been resurrected as a command line interface ! to the parseargs library routines -- BDA ] ! syserr.c : error message printing routines. ! stest.c : a small test program for the argument parser. ! [ xparse.c : source for [flsv]parseargs() and parsecntl() -- BDA ] ! [ unix_man.c : routine to print unix man1 templates -- BDA ] ! [ winsize.c : routine to "portably" get the screen size -- BDA ] ! [ pgopen.[ch] : Unix source to pipe output to a pager -- BDA ] ! [ vprintf.c : portable implementations of vprintf() & vfprintf() ] ! [ parseargs.awk : awk interface to parseargs(1) -- BDA ] ! [ parseargs.pl : perl interface to parseargs(1) -- BDA ] ! [ test.sh : Bourne shell-script to test parseargs(1) -- BDA ] ! [ test.csh : C shell-script to test parseargs(1) -- BDA ] ! [ test.ksh : Korn shell-script to test parseargs(1) -- BDA ] ! [ test.awk : awk script to test parseargs(1) -- BDA ] ! [ test.pl : perl script to test parseargs(1) -- BDA ] The parseargs routines really ought to have a way of matching a list (e.g., return the rest of argv). This isn't especially hard to do, but I haven't gotten around to it yet. [ Added, with ARGLIST flag -- PDS ] --- 58,68 ---- CONTENTS ======== ! See the file "MANIFEST" in the distribution for a complete list and ! description of all the files included in this release. + TO DO + ===== The parseargs routines really ought to have a way of matching a list (e.g., return the rest of argv). This isn't especially hard to do, but I haven't gotten around to it yet. [ Added, with ARGLIST flag -- PDS ] *************** *** 261,268 **** Update to parseargs (and major re-write) by Brad Appleton (brad@travis.ssd.csd.harris.com) ! Last Update: 03/01/91 DISCLAIMER ========== Neither Brad Appleton, nor Harris Corporation (including any of its --- 223,237 ---- Update to parseargs (and major re-write) by Brad Appleton (brad@travis.ssd.csd.harris.com) ! Last Update: 04/12/91 ! + THIS RELEASE + ============ + Read the file patchlevel.h in the distribution to find out what version + and patchlevel of parseargs you have received. + + DISCLAIMER ========== Neither Brad Appleton, nor Harris Corporation (including any of its *************** *** 427,449 **** If someone wants to try to add more shell-types to parseargs.c, here are the main things that need to be done: ! 1. add #defines for both the name (a string) and type (an integer) of ! shell (e.g #define BOURNE_SHELL "sh" and #define SH 4) ! 2. add a shell_info entry into the array Shell[]. The index of the ! entry in the array should be the number used in the #define for the ! type of shell. ! ! 3. make sure that get_shell_type() will return the proper value for ! the new shell. ! ! 4. print_args doesnt really do any shell specific stuff outside of ! indexing into the table. The print_arglist() and ! unset_positional_parameters() functions do some shell specific stuff ! and will need a case added to the switch statement(s) for the newly ! added shell. ! 5. If the information in the shell-info structure is not sufficient for the new shell then you should either: a) redefine the structure for all shells including your shell. b) add some special code into print_args() for your shell! --- 396,412 ---- If someone wants to try to add more shell-types to parseargs.c, here are the main things that need to be done: ! 1. add an entry for the shell type into the type definition for the ! "shell_t" enumerated type. ! 2. add a shell_info entry for the shell into the array Shell[]. ! 3. print_args doesnt really do any shell specific stuff outside of ! indexing into the table. The print_arglist() function does some ! shell specific stuff and MAY need a case added to the switch statement(s) ! for the newly added shell. ! ! 4. If the information in the shell-info structure is not sufficient for the new shell then you should either: a) redefine the structure for all shells including your shell. b) add some special code into print_args() for your shell! *************** *** 786,792 **** NAME OS ------------------ ------------------------ unix Unix (BSD or AT&T) ! BSD, ucb_universe BSD Unix (only one need be present) MANX, AZTEC AmigaDOS MSDOS MS-DOS for IBM PCs OS2 OS/2 for IBM PCs --- 749,755 ---- NAME OS ------------------ ------------------------ unix Unix (BSD or AT&T) ! BSD, SYSV BSD Unix or AT&T Unix (only one should be present) MANX, AZTEC AmigaDOS MSDOS MS-DOS for IBM PCs OS2 OS/2 for IBM PCs *************** *** 817,823 **** By default, if SWITCHAR is undefined then both the long and short option prefix character are '/'. One is able to distinguish an option from a long-option in this case because the third character of an ! option-arg will always be '=' or ' '. Hence, using the test program with the defaults, both "ibm_test foo /D=directory" and "ibm_test /DIR=directory" are equivalent. --- 780,786 ---- By default, if SWITCHAR is undefined then both the long and short option prefix character are '/'. One is able to distinguish an option from a long-option in this case because the third character of an ! option-arg will always be '=' or '\0'. Hence, using the test program with the defaults, both "ibm_test foo /D=directory" and "ibm_test /DIR=directory" are equivalent. *************** *** 852,859 **** thanks to posters from comp.os.vms for giving me a clue on how to do this). As a result of this, under VAX/VMS, there are two new argtype functions "argInput" and "argOutput": each requires that ad->ad_valp ! be a file pointer (not a pointer to a file pointer as in "__ &stdin" ! but an actual file pointer as in "__ stdin"). ArgInput and argOutput close the stream associated with the given file-pointer and reconnect the stream to the named file for input or output (so the effect is to redirect input (output) from (to) the stream to the named file. If --- 815,822 ---- thanks to posters from comp.os.vms for giving me a clue on how to do this). As a result of this, under VAX/VMS, there are two new argtype functions "argInput" and "argOutput": each requires that ad->ad_valp ! be a pointer to a file pointer (not a FILE * variable as in "__ stdin" ! but an actual FILE ** variable as in "__ &stdin"). ArgInput & argOutput close the stream associated with the given file-pointer and reconnect the stream to the named file for input or output (so the effect is to redirect input (output) from (to) the stream to the named file. If *************** *** 888,904 **** vms_args.c as well. LITERATE PROGRAMMING ==================== If you look at the source code you will notice that it contains lots of funny looking comments with sections that have titles enclosed between '^' and ':' characters. This is my own feeble attempt at ! literate programming. I have a Unix-shell script which will extract ! certain portions of these "structured" comments so that I may dump ! them directly into the documentation (and thus attempt to keep the ! documentation up-to-date at the same rate as the source). If anyone ! is interested in my script(s) please let me know and I will gladly e- ! mail them to the interested parties. ACKNOWLEDGEMENTS --- 851,879 ---- vms_args.c as well. + TO DO + ===== + - get parseargs(1) to work for DCL under VMS using symbols + - add ash to the list of shells supported by parseargs(1) + - add clam to the list of shells supported by parseargs(1) + - get parseargs(1) to support arrays for bash + - verify that parseargs(1) works for rc, the Plan 9 shell + - verify that parseargs(1) works for zsh + - verify that parseargs(3) works on VMS systems. + - verify that parseargs(3) works on MS-DOS and OS/2 systems. + + LITERATE PROGRAMMING ==================== If you look at the source code you will notice that it contains lots of funny looking comments with sections that have titles enclosed between '^' and ':' characters. This is my own feeble attempt at ! literate programming. I have a Korn shell script (xdoc) which will ! extract certain portions of these "structured" comments so that I may ! dump them directly into the documentation (and thus attempt to keep ! the documentation up-to-date at the same rate as the source). If anyone ! is interested in my script(s) please let me know and I will gladly ! e-mail them to the interested parties. ACKNOWLEDGEMENTS *************** *** 905,911 **** ================ I was in constant contact with Peter Da Silva during the entire period that I implemented all of the above modifications and would like to ! thank him for his time and his sage advice. Thanx also to Jim Barbour for helping me with some VMS specific things (like getting the original, unparsed command-line from DCL and --- 880,887 ---- ================ I was in constant contact with Peter Da Silva during the entire period that I implemented all of the above modifications and would like to ! thank him for his time and his sage advice. Many of the ideas which I ! implemented are a direct result of our discussions. Thanx also to Jim Barbour for helping me with some VMS specific things (like getting the original, unparsed command-line from DCL and *************** *** 912,920 **** retreiving the value of a symbol), and to Tom Christiansen and Raymond Chen for their help in getting parseargs(1) to work for perl scripts. Lastly, thanks to all those who use and will continue to improve parseargs, all I ask is that you keep me updated of your efforts (so I can keep my own version of parseargs up-to-date). I am always eager to discuss possible changes or enhancements with any interested parties. - --- 888,899 ---- retreiving the value of a symbol), and to Tom Christiansen and Raymond Chen for their help in getting parseargs(1) to work for perl scripts. + Thanx also to Gillmer J. Derge, Marco Nijdam, & Chris Johnston for sending + me their bug reports and fixes so that I could incorporate them into the + latest patch of parseargs. + Lastly, thanks to all those who use and will continue to improve parseargs, all I ask is that you keep me updated of your efforts (so I can keep my own version of parseargs up-to-date). I am always eager to discuss possible changes or enhancements with any interested parties. diff -cNr ../patchlevel4/amiga_args.c ./amiga_args.c *** ../patchlevel4/amiga_args.c Thu May 2 11:06:07 1991 --- ./amiga_args.c Thu May 2 14:34:25 1991 *************** *** 199,205 **** ad = ARGDESCNULL; }/*else*/ } ! else if (cmd_prev(cmd)) { flags = arg_flags(cmd_prev(cmd)); /* save flags */ if ( ARG_isGIVEN(cmd_prev(cmd)) ) { /* reset flags */ BCLEAR( arg_flags(cmd_prev(cmd)), ARGVALSEP ); --- 199,210 ---- ad = ARGDESCNULL; }/*else*/ } ! else if (cmd_prev(cmd)) { /* expecting a vlue from previous arg */ ! /* reset the argument flags - if this arg was already given, some ! ** of its flags may be set to indicate how it was given before. ! ** we need to know how it was given now (but save the old ones ! ** just in case the new one fails). ! */ flags = arg_flags(cmd_prev(cmd)); /* save flags */ if ( ARG_isGIVEN(cmd_prev(cmd)) ) { /* reset flags */ BCLEAR( arg_flags(cmd_prev(cmd)), ARGVALSEP ); *************** *** 228,233 **** --- 233,243 ---- } else { /* it's a positional argument or a list item */ if ( cmd_list(cmd) ) { /* its a list item */ + /* reset the argument flags - if this arg was already given, some + ** of its flags may be set to indicate how it was given before. + ** we need to know how it was given now (but save the old ones + ** just in case the new one fails). + */ flags = arg_flags(cmd_list(cmd)); /* save flags */ if ( ARG_isGIVEN(cmd_list(cmd)) ) { /* reset flags */ BCLEAR( arg_flags(cmd_list(cmd)), ARGVALSEP ); *************** *** 243,248 **** --- 253,260 ---- continue; } else { /* its a positional argument */ + + /* if FLAGS1ST is set then first positional marks end-of-flags */ if ( BTEST(cmd_flags(cmd), pa_FLAGS1ST) ) BSET( cmd_state(cmd), ps_NOFLAGS ); *************** *** 265,270 **** --- 277,287 ---- ad = ARGDESCNULL; } else { + /* reset the argument flags - if this arg was already given, some + ** of its flags may be set to indicate how it was given before. + ** we need to know how it was given now (but save the old ones + ** just in case the new one fails). + */ flags = arg_flags(ad); /* save flags */ if ( ARG_isGIVEN(ad) ) { /* reset flags for this appearance */ BCLEAR( arg_flags(ad), ARGVALSEP ); diff -cNr ../patchlevel4/argtype3.txt ./argtype3.txt *** ../patchlevel4/argtype3.txt Thu May 2 11:06:44 1991 --- ./argtype3.txt Wed Dec 31 18:00:00 1969 *************** *** 1,264 **** - - - - ARGTYPE(3) ARGTYPE(3) - - - - NAME - argtype - argument type functions used by parseargs(3) - - SYNOPSIS - #include <parseargs.h> - - BOOL argUsage( argdesc, argstr, copyf ); - BOOL argEnd( argdesc, argstr, copyf ); - BOOL argDummy( argdesc, argstr, copyf ); - BOOL argBool( argdesc, argstr, copyf ); - BOOL argSBool( argdesc, argstr, copyf ); - BOOL argUBool( argdesc, argstr, copyf ); - BOOL argTBool( argdesc, argstr, copyf ); - BOOL argChar( argdesc, argstr, copyf ); - BOOL argStr( argdesc, argstr, copyf ); - BOOL argInt( argdesc, argstr, copyf ); - BOOL argShort( argdesc, argstr, copyf ); - BOOL argLong( argdesc, argstr, copyf ); - BOOL argFloat( argdesc, argstr, copyf ); - BOOL argDouble( argdesc, argstr, copyf ); - BOOL listStr( argdesc, argstr, copyf ); - void listFree( arglist ); - void vecFree( argvec, type ); - void vecDeepFree( argvec, type ); - - ARGDESC *argdesc; - char *argstr; - BOOL copyf; - ArgList *arglist; - - DESCRIPTION - Each of these converts a parameter value to the internal - form, including validity checking. Their parameters and - return values all behave similarly. One of these routines is - 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). - - Once the argument translation routine is invoked, it is - responsible for converting the argument string to the - desired internal form (perhaps a number), and assigning the - resultant value to the arg_valp(ad) field of the argument - descriptor (this includes handling any necessary - (re)allocation if the matched argument has the ARGVEC flag - enabled). If the argument is an ARGVEC or ARGLIST then the - - - - Page 1 - - - - - - - ARGTYPE(3) ARGTYPE(3) - - - - routine is responsible for allocating any space, copying the - arg-flags to the value-specific flags, and setting the - ARGCOPYF flag for the value if it needs to be allocated as - well. - - - RETURN VALUE - TRUE The conversion was successful and the entire value - was used. - - - FALSE The conversion failed. The reason for failure - should be diagnosed using usrerr(3). - - - -N The conversion was successful but only N characters - of the value were used, the remaining characters may - still match other arguments. - - - PSEUDO-TYPES: argUsage, argDummy, argEnd - ArgUsage is used to specify an argument that causes the com- - mand usage to be printed. - - ArgDummy is used to force an item to show up in usage- - messages but the item itself is never matched against any - arguments from the command-line. - - ArgEnd is used by Amiga style command-lines to indicate an - argument that forces all remaining arguments to be con- - sidered positional args. - - These three are dummy functions. The routines themselves do - nothing of importance, we just need to have their addresses - available for identification in the corresponding command- - line styles. - - STRING-TYPES: argStr - ArgStr is one of the few argument translation routines that - actually uses the copyf flag. If copyf is true then the - string is duplicated. - - ArgStr assigns the given string (or a copy of it) to the - value referenced by arg_valp(ad) (unless the argument is a - vector in which case the given string is appended to the - end). - - ArgStr ensures that the very last item in a vector of - strings (the one accessed as vec.array[ vec.count ]) will - always be NULL. - - - - - - Page 2 - - - - - - - ARGTYPE(3) ARGTYPE(3) - - - - CHARACTER-TYPES: argChar - ArgChar assigns the given character to the value referenced - by arg_valp(ad) (unless the argument is a vector in which - case the given character is appended to the end). - - ArgChar ensures that the very last item in a vector of char- - acter (the one accessed as vec.array[ vec.count ]) will - always be a NULL byte so that the resulting vector may also - be used as a NULL terminated string. - - Unlike argStr, argChar will translate character escape - sequences such as `\n' and `\012'. - - INTEGER-TYPES: argInt, argShort, argLong - Each of these functions converts the given string to the - desired integral type. The value may be specified as an - octal number by specifying the first digit to be 0. Simi- - larly, If the first two characters are `0x' then the number - is treated as hexadecimal. - - FLOATING-POINT-TYPES: argFloat, argDouble - Each of these functions converts the given string to the - desired floating-point type. - - BOOLEAN-TYPES: argBool, argSBool, argTBool, argUBool - ArgBool and argSBool set a boolean value (if no value is - given). ArgUBool unsets a boolean value (if no value is - given). ArgTBool toggles a boolean value (if no value is - given). If a value is supplied to any of these routines, - then the string is looked up in a table and assigned the - corresponding value. - - If a value is supplied for an argument that was matched via - its single character name and is part of the same argv ele- - ment as the argument-name (so that both ARGKEYWORD and - ARGVALSEP are not set), then only the first character of the - value is used (unless it is not found in our table, in which - case the value is ignored and the default action is taken). - The table used for single-character-options is the follow- - ing: - - `0' or `-' - The corresponding boolean flag is set to FALSE. - - `1' or `+' - The corresponding boolean flag is set to TRUE. - - `^' or `~' - The corresponding boolean flag is toggled. - - The possible argument strings for long-options (keywords) - are as follows (case-insensitive): - - - - Page 3 - - - - - - - ARGTYPE(3) ARGTYPE(3) - - - - ``0'', ``-'', ``OFF'', or ``FALSE'' - The corresponding boolean flag is set to FALSE. - - ``1'', ``+'', ``ON'', or ``TRUE'' - The corresponding boolean flag is set to TRUE. - - LIST TYPES: listStr - The listStr argument translation routine is only intended - for use on behalf of arguments that have the ARGLIST flag - enabled. It will allocate space for a new node (and for the - new string if copyf is set) and append it to the end of the - list. The argument-list may later be deallocated by invoking - the function listFree and passing it the address of the - first item in the list. - - - VecFree is a macro that is used to deallocate argument- - vectors. It will free the array and flags fields of a vec- - tor, set them to NULL, and set the count field to zero. Vec- - DeepFree is a macro that is similar to vecFree but will - additionally look at each item in the array; any component - of the array that had ARGCOPYF enabled will also be deallo- - cated. Both macros are given the vector structure to free - followed by the type of the items in the vector. - - SEE ALSO - parseargs(3), parseargs(1), parsecntl(3) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Page 4 - - - --- 0 ---- diff -cNr ../patchlevel4/doc/Makefile ./doc/Makefile *** ../patchlevel4/doc/Makefile Thu May 2 11:05:46 1991 --- ./doc/Makefile Tue May 14 12:32:17 1991 *************** *** 90,101 **** ### # include dependencies ### ! argtype.3: ! parseargs.1: ! parseargs.3: ! parsecntl.3: ### # maintenance dependencies ### --- 90,140 ---- ### # include dependencies ### ! argtype.3: argtype.man3 + parseargs.1: parseargs.man1 \ + ../test.sh \ + argvalopt.inc \ + bugs.inc \ + caveats.inc \ + env_args.inc \ + env_parse.inc \ + env_usage.inc \ + parseargs1.inc \ + sh_arrays.inc \ + shells.inc + parseargs.3: parseargs.man3 \ + arg_macros.inc \ + argdesc.inc \ + argflags.inc \ + caveats.inc \ + cmd_macros.inc \ + defargs.inc \ + effects.inc \ + env_args.inc \ + env_parse.inc \ + env_usage.inc \ + fparseargs3.inc \ + lib_bugs.inc \ + lparseargs3.inc \ + multivals.inc \ + parseargs3.inc \ + returns.inc \ + sparseargs3.inc \ + usage3.inc \ + vparseargs3.inc + + parsecntl.3: parsecntl.man3 \ + argflags.inc \ + effects.inc \ + parsecntl3.inc \ + parsecntls.inc \ + parseflags.inc \ + parsemodes.inc \ + returns.inc + + ### # maintenance dependencies ### *************** *** 105,111 **** clobber: clean ${DEL} *.txt ! spell: ${INCS} ${SRCS}} ${SPELL} ${SPELLFLAGS} ${INCS} ${SRCS} print: ${MANFILES} ${INCS} --- 144,150 ---- clobber: clean ${DEL} *.txt ! spell: ${INCS} ${SRCS} ${SPELL} ${SPELLFLAGS} ${INCS} ${SRCS} print: ${MANFILES} ${INCS} diff -cNr ../patchlevel4/doc/arg_macros.inc ./doc/arg_macros.inc *** ../patchlevel4/doc/arg_macros.inc Thu May 2 10:56:14 1991 --- ./doc/arg_macros.inc Thu May 2 14:34:39 1991 *************** *** 27,33 **** .IP "\fIarg_sdesc\fP(ad)" Return the description of an argument. If a description was supplied, the \fI\s-1ARGDESCRIBED\s+1\fP flag will be set and the description will ! immediately follow the terminating NUL byte of the string name. .\"--------------------------------------------- .IP "\fIARG_isDESCRIBED\fP(ad)" Evaluates to \s-1TRUE\s+1 only if an argument description was provided. --- 27,33 ---- .IP "\fIarg_sdesc\fP(ad)" Return the description of an argument. If a description was supplied, the \fI\s-1ARGDESCRIBED\s+1\fP flag will be set and the description will ! immediately follow the terminating NULL byte of the string name. .\"--------------------------------------------- .IP "\fIARG_isDESCRIBED\fP(ad)" Evaluates to \s-1TRUE\s+1 only if an argument description was provided. diff -cNr ../patchlevel4/doc/argdesc.inc ./doc/argdesc.inc *** ../patchlevel4/doc/argdesc.inc Thu May 2 11:00:21 1991 --- ./doc/argdesc.inc Thu May 2 14:34:41 1991 *************** *** 52,57 **** square-brackets, or angle-brackets). If the long-name 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. --- 52,57 ---- square-brackets, or angle-brackets). If the long-name 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. diff -cNr ../patchlevel4/doc/argflags.inc ./doc/argflags.inc *** ../patchlevel4/doc/argflags.inc Thu May 2 10:56:15 1991 --- ./doc/argflags.inc Thu May 2 14:34:44 1991 *************** *** 51,57 **** .\"--------------------------------------------- .IP "\fI\s-1ARGLIST\s+1\fP" A variable number of values are used for this argument (and hence may ! use more than one or two argv elements from the command-line as in "\fB\-l\fI val1 val2\fR ..."). The list of values must be stored in an .I ArgList structure (\s-1NOT\s+1 a vector structure), an the corresponding argument-type --- 51,57 ---- .\"--------------------------------------------- .IP "\fI\s-1ARGLIST\s+1\fP" A variable number of values are used for this argument (and hence may ! use more than one or two \f4argv\fP elements from the command-line as in "\fB\-l\fI val1 val2\fR ..."). The list of values must be stored in an .I ArgList structure (\s-1NOT\s+1 a vector structure), an the corresponding argument-type diff -cNr ../patchlevel4/doc/argtype.man3 ./doc/argtype.man3 *** ../patchlevel4/doc/argtype.man3 Thu May 2 11:00:40 1991 --- ./doc/argtype.man3 Thu May 2 14:34:47 1991 *************** *** 37,45 **** all behave similarly. One of these routines is called when an argument of that particular type is matched by one of the argument parsing function in \fIparseargs\fP(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 possible argument ! string for that matched argument, and (3) a boolean filed that is \s-1TRUE\s+1 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). --- 37,45 ---- all behave similarly. One of these routines is called when an argument of that particular type is matched by one of the argument parsing function in \fIparseargs\fP(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 possible argument ! string for that matched argument, and (3) a boolean field that is \s-1TRUE\s+1 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). *************** *** 128,134 **** in a table and assigned the corresponding value. If a value is supplied for an argument that was matched via its ! single character name and is part of the same argv element as the argument-name (so that both \fBARGKEYWORD\fP and \fBARGVALSEP\fP are not set), then only the first character of the value is used (unless it is --- 128,134 ---- in a table and assigned the corresponding value. If a value is supplied for an argument that was matched via its ! single character name and is part of the same \f4argv\fP element as the argument-name (so that both \fBARGKEYWORD\fP and \fBARGVALSEP\fP are not set), then only the first character of the value is used (unless it is *************** *** 168,172 **** type of the items in the vector. .SH SEE ALSO .IR parseargs (3), ! .IR parseargs (3), ! .IR parsecntl (1), --- 168,172 ---- type of the items in the vector. .SH SEE ALSO .IR parseargs (3), ! .IR parseargs (1), ! .IR parsecntl (3) diff -cNr ../patchlevel4/doc/bugs.inc ./doc/bugs.inc *** ../patchlevel4/doc/bugs.inc Thu May 2 10:56:16 1991 --- ./doc/bugs.inc Thu May 2 14:34:52 1991 *************** *** 27,38 **** .PP \fIParseargs\fP cannot properly preserve any newlines in shell variables if the \fBeval\fP command is used to read its output (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 \fBparseargs\fP ! to a temporary file and use the \fBsource\fP command in \fIcsh\fP or the ! dot command (`\fB.\fP') in sh and ksh, to interpret the results; otherwise, ! newlines will be translated into spaces, or characters following ! a newline may be lost, in any variables that are set by \fBparseargs\fP. ! .PP ! Parseargs(1) is subject to the same caveats as parseargs(3). Refer to the ! \s-1CAVEATS\s+1 section of the parseargs(3) manual page(s) for more information. --- 27,36 ---- .PP \fIParseargs\fP cannot properly preserve any newlines in shell variables if the \fBeval\fP command is used to read its output (this is a shortcoming ! of the \fBeval\fP command, not of \fBparseargs\fP). If the user is concerned ! about this particular case, then the user should redirect the output from ! \fBparseargs\fP to a temporary file and use the \fBsource\fP command in ! \fIcsh\fP or the dot command (`\fB.\fP') in sh and ksh, to interpret the ! results; otherwise, newlines will be translated into spaces, or characters ! following a newline may be lost, in any variables that are set by ! \fBparseargs\fP. diff -cNr ../patchlevel4/doc/cmd_macros.inc ./doc/cmd_macros.inc *** ../patchlevel4/doc/cmd_macros.inc Thu May 2 10:56:17 1991 --- ./doc/cmd_macros.inc Thu May 2 14:34:57 1991 *************** *** 3,9 **** .\"-- xdoc -man -p '[ \t]*' -s CMD-MACROS ../parseargs.h .\"---------------------------------------------------------------------------- .SH "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 \s-1STARTOFARGS\s+1 macro is used in conjunction with \s-1ENDOFARGS\s+1). --- 3,9 ---- .\"-- xdoc -man -p '[ \t]*' -s CMD-MACROS ../parseargs.h .\"---------------------------------------------------------------------------- .SH "CMD MACROS" ! \f4<parseargs.h>\fP 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 \s-1STARTOFARGS\s+1 macro is used in conjunction with \s-1ENDOFARGS\s+1). diff -cNr ../patchlevel4/doc/defargs.inc ./doc/defargs.inc *** ../patchlevel4/doc/defargs.inc Thu May 2 10:56:18 1991 --- ./doc/defargs.inc Thu May 2 14:34:59 1991 *************** *** 4,11 **** .\"---------------------------------------------------------------------------- .SH "DEFAULT ARGUMENT DESCRIPTOR" .PP ! Each argdesc-array has an initial default argument list (which may ! be reset using the pc_DEFARGS function code with parsecntl). This initial default argument-list contains `?' and `H' which may be used as single character keywords to display command-usage for all command-line styles. Similarly, ``?'', ``H'', and ``Help'' may be used as long-keywords to display --- 4,11 ---- .\"---------------------------------------------------------------------------- .SH "DEFAULT ARGUMENT DESCRIPTOR" .PP ! Each argdesc-array has an initial default argument list (which may be reset ! using the pc_DEFARGS function code with \fIparsecntl\fP). This initial default argument-list contains `?' and `H' which may be used as single character keywords to display command-usage for all command-line styles. Similarly, ``?'', ``H'', and ``Help'' may be used as long-keywords to display *************** *** 12,17 **** command-usage for all command-line styles. In Addition, for \s-1VMS\s+1 style commands, the qualifiers \fB\s-1/INPUT\s+1=\fIfile\fR, \fB\s-1/OUTPUT\s+1=\fIfile\fR, and \fB\s-1/ERROR\s+1=\fIfile\fR, may be used ! to redirect stdin, stdout, and stderr (respectively) to a file. For ! Amiga\s-1DOS\s+1 style commands, the keyword ``ENDKWDS'' may be used to ! disable parsing for any more keywords on the command-line. --- 12,17 ---- command-usage for all command-line styles. In Addition, for \s-1VMS\s+1 style commands, the qualifiers \fB\s-1/INPUT\s+1=\fIfile\fR, \fB\s-1/OUTPUT\s+1=\fIfile\fR, and \fB\s-1/ERROR\s+1=\fIfile\fR, may be used ! to redirect \f4stdin\fP, \f4stdout\fP, and \f4stderr\fP (respectively) to a ! file. For Amiga\s-1DOS\s+1 style commands, the keyword ``ENDKWDS'' may be ! used to disable parsing for any more keywords on the command-line. diff -cNr ../patchlevel4/doc/env_args.inc ./doc/env_args.inc *** ../patchlevel4/doc/env_args.inc Thu May 2 11:00:46 1991 --- ./doc/env_args.inc Thu May 2 14:35:04 1991 *************** *** 5,11 **** .SH "SUPPLYING DEFAULT ARGUMENTS" Programs that use \fIparseargs\fP may be given default arguments under UNIX and PCs through the use of environment variables (symbols are used for VMS ! systems). If a C-program or shell-script uses parseargs to implement a command named ``\fIcmd\fP'' then the environment variable ``\s-1CMD_ARGS\s+1'' will be parsed for any "default" arguments before the command-line is parsed. The command-line will over-ride any options that are specified in this --- 5,11 ---- .SH "SUPPLYING DEFAULT ARGUMENTS" Programs that use \fIparseargs\fP may be given default arguments under UNIX and PCs through the use of environment variables (symbols are used for VMS ! systems). If a C-program or shell-script uses \fIparseargs\fP to implement a command named ``\fIcmd\fP'' then the environment variable ``\s-1CMD_ARGS\s+1'' will be parsed for any "default" arguments before the command-line is parsed. The command-line will over-ride any options that are specified in this diff -cNr ../patchlevel4/doc/env_parse.inc ./doc/env_parse.inc *** ../patchlevel4/doc/env_parse.inc Thu May 2 11:00:56 1991 --- ./doc/env_parse.inc Thu May 2 14:35:06 1991 *************** *** 8,19 **** The user may set his (or her) own desired parsing behavior through the use of the ``\s-1PARSECNTL\s+1'' environment variable. By indicating any number of flags (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 negated by immediately preceding it with a `!' or `-' character. The possible ``flags'' are given by the following table. Flags are case-insensitive. .sp 4p .IP "\fIPrompt\fP" Prompt the user for any missing arguments that are required on the command-line. No special escaping or quoting is performed on the --- 8,20 ---- The user may set his (or her) own desired parsing behavior through the use of the ``\s-1PARSECNTL\s+1'' environment variable. By indicating any number of flags (possibly negated) the user will ! directly modify the behavior of the \fIparseargs\fP library. Flags may be combined by placing a `+' or `|' character in between flags. A switch is negated by immediately preceding it with a `!' or `-' character. The possible ``flags'' are given by the following table. Flags are case-insensitive. .sp 4p + .\"--------------------------------------------- .IP "\fIPrompt\fP" Prompt the user for any missing arguments that are required on the command-line. No special escaping or quoting is performed on the *************** *** 20,61 **** 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 "\fIIgnore\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 ! and program execution is terminated. ! .\"---------------------- .IP "\fIOptsOnly\fP" ! 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). ! .\"---------------------- .IP "\fIKwdsOnly\fP" ! 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). ! .\"---------------------- .IP "\fILoptsOnly\fP" Same as \fIKwdsOnly\fP. ! .\"---------------------- .IP "\fIFlags1st\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 UNIX, if this flag is SET then parseargs will ! consider the command line "cmd -x arg" to consist of one option and ! one positional argument; however the command line "cmd arg -x" would ! be considered to consist of two positional arguments (the -x option ! will be unmatched). ! If this flag is UNSET, then both of the previous examples are considered to consist of one option and one positional argument. ! .\"---------------------- .IP "\fICaseIgnore\fP" ! 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). .sp 4p .PP If the environment variable ``\s-1PARSECNTL\s+1'' is empty or --- 21,64 ---- 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 "\fIIgnore\fP" 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. ! .\"--------------------------------------------- .IP "\fIOptsOnly\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 "\fIKwdsOnly\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 "\fILoptsOnly\fP" Same as \fIKwdsOnly\fP. ! .\"--------------------------------------------- .IP "\fIFlags1st\fP" ! Setting this flag causes the \fIparseargs\fP 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). ! 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 "\fICaseIgnore\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" to be considered equivalent). ! .\"--------------------------------------------- .sp 4p .PP If the environment variable ``\s-1PARSECNTL\s+1'' is empty or diff -cNr ../patchlevel4/doc/env_usage.inc ./doc/env_usage.inc *** ../patchlevel4/doc/env_usage.inc Thu May 2 10:56:19 1991 --- ./doc/env_usage.inc Thu May 2 14:35:08 1991 *************** *** 16,22 **** 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 ``\s-1USAGECNTL\s+1'' environment variable are given by the following table. .sp 4p .\"--------------------------------------- --- 16,22 ---- 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 `!' ! or `-' character. The ``modes'' which correspond to the possible values of the ``\s-1USAGECNTL\s+1'' environment variable are given by the following table. .sp 4p .\"--------------------------------------- diff -cNr ../patchlevel4/doc/fparseargs3.inc ./doc/fparseargs3.inc *** ../patchlevel4/doc/fparseargs3.inc Thu May 2 10:56:20 1991 --- ./doc/fparseargs3.inc Thu May 2 14:35:10 1991 *************** *** 4,10 **** .\"---------------------------------------------------------------------------- .PP Given a readable input stream and an argdesc array, \fIfparseargs\fP ! will parse arguments in a file in much the same manner as \fIparseargs\fP. 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 \s-1VMS\s+1) then --- 4,10 ---- .\"---------------------------------------------------------------------------- .PP Given a readable input stream and an argdesc array, \fIfparseargs\fP ! will parse arguments in a file in the same manner as \fIparseargs\fP. 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 \s-1VMS\s+1) then diff -cNr ../patchlevel4/doc/lparseargs3.inc ./doc/lparseargs3.inc *** ../patchlevel4/doc/lparseargs3.inc Thu May 2 11:01:17 1991 --- ./doc/lparseargs3.inc Thu May 2 14:35:15 1991 *************** *** 4,7 **** .\"---------------------------------------------------------------------------- .PP Given an ArgList and an argdesc array, \fIlparseargs\fP ! will parse arguments in an ArgList in much the same manner as \fIparseargs\fP. --- 4,7 ---- .\"---------------------------------------------------------------------------- .PP Given an ArgList and an argdesc array, \fIlparseargs\fP ! will parse arguments in an ArgList in the same manner as \fIparseargs\fP. diff -cNr ../patchlevel4/doc/multivals.inc ./doc/multivals.inc *** ../patchlevel4/doc/multivals.inc Thu May 2 11:01:27 1991 --- ./doc/multivals.inc Thu May 2 14:35:18 1991 *************** *** 28,44 **** the function .I listFree. .I ListFree ! takes one parameter: first of which is the address of the first item in ! the arg-list. .PP An alternative to argument-lists is argument vectors (or arg-vectors). Arg-vectors use the \s-1ARGVEC\s+1 flag instead of the \s-1ARGLIST\s+1 flag and do not require a special \fIlistXxxx\fP function for each vector-type. Each of the \fIargXxxx\fP functions is 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 \f4<parseargs.h>\fR which are used for arg-vectors. \s-1ARGVEC_T\s+1 may be used to declare a vector structure or a vector type; \s-1ARGVEC_EMPTY\s+1 may be used to initialize the structure. --- 28,43 ---- the function .I listFree. .I ListFree