kc3-lang/gnulib/doc/argmatch.texi

• Show log

  Commit

• Hash : 96286226
  Author :
  Date : 2019-06-22T08:37:31
  

  argmatch: put all the docs member last.
  
  Reported by Bruno Haible.
  * lib/argmatch.h (argmatch_##Name##_group_type): Put the args
  member before the docs done.
  * doc/argmatch.texi, tests/test-argmatch.c: Adjust.
  

Download

• doc/argmatch.texi

• @node Recognizing Option Arguments
  @section Recognizing Option Arguments
  
  The module @samp{argmatch} provides a simple textual user interface to a
  finite choice.  It is for example well suited to recognize arguments of
  options or values of environment variables that accept a fixed set of valid
  choices.
  
  These choices may be denoted by synonyms, such as `none' and `off' below.
  
  @smallexample
  $ @kbd{my_cp --backup=none foo bar}
  $ @kbd{my_cp --backup=non foo bar}
  $ @kbd{my_cp --backup=no foo bar}
  $ @kbd{my_cp --backup=n foo bar}
  my_cp: ambiguous argument 'n' for 'backup type'
  Valid arguments are:
    - 'no', 'none', 'off'
    - 'numbered', 't', 'newstyle'
    - 'existing', 'nil', 'numbered-existing'
    - 'simple', 'never', 'single'
  Try 'my_cp --help' for more information.
  $ @kbd{my_cp --backup=num foo bar}
  $ @kbd{my_cp --backup=true foo bar}
  my_cp: invalid argument 'true' for 'backup type'
  Valid arguments are:
    - 'no', 'none', 'off'
    - 'numbered', 't', 'newstyle'
    - 'existing', 'nil', 'numbered-existing'
    - 'simple', 'never', 'single'
  Try 'my_cp --help' for more information.
  @end smallexample
  
  To set up @code{argmatch}, first call @samp{ARGMATCH_DEFINE_GROUP
  (@var{name}, @var{type})} with the name of the argmatch group name, and the
  value type.  For instance:
  
  @smallexample
  enum backup_type
  @{
    no_backups,
    simple_backups,
    numbered_existing_backups,
    numbered_backups
  @};
  
  ARGMATCH_DEFINE_GROUP (backup, enum backup_type);
  @end smallexample
  
  @noindent
  This defines a few types and functions named @code{argmatch_@var{name}_*}.
  Introduce the array that defines the mapping from user-input to actual
  value, with a terminator:
  
  @example
  static const argmatch_backup_arg argmatch_backup_args[] =
  @{
    @{ "no",                no_backups @},
    @{ "none",              no_backups @},
    @{ "off",               no_backups @},
    @{ "simple",            simple_backups @},
    @{ "never",             simple_backups @},
    @{ "single",            simple_backups @},
    @{ "existing",          numbered_existing_backups @},
    @{ "nil",               numbered_existing_backups @},
    @{ "numbered-existing", numbered_existing_backups @},
    @{ "numbered",          numbered_backups @},
    @{ "t",                 numbered_backups @},
    @{ "newstyle",          numbered_backups @},
    @{ NULL, no_backups @}
  @};
  @end example
  
  @noindent
  Then introduce the array that defines the values, also with a terminator.
  Document only once per group of synonyms:
  
  @example
  static const argmatch_backup_doc argmatch_backup_docs[] =
  @{
    @{ "no",       N_("never make backups (even if --backup is given)") @},
    @{ "numbered", N_("make numbered backups") @},
    @{ "existing", N_("numbered if numbered backups exist, simple otherwise") @},
    @{ "simple",   N_("always make simple backups") @},
    @{ NULL, NULL @}
  @};
  @end example
  
  @noindent
  Finally, define the argmatch group:
  
  @example
  const argmatch_backup_group_type argmatch_backup_group =
  @{
    argmatch_backup_args,
    argmatch_backup_docs,
    N_("\
  The backup suffix is '~', unless set with --suffix or SIMPLE_BACKUP_SUFFIX.\n\
  The version control method may be selected via the --backup option or through\n\
  the VERSION_CONTROL environment variable.  Here are the values:\n"),
    NULL
  @};
  @end example
  
  @sp 1
  
  To use the argmatch group:
  
  @smallexample
  ptrdiff_t i = argmatch_backup_choice ("--backup", "none");
  // argmatch_backup_group.args[i].arg is "none", so its value
  // is argmatch_backup_group.args[i].val.
  // Return -1 on invalid argument, and -2 on ambiguity.
  
  enum backup_type val = *argmatch_backup_value ("--backup", "none");
  // Returns a pointer to the value, and exit on errors.
  // So argmatch_backup_group.args[i].val == val.
  
  const char *arg = argmatch_backup_argument (&no_backups);
  // arg is "no".
  
  // Print the documentation on stdout.
  argmatch_backup_usage (stdout);
  // Gives:
  //
  // The backup suffix is '~', unless set with --suffix or SIMPLE_BACKUP_SUFFIX.
  // The version control method may be selected via the --backup option or through
  // the VERSION_CONTROL environment variable.  Here are the values:
  //
  //   no, none, off  never make backups (even if --backup is given)
  //   numbered, t, newstyle
  //                  make numbered backups
  //   existing, nil, numbered-existing
  //                  numbered if numbered backups exist, simple otherwise
  //   simple, never, single
  //                  always make simple backups
  @end smallexample
  

Download