Adjust collidx_table_lookup for name change.
[kopensolaris-gnu/glibc.git] / argp / argp.h
index be72756..564db55 100644 (file)
@@ -1,41 +1,44 @@
 /* Hierarchial argument parsing, layered over getopt.
-   Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
+   Copyright (C) 1995,1996,1997,1998,1999,2003 Free Software Foundation, Inc.
    This file is part of the GNU C Library.
    Written by Miles Bader <miles@gnu.ai.mit.edu>.
 
    The GNU C Library is free software; you can redistribute it and/or
-   modify it under the terms of the GNU Library General Public License as
-   published by the Free Software Foundation; either version 2 of the
-   License, or (at your option) any later version.
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2.1 of the License, or (at your option) any later version.
 
    The GNU C Library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-   Library General Public License for more details.
+   Lesser General Public License for more details.
 
-   You should have received a copy of the GNU Library General Public
-   License along with the GNU C Library; see the file COPYING.LIB.  If not,
-   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-   Boston, MA 02111-1307, USA.  */
+   You should have received a copy of the GNU Lesser General Public
+   License along with the GNU C Library; if not, write to the Free
+   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+   02111-1307 USA.  */
 
-#ifndef __ARGP_H__
-#define __ARGP_H__
+#ifndef _ARGP_H
+#define _ARGP_H
 
 #include <stdio.h>
-#include <errno.h>
 #include <ctype.h>
 #include <getopt.h>
 
+#define __need_error_t
+#include <errno.h>
+
 #ifndef __const
-#define __const const
+# define __const const
 #endif
 
-#ifndef __P
-# if (defined (__STDC__) && __STDC__) || defined (__cplusplus)
-#  define __P(args)    args
-# else
-#  define __P(args)    ()
-# endif
+#ifndef __THROW
+# define __THROW
+#endif
+
+#ifndef __error_t_defined
+typedef int error_t;
+# define __error_t_defined
 #endif
 \f
 #ifdef  __cplusplus
@@ -97,18 +100,28 @@ struct argp_option
    is set, then the option NAME field is displayed unmodified (e.g., no `--'
    prefix is added) at the left-margin (where a *short* option would normally
    be displayed), and the documentation string in the normal place.  For
-   purposes of sorting, any leading whitespace and puncuation is ignored,
+   purposes of sorting, any leading whitespace and punctuation is ignored,
    except that if the first non-whitespace character is not `-', this entry
    is displayed after all options (and OPTION_DOC entries with a leading `-')
    in the same group.  */
 #define OPTION_DOC             0x8
+
+/* This option shouldn't be included in `long' usage messages (but is still
+   included in help messages).  This is mainly intended for options that are
+   completely documented in an argp's ARGS_DOC field, in which case including
+   the option in the generic usage list would be redundant.  For instance,
+   if ARGS_DOC is "FOO BAR\n-x BLAH", and the `-x' option's purpose is to
+   distinguish these two cases, -x should probably be marked
+   OPTION_NO_USAGE.  */
+#define OPTION_NO_USAGE                0x10
 \f
 struct argp;                   /* fwd declare this type */
 struct argp_state;             /* " */
 struct argp_child;             /* " */
 
 /* The type of a pointer to an argp parsing function.  */
-typedef error_t (*argp_parser_t)(int key, char *arg, struct argp_state *state);
+typedef error_t (*argp_parser_t) (int key, char *arg,
+                                 struct argp_state *state);
 
 /* What to return for unrecognized keys.  For special ARGP_KEY_ keys, such
    returns will simply be ignored.  For user keys, this error will be turned
@@ -120,12 +133,21 @@ typedef error_t (*argp_parser_t)(int key, char *arg, struct argp_state *state);
 /* Special values for the KEY argument to an argument parsing function.
    ARGP_ERR_UNKNOWN should be returned if they aren't understood.
 
-   The sequence of keys to parser calls is either (where opt is a user key):
-       ARGP_KEY_INIT (opt | ARGP_KEY_ARG)... ARGP_KEY_END
-   or  ARGP_KEY_INIT opt... ARGP_KEY_NO_ARGS ARGP_KEY_END
+   The sequence of keys to a parsing function is either (where each
+   uppercased word should be prefixed by `ARGP_KEY_' and opt is a user key):
+
+       INIT opt... NO_ARGS END SUCCESS  -- No non-option arguments at all
+   or  INIT (opt | ARG)... END SUCCESS  -- All non-option args parsed
+   or  INIT (opt | ARG)... SUCCESS      -- Some non-option arg unrecognized
+
+   The third case is where every parser returned ARGP_KEY_UNKNOWN for an
+   argument, in which case parsing stops at that argument (returning the
+   unparsed arguments to the caller of argp_parse if requested, or stopping
+   with an error message if not).
 
-   If an error occurs, then the parser is called with ARGP_KEY_ERR, and no
-   other calls are made.  */
+   If an error occurs (either detected by argp, or because the parsing
+   function returned an error value), then the parser is called with
+   ARGP_KEY_ERROR, and no further calls are made.  */
 
 /* This is not an option at all, but rather a command line argument.  If a
    parser receiving this key returns success, the fact is recorded, and the
@@ -135,6 +157,12 @@ typedef error_t (*argp_parser_t)(int key, char *arg, struct argp_state *state);
    actually modify the argument (perhaps into an option), and have it
    processed again.  */
 #define ARGP_KEY_ARG           0
+/* There are remaining arguments not parsed by any parser, which may be found
+   starting at (STATE->argv + STATE->next).  If success is returned, but
+   STATE->next left untouched, it's assumed that all arguments were consume,
+   otherwise, the parser should adjust STATE->next to reflect any arguments
+   consumed.  */
+#define ARGP_KEY_ARGS          0x1000006
 /* There are no more command line arguments at all.  */
 #define ARGP_KEY_END           0x1000001
 /* Because it's common to want to do some special processing if there aren't
@@ -147,19 +175,20 @@ typedef error_t (*argp_parser_t)(int key, char *arg, struct argp_state *state);
    element of the CHILD_INPUT field, if any, in the state structure is
    copied to each child's state to be the initial value of the INPUT field.  */
 #define ARGP_KEY_INIT          0x1000003
+/* Use after all other keys, including SUCCESS & END.  */
+#define ARGP_KEY_FINI          0x1000007
 /* Passed in when parsing has successfully been completed (even if there are
    still arguments remaining).  */
 #define ARGP_KEY_SUCCESS       0x1000004
-/* Passed in if an error occurs (in which case a call with ARGP_KEY_SUCCESS is
-   never made, so any cleanup must be done here).  */
+/* Passed in if an error occurs.  */
 #define ARGP_KEY_ERROR         0x1000005
 
-/* An argp structure contains a set of getopt options declarations, a
-   function to deal with getting one, and an optional pointer to another
-   argp structure.  When actually parsing options, getopt is called with
-   the union of all the argp structures chained together through their
-   CHILD pointers, with conflicts being resolved in favor of the first
-   occurance in the chain.  */
+/* An argp structure contains a set of options declarations, a function to
+   deal with parsing one, documentation string, a possible vector of child
+   argp's, and perhaps a function to filter help output.  When actually
+   parsing options, getopt is called with the union of all the argp
+   structures chained together through their CHILD pointers, with conflicts
+   being resolved in favor of the first occurrence in the chain.  */
 struct argp
 {
   /* An array of argp_option structures, terminated by an entry with both
@@ -194,7 +223,35 @@ struct argp
      their own argp structure, which you want to use in conjunction with your
      own.  */
   __const struct argp_child *children;
+
+  /* If non-zero, this should be a function to filter the output of help
+     messages.  KEY is either a key from an option, in which case TEXT is
+     that option's help text, or a special key from the ARGP_KEY_HELP_
+     defines, below, describing which other help text TEXT is.  The function
+     should return either TEXT, if it should be used as-is, a replacement
+     string, which should be malloced, and will be freed by argp, or NULL,
+     meaning `print nothing'.  The value for TEXT is *after* any translation
+     has been done, so if any of the replacement text also needs translation,
+     that should be done by the filter function.  INPUT is either the input
+     supplied to argp_parse, or NULL, if argp_help was called directly.  */
+  char *(*help_filter) (int __key, __const char *__text, void *__input);
+
+  /* If non-zero the strings used in the argp library are translated using
+     the domain described by this string.  Otherwise the currently installed
+     default domain is used.  */
+  const char *argp_domain;
 };
+
+/* Possible KEY arguments to a help filter function.  */
+#define ARGP_KEY_HELP_PRE_DOC  0x2000001 /* Help text preceeding options. */
+#define ARGP_KEY_HELP_POST_DOC 0x2000002 /* Help text following options. */
+#define ARGP_KEY_HELP_HEADER   0x2000003 /* Option header string. */
+#define ARGP_KEY_HELP_EXTRA    0x2000004 /* After all other documentation;
+                                            TEXT is NULL for this key.  */
+/* Explanatory note emitted when duplicate option arguments have been
+   suppressed.  */
+#define ARGP_KEY_HELP_DUP_ARGS_NOTE 0x2000005
+#define ARGP_KEY_HELP_ARGS_DOC 0x2000006 /* Argument doc string.  */
 \f
 /* When an argp has a non-zero CHILDREN field, it should point to a vector of
    argp_child structures, each of which describes a subsidiary argp.  */
@@ -226,7 +283,7 @@ struct argp_child
 struct argp_state
 {
   /* The top level ARGP being parsed.  */
-  __const struct argp *argp;
+  __const struct argp *root_argp;
 
   /* The argument vector being parsed.  May be modified.  */
   int argc;
@@ -265,6 +322,8 @@ struct argp_state
   /* Streams used when argp prints something.  */
   FILE *err_stream;            /* For errors; initialized to stderr. */
   FILE *out_stream;            /* For information; initialized to stdout. */
+
+  void *pstate;                        /* Private, for use by argp.  */
 };
 \f
 /* Flags for argp_parse (note that the defaults are those that are
@@ -318,35 +377,43 @@ struct argp_state
    routine returned a non-zero value, it is returned; otherwise 0 is
    returned.  This function may also call exit unless the ARGP_NO_HELP flag
    is set.  INPUT is a pointer to a value to be passed in to the parser.  */
-error_t argp_parse __P ((__const struct argp *__argp,
-                        int __argc, char **__argv, unsigned __flags,
-                        int *__arg_index, void *__input));
-error_t __argp_parse __P ((__const struct argp *__argp,
-                          int __argc, char **__argv, unsigned __flags,
-                          int *__arg_index, void *__input));
+extern error_t argp_parse (__const struct argp *__restrict __argp,
+                          int __argc, char **__restrict __argv,
+                          unsigned __flags, int *__restrict __arg_index,
+                          void *__restrict __input) __THROW;
+extern error_t __argp_parse (__const struct argp *__restrict __argp,
+                            int __argc, char **__restrict __argv,
+                            unsigned __flags, int *__restrict __arg_index,
+                            void *__restrict __input) __THROW;
 \f
 /* Global variables.  */
 
 /* If defined or set by the user program to a non-zero value, then a default
    option --version is added (unless the ARGP_NO_HELP flag is used), which
-   will print this this string followed by a newline and exit (unless the
+   will print this string followed by a newline and exit (unless the
    ARGP_NO_EXIT flag is used).  Overridden by ARGP_PROGRAM_VERSION_HOOK.  */
-extern char *argp_program_version;
+extern __const char *argp_program_version;
 
 /* If defined or set by the user program to a non-zero value, then a default
    option --version is added (unless the ARGP_NO_HELP flag is used), which
    calls this function with a stream to print the version to and a pointer to
    the current parsing state, and then exits (unless the ARGP_NO_EXIT flag is
    used).  This variable takes precedent over ARGP_PROGRAM_VERSION.  */
-extern void (*argp_program_version_hook) __P ((FILE *__stream,
-                                              struct argp_state *__state));
+extern void (*argp_program_version_hook) (FILE *__restrict __stream,
+                                         struct argp_state *__restrict
+                                         __state);
 
 /* If defined or set by the user program, it should point to string that is
    the bug-reporting address for the program.  It will be printed by
    argp_help if the ARGP_HELP_BUG_ADDR flag is set (as it is by various
    standard help messages), embedded in a sentence that says something like
    `Report bugs to ADDR.'.  */
-extern char *argp_program_bug_address;
+extern __const char *argp_program_bug_address;
+
+/* The exit status that argp will use when exiting due to a parsing error.
+   If not defined or set by the user program, this defaults to EX_USAGE from
+   <sysexits.h>.  */
+extern error_t argp_err_exit_status;
 \f
 /* Flags for argp_help.  */
 #define ARGP_HELP_USAGE                0x01 /* a Usage: message. */
@@ -379,10 +446,12 @@ extern char *argp_program_bug_address;
 
 /* Output a usage message for ARGP to STREAM.  FLAGS are from the set
    ARGP_HELP_*.  */
-extern void argp_help __P ((__const struct argp *__argp, FILE *__stream,
-                           unsigned __flags, char *__name));
-extern void __argp_help __P ((__const struct argp *__argp, FILE *__stream,
-                             unsigned __flags, char *__name));
+extern void argp_help (__const struct argp *__restrict __argp,
+                      FILE *__restrict __stream,
+                      unsigned __flags, char *__restrict __name) __THROW;
+extern void __argp_help (__const struct argp *__restrict __argp,
+                        FILE *__restrict __stream, unsigned __flags,
+                        char *__name) __THROW;
 \f
 /* The following routines are intended to be called from within an argp
    parsing routine (thus taking an argp_state structure as the first
@@ -394,21 +463,25 @@ extern void __argp_help __P ((__const struct argp *__argp, FILE *__stream,
 
 /* Output, if appropriate, a usage message for STATE to STREAM.  FLAGS are
    from the set ARGP_HELP_*.  */
-extern void argp_state_help __P ((struct argp_state *__state, FILE *__stream,
-                                 unsigned __flags));
-extern void __argp_state_help __P ((struct argp_state *__state, FILE *__stream,
-                                   unsigned __flags));
+extern void argp_state_help (__const struct argp_state *__restrict __state,
+                            FILE *__restrict __stream,
+                            unsigned int __flags) __THROW;
+extern void __argp_state_help (__const struct argp_state *__restrict __state,
+                              FILE *__restrict __stream,
+                              unsigned int __flags) __THROW;
 
 /* Possibly output the standard usage message for ARGP to stderr and exit.  */
-extern void argp_usage __P ((struct argp_state *__state));
-extern void __argp_usage __P ((struct argp_state *__state));
+extern void argp_usage (__const struct argp_state *__state) __THROW;
+extern void __argp_usage (__const struct argp_state *__state) __THROW;
 
 /* If appropriate, print the printf string FMT and following args, preceded
    by the program name and `:', to stderr, and followed by a `Try ... --help'
    message, then exit (1).  */
-void argp_error __P ((struct argp_state *__state, __const char *__fmt, ...))
+extern void argp_error (__const struct argp_state *__restrict __state,
+                       __const char *__restrict __fmt, ...) __THROW
      __attribute__ ((__format__ (__printf__, 2, 3)));
-void __argp_error __P ((struct argp_state *__state, __const char *__fmt, ...))
+extern void __argp_error (__const struct argp_state *__restrict __state,
+                         __const char *__restrict __fmt, ...) __THROW
      __attribute__ ((__format__ (__printf__, 2, 3)));
 
 /* Similar to the standard gnu error-reporting function error(), but will
@@ -419,43 +492,54 @@ void __argp_error __P ((struct argp_state *__state, __const char *__fmt, ...))
    difference between this function and argp_error is that the latter is for
    *parsing errors*, and the former is for other problems that occur during
    parsing but don't reflect a (syntactic) problem with the input.  */
-void argp_failure __P ((struct argp_state *__state,
-                       int __status, int __errnum, __const char *__fmt, ...))
+extern void argp_failure (__const struct argp_state *__restrict __state,
+                         int __status, int __errnum,
+                         __const char *__restrict __fmt, ...) __THROW
      __attribute__ ((__format__ (__printf__, 4, 5)));
-void __argp_failure __P ((struct argp_state *__state,
-                         int __status, int __errnum, __const char *__fmt, ...))
+extern void __argp_failure (__const struct argp_state *__restrict __state,
+                           int __status, int __errnum,
+                           __const char *__restrict __fmt, ...) __THROW
      __attribute__ ((__format__ (__printf__, 4, 5)));
 
 /* Returns true if the option OPT is a valid short option.  */
-extern int _option_is_short __P ((__const struct argp_option *__opt));
-extern int __option_is_short __P ((__const struct argp_option *__opt));
+extern int _option_is_short (__const struct argp_option *__opt) __THROW;
+extern int __option_is_short (__const struct argp_option *__opt) __THROW;
 
 /* Returns true if the option OPT is in fact the last (unused) entry in an
    options array.  */
-extern int _option_is_end __P ((__const struct argp_option *__opt));
-extern int __option_is_end __P ((__const struct argp_option *__opt));
+extern int _option_is_end (__const struct argp_option *__opt) __THROW;
+extern int __option_is_end (__const struct argp_option *__opt) __THROW;
+
+/* Return the input field for ARGP in the parser corresponding to STATE; used
+   by the help routines.  */
+extern void *_argp_input (__const struct argp *__restrict __argp,
+                         __const struct argp_state *__restrict __state)
+     __THROW;
+extern void *__argp_input (__const struct argp *__restrict __argp,
+                          __const struct argp_state *__restrict __state)
+     __THROW;
 \f
-#ifdef __OPTIMIZE__
+#ifdef __USE_EXTERN_INLINES
 
-#if !_LIBC
-# define __argp_usage argp_usage
-# define __argp_state_help argp_state_help
-# define __option_is_short _option_is_short
-# define __option_is_end _option_is_end
-#endif
+# if !_LIBC
+#  define __argp_usage argp_usage
+#  define __argp_state_help argp_state_help
+#  define __option_is_short _option_is_short
+#  define __option_is_end _option_is_end
+# endif
 
-#ifndef ARGP_EI
-# define ARGP_EI extern inline
-#endif
+# ifndef ARGP_EI
+#  define ARGP_EI extern __inline__
+# endif
 
 ARGP_EI void
-__argp_usage (struct argp_state *__state)
+__argp_usage (__const struct argp_state *__state) __THROW
 {
   __argp_state_help (__state, stderr, ARGP_HELP_STD_USAGE);
 }
 
 ARGP_EI int
-__option_is_short (__const struct argp_option *__opt)
+__option_is_short (__const struct argp_option *__opt) __THROW
 {
   if (__opt->flags & OPTION_DOC)
     return 0;
@@ -467,22 +551,21 @@ __option_is_short (__const struct argp_option *__opt)
 }
 
 ARGP_EI int
-__option_is_end (__const struct argp_option *__opt)
+__option_is_end (__const struct argp_option *__opt) __THROW
 {
   return !__opt->key && !__opt->name && !__opt->doc && !__opt->group;
 }
 
-#if !_LIBC
-# undef __argp_usage
-# undef __argp_state_help
-# undef __option_is_short
-# undef __option_is_end
-#endif
-
-#endif /* __OPTIMIZE__ */
+# if !_LIBC
+#  undef __argp_usage
+#  undef __argp_state_help
+#  undef __option_is_short
+#  undef __option_is_end
+# endif
+#endif /* Use extern inlines.  */
 
 #ifdef  __cplusplus
 }
 #endif
 
-#endif /* __ARGP_H__ */
+#endif /* argp.h */