OLD | NEW |
1 Parses raw command-line arguments into a set of options and values. | 1 Parses raw command-line arguments into a set of options and values. |
2 | 2 |
3 This library supports [GNU][] and [POSIX][] style options, and it works | 3 This library supports [GNU][] and [POSIX][] style options, and it works |
4 in both server-side and client-side apps. | 4 in both server-side and client-side apps. |
5 | 5 |
6 ## Defining options | 6 ## Defining options |
7 | 7 |
8 First create an [ArgParser][]: | 8 First create an [ArgParser][]: |
9 | 9 |
10 var parser = new ArgParser(); | 10 var parser = new ArgParser(); |
(...skipping 33 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
44 | 44 |
45 ```dart | 45 ```dart |
46 parser.addOption('mode', defaultsTo: 'debug'); | 46 parser.addOption('mode', defaultsTo: 'debug'); |
47 parser.addFlag('verbose', defaultsTo: false); | 47 parser.addFlag('verbose', defaultsTo: false); |
48 ``` | 48 ``` |
49 | 49 |
50 The default value for non-flag options can be any string. For flags, it must | 50 The default value for non-flag options can be any string. For flags, it must |
51 be a `bool`. | 51 be a `bool`. |
52 | 52 |
53 To validate a non-flag option, you can use the `allowed` parameter to provide an | 53 To validate a non-flag option, you can use the `allowed` parameter to provide an |
54 allowed set of values. When you do, the parser throws a [FormatException] if the | 54 allowed set of values. When you do, the parser throws an |
55 value for an option is not in the allowed set. Here's an example of specifying | 55 [`ArgParserException`][ArgParserException] if the value for an option is not in |
56 allowed values: | 56 the allowed set. Here's an example of specifying allowed values: |
| 57 |
| 58 [ArgParserException]: https://www.dartdocs.org/documentation/args/latest/args/Ar
gParserException-class.html |
57 | 59 |
58 ```dart | 60 ```dart |
59 parser.addOption('mode', allowed: ['debug', 'release']); | 61 parser.addOption('mode', allowed: ['debug', 'release']); |
60 ``` | 62 ``` |
61 | 63 |
62 You can use the `callback` parameter to associate a function with an option. | 64 You can use the `callback` parameter to associate a function with an option. |
63 Later, when parsing occurs, the callback function is invoked with the value of | 65 Later, when parsing occurs, the callback function is invoked with the value of |
64 the option: | 66 the option: |
65 | 67 |
66 ```dart | 68 ```dart |
(...skipping 220 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
287 final name = "commit"; | 289 final name = "commit"; |
288 final description = "Record changes to the repository."; | 290 final description = "Record changes to the repository."; |
289 | 291 |
290 CommitCommand() { | 292 CommitCommand() { |
291 // [argParser] is automatically created by the parent class. | 293 // [argParser] is automatically created by the parent class. |
292 argParser.addFlag('all', abbr: 'a'); | 294 argParser.addFlag('all', abbr: 'a'); |
293 } | 295 } |
294 | 296 |
295 // [run] may also return a Future. | 297 // [run] may also return a Future. |
296 void run() { | 298 void run() { |
297 // [options] is set before [run()] is called and contains the options | 299 // [argResults] is set before [run()] is called and contains the options |
298 // passed to this command. | 300 // passed to this command. |
299 print(options['all']); | 301 print(argResults['all']); |
300 } | 302 } |
301 } | 303 } |
302 ``` | 304 ``` |
303 | 305 |
304 Commands can also have subcommands, which are added with [addSubcommand][]. A | 306 Commands can also have subcommands, which are added with [addSubcommand][]. A |
305 command with subcommands can't run its own code, so [run][] doesn't need to be | 307 command with subcommands can't run its own code, so [run][] doesn't need to be |
306 implemented. For example: | 308 implemented. For example: |
307 | 309 |
308 ```dart | 310 ```dart |
309 class StashCommand extends Command { | 311 class StashCommand extends Command { |
310 final String name = "stash"; | 312 final String name = "stash"; |
311 final String description = "Stash changes in the working directory."; | 313 final String description = "Stash changes in the working directory."; |
312 | 314 |
313 StashCommand() { | 315 StashCommand() { |
314 addSubcommand(new StashSaveCommand()); | 316 addSubcommand(new StashSaveCommand()); |
315 addSubcommand(new StashListCommand()); | 317 addSubcommand(new StashListCommand()); |
316 } | 318 } |
317 } | 319 } |
318 ``` | 320 ``` |
319 | 321 |
320 [CommandRunner][] automatically adds a `help` command that displays usage | 322 [CommandRunner][] automatically adds a `help` command that displays usage |
321 information for commands, as well as support for the `--help` flag for all | 323 information for commands, as well as support for the `--help` flag for all |
322 commands. If it encounters an error parsing the arguments or processing a | 324 commands. If it encounters an error parsing the arguments or processing a |
323 command, it throws a [UsageError][]; your `main()` method should catch these and | 325 command, it throws a [UsageException][]; your `main()` method should catch these
and |
324 print them appropriately. For example: | 326 print them appropriately. For example: |
325 | 327 |
326 ```dart | 328 ```dart |
327 runner.run(arguments).catchError((error) { | 329 runner.run(arguments).catchError((error) { |
328 if (error is! UsageError) throw error; | 330 if (error is! UsageException) throw error; |
329 print(error); | 331 print(error); |
330 exit(64); // Exit code 64 indicates a usage error. | 332 exit(64); // Exit code 64 indicates a usage error. |
331 }); | 333 }); |
332 ``` | 334 ``` |
333 | 335 |
334 ## Displaying usage | 336 ## Displaying usage |
335 | 337 |
336 You can automatically generate nice help text, suitable for use as the output of | 338 You can automatically generate nice help text, suitable for use as the output of |
337 `--help`. To display good usage information, you should provide some help text | 339 `--help`. To display good usage information, you should provide some help text |
338 when you create your options. | 340 when you create your options. |
(...skipping 17 matching lines...) Expand all Loading... |
356 by using the `allowedHelp:` parameter: | 358 by using the `allowedHelp:` parameter: |
357 | 359 |
358 ```dart | 360 ```dart |
359 parser.addOption('arch', help: 'The architecture to compile for', | 361 parser.addOption('arch', help: 'The architecture to compile for', |
360 allowedHelp: { | 362 allowedHelp: { |
361 'ia32': 'Intel x86', | 363 'ia32': 'Intel x86', |
362 'arm': 'ARM Holding 32-bit chip' | 364 'arm': 'ARM Holding 32-bit chip' |
363 }); | 365 }); |
364 ``` | 366 ``` |
365 | 367 |
366 To display the help, use the [getUsage()][getUsage] method: | 368 To display the help, use the [usage][usage] getter: |
367 | 369 |
368 ```dart | 370 ```dart |
369 print(parser.getUsage()); | 371 print(parser.usage); |
370 ``` | 372 ``` |
371 | 373 |
372 The resulting string looks something like this: | 374 The resulting string looks something like this: |
373 | 375 |
374 ``` | 376 ``` |
375 --mode The compiler configuration | 377 --mode The compiler configuration |
376 [debug, release] | 378 [debug, release] |
377 | 379 |
378 --out=<path> The output path | 380 --out=<path> The output path |
379 --[no-]verbose Show additional diagnostic info | 381 --[no-]verbose Show additional diagnostic info |
380 --arch The architecture to compile for | 382 --arch The architecture to compile for |
381 [arm] ARM Holding 32-bit chip | 383 [arm] ARM Holding 32-bit chip |
382 [ia32] Intel x86 | 384 [ia32] Intel x86 |
383 ``` | 385 ``` |
384 | 386 |
385 [posix]: http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
#tag_12_02 | 387 [posix]: http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
#tag_12_02 |
386 [gnu]: http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfa
ces | 388 [gnu]: http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfa
ces |
387 [ArgParser]: http://www.dartdocs.org/documentation/args/latest/index.html#args/a
rgs.ArgParser | 389 [ArgParser]: http://www.dartdocs.org/documentation/args/latest/index.html#args/a
rgs.ArgParser |
388 [ArgResults]: http://www.dartdocs.org/documentation/args/latest/index.html#args/
args.ArgResults | 390 [ArgResults]: http://www.dartdocs.org/documentation/args/latest/index.html#args/
args.ArgResults |
389 [CommandRunner]: http://www.dartdocs.org/documentation/args/latest/index.html#ar
gs/args.CommandRunner | 391 [CommandRunner]: http://www.dartdocs.org/documentation/args/latest/index.html#ar
gs/command_runner.CommandRunner |
390 [Command]: http://www.dartdocs.org/documentation/args/latest/index.html#args/arg
s.Command | 392 [Command]: http://www.dartdocs.org/documentation/args/latest/index.html#args/com
mand_runner.Command |
391 [UsageError]: http://www.dartdocs.org/documentation/args/latest/index.html#args/
args.UsageError | 393 [UsageException]: http://www.dartdocs.org/documentation/args/latest/index.html#a
rgs/command_runner.UsageException |
392 [addOption]: http://www.dartdocs.org/documentation/args/latest/index.html#args/a
rgs.ArgParser@id_addOption | 394 [addOption]: http://www.dartdocs.org/documentation/args/latest/index.html#args/a
rgs.ArgParser@id_addOption |
393 [addFlag]: http://www.dartdocs.org/documentation/args/latest/index.html#args/arg
s.ArgParser@id_addFlag | 395 [addFlag]: http://www.dartdocs.org/documentation/args/latest/index.html#args/arg
s.ArgParser@id_addFlag |
394 [parse]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.
ArgParser@id_parse | 396 [parse]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.
ArgParser@id_parse |
395 [rest]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.A
rgResults@id_rest | 397 [rest]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.A
rgResults@id_rest |
396 [addCommand]: http://www.dartdocs.org/documentation/args/latest/index.html#args/
args.ArgParser@id_addCommand | 398 [addCommand]: http://www.dartdocs.org/documentation/args/latest/index.html#args/
args.ArgParser@id_addCommand |
397 [getUsage]: http://www.dartdocs.org/documentation/args/latest/index.html#args/ar
gs.ArgParser@id_getUsage | 399 [getUsage]: http://www.dartdocs.org/documentation/args/latest/index.html#args/ar
gs.ArgParser@id_getUsage |
398 [addSubcommand]: http://www.dartdocs.org/documentation/args/latest/index.html#ar
gs/args.Command@id_addSubcommand | 400 [addSubcommand]: http://www.dartdocs.org/documentation/args/latest/index.html#ar
gs/command_runner.Command@id_addSubcommand |
399 [run]: http://www.dartdocs.org/documentation/args/latest/index.html#args/args.Co
mmand@id_run | 401 [run]: http://www.dartdocs.org/documentation/args/latest/index.html#args/command
_runner.Command@id_run |
OLD | NEW |