home *** CD-ROM | disk | FTP | other *** search
-
- argproc - process command line arguments
-
- SYNOPSIS
-
- #include <argproc.h>
-
- long argproc(argc, argv, format [ , pointer ] . . . )
- int argc;
- char *argv[], *format;
-
- Format string contents:
- - introduces one or more switches with single-letter names
- = is same as -, but sets a boolean telling whether each switch
- actually appeared on the command line
- {} surround switches with long names
- %s, %d, %f, %hd, %ld, %lf, etc. may appear alone to indicate
- positional parameters, or after a switch name to indicate
- arguments to that switch. These are processed by sscanf().
- , separates arguments of a single switch
- [] surround optional arguments
-
- NOTICE
-
- Argproc is a routine written by Steve Colwell at S.R. Systems.
- It is being posted to Usenet to stimulate discussion about
- command line argument parsers, and may be freely used and copied
- for any purpose. This routine has been in daily use for over a year
- now; however, the version being posted was modified to use vsprintf
- instead of _doprnt, and has been tested only lightly.
-
- DESCRIPTION
-
- This routine provides an easy way to parse command line
- arguments. The main routine passes its argc, argv, and a
- scanf-type format string to argproc, which parses the com-
- mand line for parameters and switches as described below,
- returning the various values in the pointed-to variables.
- It does not alter argv[].
-
- Each entry in the format string has one of the following
- forms:
-
- -XYZ X, Y, and Z are the one-char names of boolean flags.
-
- -X%s %s is a scanf-type format specification, which is used
- only if -X precedes it.
-
- -X[%s] %s is a optional scanf-type format specification, which
- may or may not be supplied after the -X.
- -X[%d,%s] is allowed, but -X%d[,%s] is not supported.
-
- =X X is a boolean flag, a boolean value is put in the associated
- variable. The '=' may be used in place of the '-' in any
- of the above formats.
-
- {=XYZ}
- XYZ is a many-char name for a single boolean flag.
- {-outfile%s}
- 'outfile' is a many-char name for a flag with a string argument.
-
- %s the next argument that doesn't start with - is taken as a %s
- type.
-
- Generally, anywhere a "%d" or "%s" is listed above, ANY scanf-style
- format specifier may appear.
-
- The only way to have a switch with a greater than one char
- name is by using the braces. For example, "{-longname}".
- All other flag names are only one character long. The flags
- are detected anywhere in the argument list, no matter where
- they appear in the format string.
-
- A single argument may contain more than one format command.
- For example, "%d,%d" gets two integers, seperated by a
- comma, from one argument. This form implies two relevant
- bits in the returned bit map as well as two variables in the
- variable list.
-
- A format may use the scanf "%*c" form to throw away an argu-
- ment or a part of an argument. In this case a bit is
- assigned, but no variable is used as there is no value to
- receive. This may be used to get two ints separated by any
- char (ie. "%d%*c%d" to read 5,6 5-6 etc).
-
- The order of switches in the format string doesn't imply
- that the switches must be given in any order on the commandline.
-
- RETURN VALUE
-
- The return value is -1 for error.
-
- If there was no error, one bit is set for each unit of the
- format string which was successfully parsed.
- This turns out to be difficult to use in practice, especially when
- adding new options; I suggest using the = notation instead.
- (A unit is a flag or argument format command in the format string.
- For example, "-moyx" has four units and "-X%d" has two units.
- The leftmost unit is assigned bit 0, the second unit is bit 1,
- etc. If there are more than 32 "units" in the format string,
- only the first 32 have bits in the return value.
- This is one reason why the equals sign "=x" notation was added.)
-
- EXAMPLES
-
- Always call lose_title(argv[0]) first thing in main().
-
- boolean x, y, z;
- argproc(argc,argv,"=xy =z", &x, &y, &z);
-
- short a = 5;
- argproc(argc,argv,"-a%hd", &a);
-
- char infile[100];
- static char logfile[100] = "";
- argproc(argc,argv,"{-logfile%s} %s", logfile, infile);
-
- char ofile[100], pfile[100];
- boolean pGiven;
- argproc(argc,argv,"-o%s =p[%s]", ofile, &pGiven, pfile);
-
- See also demo.c.
-
- DIAGNOSTICS
-
- If the user enters an unknown option, argproc usually prints a message to
- stderr and exits with a status of 1.
- However, if the first character of the format string is 'W',
- argproc prints an error message and returns with a value of -1.
- If the first character of the format string is 'N',
- argproc places an error message in the global ErrString, and returns
- with a value of -1.
- See 'lose.doc'.
-
- BUGS
-
- Longer switch names must occur before shorter ones to override them;
- that is, the format string "-f {-fc}" will never allow the flag
- -fc to be found, it will just give the error "no flag -c".
-
- Does not support the "--" convention.
-
- Does not allow spaces between an option and its argument
- (e.g. "-o foo" does NOT match the format "-o%s"; "-ofoo" does).
-
- LIBRARY
-
- Use argproc.l
-
-