diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/examples/argp-ex1.c | 5 | ||||
| -rw-r--r-- | manual/examples/argp-ex2.c | 21 | ||||
| -rw-r--r-- | manual/examples/argp-ex3.c | 54 | ||||
| -rw-r--r-- | manual/examples/argp-ex4.c | 23 | ||||
| -rw-r--r-- | manual/startup.texi | 6 |
5 files changed, 104 insertions, 5 deletions
diff --git a/manual/examples/argp-ex1.c b/manual/examples/argp-ex1.c index c87ebbb532..50ac0ed978 100644 --- a/manual/examples/argp-ex1.c +++ b/manual/examples/argp-ex1.c @@ -1,5 +1,10 @@ /* Argp example #1 -- a minimal program using argp */ +/* This is (probably) the smallest possible program that + uses argp. It won't do much except give an error + messages and exit when there are any arguments, and print + a (rather pointless) messages for --help. */ + #include <argp.h> int main (int argc, char **argv) diff --git a/manual/examples/argp-ex2.c b/manual/examples/argp-ex2.c index d1b149b494..55f59f2ab8 100644 --- a/manual/examples/argp-ex2.c +++ b/manual/examples/argp-ex2.c @@ -1,11 +1,30 @@ /* Argp example #2 -- a pretty minimal program using argp */ +/* This program doesn't use any options or arguments, but uses + argp to be compliant with the GNU standard command line + format. + + In addition to making sure no arguments are given, and + implementing a --help option, this example will have a + --version option, and will put the given documentation string + and bug address in the --help output, as per GNU standards. + + The variable ARGP contains the argument parser specification; + adding fields to this structure is the way most parameters are + passed to argp_parse (the first three fields are usually used, + but not in this small program). There are also two global + variables that argp knows about defined here, + ARGP_PROGRAM_VERSION and ARGP_PROGRAM_BUG_ADDRESS (they are + global variables becuase they will almost always be constant + for a given program, even if it uses different argument + parsers for various tasks). */ + #include <argp.h> const char *argp_program_version = "argp-ex2 1.0"; const char *argp_program_bug_address = - "<bug-gnu-utils@@prep.ai.mit.edu>"; + "<bug-gnu-utils@@gnu.org>"; /* Program documentation. */ static char doc[] = diff --git a/manual/examples/argp-ex3.c b/manual/examples/argp-ex3.c index 363ee59e11..87d993f8ae 100644 --- a/manual/examples/argp-ex3.c +++ b/manual/examples/argp-ex3.c @@ -1,11 +1,63 @@ /* Argp example #3 -- a program with options and arguments using argp */ +/* This program uses the same features as example 2, and uses options and + arguments. + + We now use the first four fields in ARGP, so here's a description of them: + OPTIONS -- A pointer to a vector of struct argp_option (see below) + PARSER -- A function to parse a single option, called by argp + ARGS_DOC -- A string describing how the non-option arguments should look + DOC -- A descriptive string about this program; if it contains a + vertical tab character (\v), the part after it will be + printed *following* the options + + The function PARSER takes the following arguments: + KEY -- An integer specifying which option this is (taken + from the KEY field in each struct argp_option), or + a special key specifying something else; the only + special keys we use here are ARGP_KEY_ARG, meaning + a non-option argument, and ARGP_KEY_END, meaning + that all argumens have been parsed + ARG -- For an option KEY, the string value of its + argument, or NULL if it has none + STATE-- A pointer to a struct argp_state, containing + various useful information about the parsing state; used here + are the INPUT field, which reflects the INPUT argument to + argp_parse, and the ARG_NUM field, which is the number of the + current non-option argument being parsed + It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the + given KEY wasn't recognized, or an errno value indicating some other + error. + + Note that in this example, main uses a structure to communicate with the + parse_opt function, a pointer to which it passes in the INPUT argument to + argp_parse. Of course, it's also possible to use global variables + instead, but this is somewhat more flexible. + + The OPTIONS field contains a pointer to a vector of struct argp_option's; + that structure has the following fields (if you assign your option + structures using array initialization like this example, unspecified + fields will be defaulted to 0, and need not be specified): + NAME -- The name of this option's long option (may be zero) + KEY -- The KEY to pass to the PARSER function when parsing this option, + *and* the name of this option's short option, if it is a + printable ascii character + ARG -- The name of this option's argument, if any + FLAGS -- Flags describing this option; some of them are: + OPTION_ARG_OPTIONAL -- The argument to this option is optional + OPTION_ALIAS -- This option is an alias for the + previous option + OPTION_HIDDEN -- Don't show this option in --help output + DOC -- A documentation string for this option, shown in --help output + + An options vector should be terminated by an option with all fields zero. */ + #include <argp.h> const char *argp_program_version = "argp-ex3 1.0"; const char *argp_program_bug_address = - "<bug-gnu-utils@@prep.ai.mit.edu>"; + "<bug-gnu-utils@@gnu.org>"; /* Program documentation. */ static char doc[] = diff --git a/manual/examples/argp-ex4.c b/manual/examples/argp-ex4.c index 24dd417a81..fa5a8d00ec 100644 --- a/manual/examples/argp-ex4.c +++ b/manual/examples/argp-ex4.c @@ -1,5 +1,28 @@ /* Argp example #4 -- a program with somewhat more complicated options */ +/* This program uses the same features as example 3, but has more + options, and somewhat more structure in the -help output. It + also shows how you can `steal' the remainder of the input + arguments past a certain point, for programs that accept a + list of items. It also shows the special argp KEY value + ARGP_KEY_NO_ARGS, which is only given if no non-option + arguments were supplied to the program. + + For structuring the help output, two features are used, + *headers* which are entries in the options vector with the + first four fields being zero, and a two part documentation + string (in the variable DOC), which allows documentation both + before and after the options; the two parts of DOC are + separated by a vertical-tab character ('\v', or '\013'). By + convention, the documentation before the options is just a + short string saying what the program does, and that afterwards + is longer, describing the behavior in more detail. All + documentation strings are automatically filled for output, + although newlines may be included to force a line break at a + particular point. All documenation strings are also passed to + the `gettext' function, for possible translation into the + current locale. */ + #include <stdlib.h> #include <error.h> #include <argp.h> diff --git a/manual/startup.texi b/manual/startup.texi index dd21c89e6f..bea6c39676 100644 --- a/manual/startup.texi +++ b/manual/startup.texi @@ -82,7 +82,7 @@ allow this three-argument form, so to be portable it is best to write * Parsing Program Arguments:: Ways to parse program options and arguments. @end menu -@node Argument Syntax +@node Argument Syntax, Parsing Program Arguments, , Program Arguments @subsection Program Argument Syntax Conventions @cindex program argument syntax @cindex syntax, for program arguments @@ -154,7 +154,7 @@ accept an argument that is itself optional. Eventually, the GNU system will provide completion for long option names in the shell. -@node Parsing Program Arguments +@node Parsing Program Arguments, , Argument Syntax, Program Arguments @subsection Parsing Program Arguments @cindex program arguments, parsing @@ -188,7 +188,7 @@ it does more of the dirty work for you. @node Suboptions, Suboptions Example, Argp, Parsing Program Arguments @c This is a @section so that it's at the same level as getopt and argp -@section Parsing of Suboptions +@subsubsection Parsing of Suboptions Having a single level of options is sometimes not enough. There might be too many options which have to be available or a set of options is |