| 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 |