Arguments

The main arguments container class.

Constructors

this this(istring app_name, istring short_desc, istring usage, istring long_desc, istring sp, istring lp, char eq): Constructor.

Members

Aliases

exists alias exists = getBool: Convenience alias to get the value of a boolean argument
opCall alias opCall = get: Convenience aliases to access a specific argument instance
opIndex alias opIndex = get: Undocumented in source.

Functions

clear Arguments clear(): Unsets all configured arguments (as if they weren't given at all on the command-line), clears all parameters that may have been assigned to arguments and also clears any parsing errors that may have been associated with any argument(s).
displayErrors void displayErrors(FormatOutput output): Displays any errors that occurred.
displayHelp void displayHelp(FormatOutput output): Displays the full help message for the application.
errors istring errors(): Constructs a string of error messages.
errors Arguments errors(const(istring)[] errors): Replaces the default error messages with the given string. Note that arguments are passed to the formatter in the following order, and these should be indexed appropriately by each of the error messages (see the 'errmsg' variable for the format string):
get Argument get(char name): Gets a reference to an argument, creating a new instance if necessary.
get Argument get(cstring name): Gets a reference to an argument, creating a new instance if necessary.
getBool bool getBool(cstring name): Convenience method to check whether an argument is set or not (i.e. whether it was found during parsing of the command-line arguments).
getInt T getInt(cstring name): Convenience method to get the integer value of the parameter assigned to an argument. This is valid only if the argument has been assigned exactly one parameter.
getString istring getString(cstring name): Convenience method to get the string parameter assigned to an argument. This is valid only if the argument has been assigned exactly one parameter.
help Arguments help(void delegate(istring arg, istring help) dg): Exposes the configured help text for each of the configured arguments, via the given delegate. Note that the delegate will be called only for those arguments for which a help text has been configured.
opApply int opApply(int delegate(ref Argument) dg): Enables 'foreach' iteration over the set of configured arguments.
parse bool parse(istring input, bool sloppy): Parses the command-line arguments into a set of Argument instances. The command-line arguments are expected to be passed in a string.
parse bool parse(const(istring)[] input, bool sloppy): Parses the command-line arguments into a set of Argument instances. The command-line arguments are expected to be passed in an array of strings.

Variables

app_name istring app_name;: Application's name to use in help messages.
long_desc istring long_desc;: Long description about the application and how to use it (as a format string).
short_desc istring short_desc;: One line description of what the application does (as a format string).
usage istring usage;: Application's short usage description (as a format string).

Examples

Unit tests

1 auto args = new Arguments;
2 
3 // basic
4 auto x = args['x'];
5 test(args.parse(""));
6 x.required;
7 test(args.parse("") is false);
8 test(args.clear.parse("-x"));
9 test(x.set);
10 
11 // alias
12 x.aliased('X');
13 test(args.clear.parse("-X"));
14 test(x.set);
15 
16 // unexpected arg (with sloppy)
17 test(args.clear.parse("-y") is false);
18 test(args.clear.parse("-y") is false);
19 test(args.clear.parse("-y", true) is false);
20 test(args['y'].set);
21 test(args.clear.parse("-x -y", true));
22 
23 // parameters
24 x.params(0);
25 test(args.clear.parse("-x param"));
26 test(x.assigned.length is 0);
27 test(args(null).assigned.length is 1);
28 x.params(1);
29 test(args.clear.parse("-x=param"));
30 test(x.assigned.length is 1);
31 test(x.assigned[0] == "param");
32 test(args.clear.parse("-x param"));
33 test(x.assigned.length is 1);
34 test(x.assigned[0] == "param");
35 
36 // too many args
37 x.params(1);
38 test(args.clear.parse("-x param1 param2"));
39 test(x.assigned.length is 1);
40 test(x.assigned[0] == "param1");
41 test(args(null).assigned.length is 1);
42 test(args(null).assigned[0] == "param2");
43 
44 // now with default params
45 test(args.clear.parse("param1 param2 -x=blah"));
46 test(args[null].assigned.length is 2);
47 test(args(null).assigned.length is 2);
48 test(x.assigned.length is 1);
49 x.params(0);
50 test(!args.clear.parse("-x=blah"));
51 
52 // args as parameter
53 test(args.clear.parse("- -x"));
54 test(args[null].assigned.length is 1);
55 test(args[null].assigned[0] == "-");
56 
57 // multiple flags, with alias and sloppy
58 test(args.clear.parse("-xy"));
59 test(args.clear.parse("-xyX"));
60 test(x.set);
61 test(args['y'].set);
62 test(args.clear.parse("-xyz") is false);
63 test(args.clear.parse("-xyz", true));
64 auto z = args['z'];
65 test(z.set);
66 
67 // multiple flags with trailing arg
68 test(args.clear.parse("-xyz=10"));
69 test(z.assigned.length is 1);
70 
71 // again, but without sloppy param declaration
72 z.params(0);
73 test(!args.clear.parse("-xyz=10"));
74 test(args.clear.parse("-xzy=10"));
75 test(args('y').assigned.length is 1);
76 test(args('x').assigned.length is 0);
77 test(args('z').assigned.length is 0);
78 
79 // x requires y
80 x.requires('y');
81 test(args.clear.parse("-xy"));
82 test(args.clear.parse("-xz") is false);
83 test!("==")(args.errors(), "argument 'x' requires 'y'\n");
84 
85 // defaults
86 z.defaults("foo");
87 test(args.clear.parse("-xy"));
88 test(z.assigned.length is 1);
89 
90 // long names, with params
91 test(args.clear.parse("-xy --foobar") is false);
92 test(args.clear.parse("-xy --foobar", true));
93 test(args["y"].set && x.set);
94 test(args["foobar"].set);
95 test(args.clear.parse("-xy --foobar=10"));
96 test(args["foobar"].assigned.length is 1);
97 test(args["foobar"].assigned[0] == "10");
98 
99 // smush argument z, but not others
100 z.params;
101 test(args.clear.parse("-xy -zsmush") is false);
102 test(x.set);
103 z.smush;
104 test(args.clear.parse("-xy -zsmush"));
105 test(z.assigned.length is 1);
106 test(z.assigned[0] == "smush");
107 test(x.assigned.length is 0);
108 z.params(0);
109 
110 // conflict x with z
111 x.conflicts(z);
112 test(args.clear.parse("-xyz") is false);
113 
114 // word mode, with prefix elimination
115 args = new Arguments(null, null, null, null, null, null);
116 test(args.clear.parse("foo bar wumpus") is false);
117 test(args.clear.parse("foo bar wumpus wombat", true));
118 test(args("foo").set);
119 test(args("bar").set);
120 test(args("wumpus").set);
121 test(args("wombat").set);
122 
123 // use '/' instead of '-'
124 args = new Arguments(null, null, null, null, "/", "/");
125 test(args.clear.parse("/foo /bar /wumpus") is false);
126 test(args.clear.parse("/foo /bar /wumpus /wombat", true));
127 test(args("foo").set);
128 test(args("bar").set);
129 test(args("wumpus").set);
130 test(args("wombat").set);
131 
132 // use '/' for short and '-' for long
133 args = new Arguments(null, null, null, null, "/", "-");
134 test(args.clear.parse("-foo -bar -wumpus -wombat /abc", true));
135 test(args("foo").set);
136 test(args("bar").set);
137 test(args("wumpus").set);
138 test(args("wombat").set);
139 test(args("a").set);
140 test(args("b").set);
141 test(args("c").set);
142 
143 // "--" makes all subsequent be implicit parameters
144 args = new Arguments;
145 args('f').params(0);
146 test(args.parse("-f -- -bar -wumpus -wombat --abc"));
147 test(args('f').assigned.length is 0);
148 test(args(null).assigned.length is 4);
149 
150 // Confirm arguments are stored in a sorted manner
151 args = new Arguments;
152 test(args.clear.parse("--beta --alpha --delta --echo --charlie", true));
153 size_t index;
154 foreach (arg; args)
155 {
156     switch ( index++ )
157     {
158         case 0: continue;
159         case 1: test("alpha"   == arg.name); continue;
160         case 2: test("beta"    == arg.name); continue;
161         case 3: test("charlie" == arg.name); continue;
162         case 4: test("delta"   == arg.name); continue;
163         case 5: test("echo"    == arg.name); continue;
164         default: test(0);
165     }
166 }
167 
168 // Test that getInt() works as expected
169 args = new Arguments;
170 args("num").params(1);
171 test(args.parse("--num 100"));
172 test(args.getInt!(uint)("num") == 100);
173 
174 args = new Arguments;
175 args("num").params(1);
176 test(args.parse("--num 18446744073709551615"));
177 test(args.getInt!(ulong)("num") == ulong.max);
178 
179 args = new Arguments;
180 args("num").params(1);
181 test(args.getInt!(ulong)("num") == 0);

Arguments

Constructors

Members

Aliases

Functions

Variables

Examples

Meta

Source