1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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_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
|
