argmatch: add support to generate the usage message

* lib/argmatch.c: Move some #includes and gettext support to...
* lib/argmatch.h: here.
(ARGMATCH_DEFINE_GROUP): New macro.
* tests/test-argmatch.c (argmatch_backup_docs, argmatch_backup_args)
(argmatch_backup_group): New.
(CHECK): New.
(main): Check argmatch_backup_value, argmatch_backup_xvalue,
argmatch_backup_argument and argmatch_backup_usage.
* modules/argmatch: We depend on c99.
* doc/argmatch.texi (Recognizing Option Arguments): New.
* doc/gnulib.texi: Use it.

1 files changed, 137 insertions, 0 deletions

diff --git a/doc/argmatch.texi b/doc/argmatch.texi
new file mode 100644
index 0000000000..9222520702
--- /dev/null
+++ b/doc/argmatch.texi
@@ -0,0 +1,137 @@
+@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_docs,
+  argmatch_backup_args,
+  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