(Argp Special Keys): Document ARGP_KEY_ARGS.
authordrepper <drepper>
Thu, 19 Jun 1997 18:20:48 +0000 (18:20 +0000)
committerdrepper <drepper>
Thu, 19 Jun 1997 18:20:48 +0000 (18:20 +0000)
manual/argp.texi

index 53a405e..f28a87a 100644 (file)
@@ -271,13 +271,13 @@ group); in this usage, it's conventional to end the string with a
 The group this option is in.
 
 In a long help message, options are sorted alphabetically within each
-group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n},
--@var{m}, @dots{}, -2, -1.  Every entry in an options array with this
+group, and the groups presented in the order @math{0, 1, 2, @dots{}, @var{n},
+-@var{m}, @dots{}, -2, -1}.  Every entry in an options array with this
 field 0 will inherit the group number of the previous entry, or zero if
 it's the first one, unless its a group header (@code{name} and
-@code{key} fields both zero), in which case, the previous entry + 1 is
+@code{key} fields both zero), in which case, the previous entry @math{+ 1} is
 the default.  Automagic options such as @samp{--help} are put into group
--1.
+--1.
 
 Note that because of C structure initialization rules, this field
 often need not be specified, because 0 is the right value.
@@ -460,6 +460,35 @@ the argument (perhaps into an option), and have it processed again.
 
 @comment argp.h
 @comment GNU
+@item ARGP_KEY_ARGS
+If a parser function returns @code{ARGP_ERR_UNKNOWN} for
+@code{ARGP_KEY_ARG}, it is immediately called again with the key
+@code{ARGP_KEY_ARGS}, which has a similar meaning, but is slightly more
+convenient for consuming all remaining arguments.  @var{arg} is 0, and
+the tail of the argument vector may be found at @code{@var{state}->argv
++ @var{state}->next}.  If success is returned for this key, and
+@code{@var{state}->next} is unchanged, then all remaining arguments are
+considered to have been consumed, otherwise, the amount by which
+@code{@var{state}->next} has been adjust indicates how many were used.
+For instance, here's an example that uses both, for different args:
+
+@smallexample
+...
+case ARGP_KEY_ARG:
+  if (@var{state}->arg_num == 0)
+    /* First argument */
+    first_arg = @var{arg};
+  else
+    return ARGP_KEY_UNKNOWN;    /* Let the next case parse it.  */
+  break;
+case ARGP_KEY_ARGS:
+  remaining_args = @var{state}->argv + @var{state}->next;
+  num_remaining_args = @var{state}->argc - @var{state}->next;
+  break;
+@end smallexample
+
+@comment argp.h
+@comment GNU
 @item ARGP_KEY_END
 There are no more command line arguments at all.
 
@@ -797,7 +826,11 @@ Don't exit on errors (they may still result in error messages).
 @comment argp.h
 @comment GNU
 @item ARGP_LONG_ONLY
-Use the gnu getopt `long-only' rules for parsing arguments.
+Use the gnu getopt `long-only' rules for parsing arguments.  This
+allows long-options to be recognized with only a single @samp{-} (for
+instances, @samp{-help}), but results in a generally somewhat less
+useful interface, that conflicts with the way most GNU programs work.
+For this reason, its use is discouraged.
 
 @comment argp.h
 @comment GNU