OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * This library lets you define parsers for parsing raw command-line arguments | 6 * This library lets you define parsers for parsing raw command-line arguments |
7 * into a set of options and values using [GNU][] and [POSIX][] style options. | 7 * into a set of options and values using [GNU][] and [POSIX][] style options. |
8 * | 8 * |
9 * ## Defining options ## | 9 * ## Defining options ## |
10 * | 10 * |
(...skipping 23 matching lines...) Expand all Loading... |
34 * They may also specify a default value. The default value will be used if the | 34 * They may also specify a default value. The default value will be used if the |
35 * option isn't provided: | 35 * option isn't provided: |
36 * | 36 * |
37 * parser.addOption('mode', defaultsTo: 'debug'); | 37 * parser.addOption('mode', defaultsTo: 'debug'); |
38 * parser.addFlag('verbose', defaultsTo: false); | 38 * parser.addFlag('verbose', defaultsTo: false); |
39 * | 39 * |
40 * The default value for non-flag options can be any [String]. For flags, it | 40 * The default value for non-flag options can be any [String]. For flags, it |
41 * must be a [bool]. | 41 * must be a [bool]. |
42 * | 42 * |
43 * To validate non-flag options, you may provide an allowed set of values. When | 43 * To validate non-flag options, you may provide an allowed set of values. When |
44 * you do, it will throw an [ArgFormatException] when you parse the arguments | 44 * you do, it will throw a [FormatException] when you parse the arguments if |
45 * if the value for an option is not in the allowed set: | 45 * the value for an option is not in the allowed set: |
46 * | 46 * |
47 * parser.addOption('mode', allowed: ['debug', 'release']); | 47 * parser.addOption('mode', allowed: ['debug', 'release']); |
48 * | 48 * |
49 * You can provide a callback when you define an option. When you later parse | 49 * You can provide a callback when you define an option. When you later parse |
50 * a set of arguments, the callback for that option will be invoked with the | 50 * a set of arguments, the callback for that option will be invoked with the |
51 * value provided for it: | 51 * value provided for it: |
52 * | 52 * |
53 * parser.addOption('mode', callback: (mode) => print('Got mode $mode)); | 53 * parser.addOption('mode', callback: (mode) => print('Got mode $mode)); |
54 * parser.addFlag('verbose', callback: (verbose) { | 54 * parser.addFlag('verbose', callback: (verbose) { |
55 * if (verbose) print('Verbose'); | 55 * if (verbose) print('Verbose'); |
(...skipping 237 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
293 | 293 |
294 /** | 294 /** |
295 * Generates a string displaying usage information for the defined options. | 295 * Generates a string displaying usage information for the defined options. |
296 * This is basically the help text shown on the command line. | 296 * This is basically the help text shown on the command line. |
297 */ | 297 */ |
298 String getUsage() { | 298 String getUsage() { |
299 return new _Usage(this).generate(); | 299 return new _Usage(this).generate(); |
300 } | 300 } |
301 | 301 |
302 /** | 302 /** |
303 * Called during parsing to validate the arguments. Throws an | 303 * Called during parsing to validate the arguments. Throws a |
304 * [ArgFormatException] if [condition] is `false`. | 304 * [FormatException] if [condition] is `false`. |
305 */ | 305 */ |
306 _validate(bool condition, String message) { | 306 _validate(bool condition, String message) { |
307 if (!condition) throw new ArgFormatException(message); | 307 if (!condition) throw new FormatException(message); |
308 } | 308 } |
309 | 309 |
310 /** Validates and stores [value] as the value for [option]. */ | 310 /** Validates and stores [value] as the value for [option]. */ |
311 _setOption(Map results, _Option option, value) { | 311 _setOption(Map results, _Option option, value) { |
312 // See if it's one of the allowed values. | 312 // See if it's one of the allowed values. |
313 if (option.allowed != null) { | 313 if (option.allowed != null) { |
314 _validate(option.allowed.some((allow) => allow == value), | 314 _validate(option.allowed.some((allow) => allow == value), |
315 '"$value" is not an allowed value for option "${option.name}".'); | 315 '"$value" is not an allowed value for option "${option.name}".'); |
316 } | 316 } |
317 | 317 |
(...skipping 162 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
480 operator [](String name) { | 480 operator [](String name) { |
481 if (!_options.containsKey(name)) { | 481 if (!_options.containsKey(name)) { |
482 throw new IllegalArgumentException( | 482 throw new IllegalArgumentException( |
483 'Could not find an option named "$name".'); | 483 'Could not find an option named "$name".'); |
484 } | 484 } |
485 | 485 |
486 return _options[name]; | 486 return _options[name]; |
487 } | 487 } |
488 } | 488 } |
489 | 489 |
490 /** | |
491 * Exception thrown by [ArgParser.parse()] when the argument list isn't valid. | |
492 */ | |
493 class ArgFormatException implements Exception { | |
494 final String message; | |
495 const ArgFormatException(this.message); | |
496 } | |
497 | |
498 class _Option { | 490 class _Option { |
499 final String name; | 491 final String name; |
500 final String abbreviation; | 492 final String abbreviation; |
501 final List allowed; | 493 final List allowed; |
502 final defaultValue; | 494 final defaultValue; |
503 final Function callback; | 495 final Function callback; |
504 final String help; | 496 final String help; |
505 final Map<String, String> allowedHelp; | 497 final Map<String, String> allowedHelp; |
506 final bool isFlag; | 498 final bool isFlag; |
507 final bool negatable; | 499 final bool negatable; |
(...skipping 215 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
723 allowedBuffer.add(allowed); | 715 allowedBuffer.add(allowed); |
724 if (allowed == option.defaultValue) { | 716 if (allowed == option.defaultValue) { |
725 allowedBuffer.add(' (default)'); | 717 allowedBuffer.add(' (default)'); |
726 } | 718 } |
727 first = false; | 719 first = false; |
728 } | 720 } |
729 allowedBuffer.add(']'); | 721 allowedBuffer.add(']'); |
730 return allowedBuffer.toString(); | 722 return allowedBuffer.toString(); |
731 } | 723 } |
732 } | 724 } |
OLD | NEW |