diff options
author | Akim Demaille <akim.demaille@gmail.com> | 2019-04-30 08:01:14 +0200 |
---|---|---|
committer | Akim Demaille <akim.demaille@gmail.com> | 2019-06-21 18:35:01 +0200 |
commit | 5d00a2ec62270ded0438b5641a97b9ea0a1cd159 (patch) | |
tree | 2fb46e5cb4db958407e0302980d96e1177c67e79 /doc | |
parent | 13644a8180a084c4c682d54f27a2eaab01a92d7f (diff) | |
download | gnulib-5d00a2ec62270ded0438b5641a97b9ea0a1cd159.tar.gz |
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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/argmatch.texi | 137 | ||||
-rw-r--r-- | doc/gnulib.texi | 3 |
2 files changed, 140 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 diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 2ea18ad884..067e6045c0 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -6636,6 +6636,7 @@ to POSIX that it can be treated like any other Unix-like platform. * Closed standard fds:: * Container data types:: * String Functions in C Locale:: +* Recognizing Option Arguments:: * Quoting:: * progname and getprogname:: * gcd:: @@ -6674,6 +6675,8 @@ to POSIX that it can be treated like any other Unix-like platform. @include c-locale.texi +@include argmatch.texi + @include quote.texi @include progname.texi |