| OLD | NEW |
| 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2014, 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 library args; | 5 library args.src.arg_parser; |
| 6 | 6 |
| 7 import 'package:collection/wrappers.dart'; | 7 import 'package:collection/wrappers.dart'; |
| 8 | 8 |
| 9 import 'src/parser.dart'; | 9 import 'arg_results.dart'; |
| 10 import 'src/usage.dart'; | 10 import 'option.dart'; |
| 11 import 'src/options.dart'; | 11 import 'parser.dart'; |
| 12 export 'src/options.dart'; | 12 import 'usage.dart'; |
| 13 | 13 |
| 14 /// A class for taking a list of raw command line arguments and parsing out | 14 /// A class for taking a list of raw command line arguments and parsing out |
| 15 /// options and flags from them. | 15 /// options and flags from them. |
| 16 class ArgParser { | 16 class ArgParser { |
| 17 final Map<String, Option> _options; | 17 final Map<String, Option> _options; |
| 18 final Map<String, ArgParser> _commands; | 18 final Map<String, ArgParser> _commands; |
| 19 | 19 |
| 20 /// The options that have been defined for this parser. | 20 /// The options that have been defined for this parser. |
| 21 final Map<String, Option> options; | 21 final Map<String, Option> options; |
| 22 | 22 |
| (...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 62 return parser; | 62 return parser; |
| 63 } | 63 } |
| 64 | 64 |
| 65 /// Defines a flag. Throws an [ArgumentError] if: | 65 /// Defines a flag. Throws an [ArgumentError] if: |
| 66 /// | 66 /// |
| 67 /// * There is already an option named [name]. | 67 /// * There is already an option named [name]. |
| 68 /// * There is already an option using abbreviation [abbr]. | 68 /// * There is already an option using abbreviation [abbr]. |
| 69 void addFlag(String name, {String abbr, String help, bool defaultsTo: false, | 69 void addFlag(String name, {String abbr, String help, bool defaultsTo: false, |
| 70 bool negatable: true, void callback(bool value), bool hide: false}) { | 70 bool negatable: true, void callback(bool value), bool hide: false}) { |
| 71 _addOption(name, abbr, help, null, null, null, defaultsTo, callback, | 71 _addOption(name, abbr, help, null, null, null, defaultsTo, callback, |
| 72 isFlag: true, negatable: negatable, hide: hide); | 72 OptionType.FLAG, negatable: negatable, hide: hide); |
| 73 } | 73 } |
| 74 | 74 |
| 75 /// Defines a value-taking option. Throws an [ArgumentError] if: | 75 /// Defines a value-taking option. Throws an [ArgumentError] if: |
| 76 /// | 76 /// |
| 77 /// * There is already an option with name [name]. | 77 /// * There is already an option with name [name]. |
| 78 /// * There is already an option using abbreviation [abbr]. | 78 /// * There is already an option using abbreviation [abbr]. |
| 79 void addOption(String name, {String abbr, String help, String valueHelp, | 79 void addOption(String name, {String abbr, String help, String valueHelp, |
| 80 List<String> allowed, Map<String, String> allowedHelp, String defaultsTo, | 80 List<String> allowed, Map<String, String> allowedHelp, String defaultsTo, |
| 81 void callback(value), bool allowMultiple: false, bool hide: false}) { | 81 void callback(value), bool allowMultiple: false, bool hide: false}) { |
| 82 _addOption(name, abbr, help, valueHelp, allowed, allowedHelp, defaultsTo, | 82 _addOption(name, abbr, help, valueHelp, allowed, allowedHelp, defaultsTo, |
| 83 callback, isFlag: false, allowMultiple: allowMultiple, | 83 callback, allowMultiple ? OptionType.MULTIPLE : OptionType.SINGLE, |
| 84 hide: hide); | 84 hide: hide); |
| 85 } | 85 } |
| 86 | 86 |
| 87 void _addOption(String name, String abbr, String help, String valueHelp, | 87 void _addOption(String name, String abbr, String help, String valueHelp, |
| 88 List<String> allowed, Map<String, String> allowedHelp, defaultsTo, | 88 List<String> allowed, Map<String, String> allowedHelp, defaultsTo, |
| 89 void callback(value), {bool isFlag, bool negatable: false, | 89 void callback(value), OptionType type, {bool negatable: false, |
| 90 bool allowMultiple: false, bool hide: false}) { | 90 bool hide: false}) { |
| 91 // Make sure the name isn't in use. | 91 // Make sure the name isn't in use. |
| 92 if (_options.containsKey(name)) { | 92 if (_options.containsKey(name)) { |
| 93 throw new ArgumentError('Duplicate option "$name".'); | 93 throw new ArgumentError('Duplicate option "$name".'); |
| 94 } | 94 } |
| 95 | 95 |
| 96 // Make sure the abbreviation isn't too long or in use. | 96 // Make sure the abbreviation isn't too long or in use. |
| 97 if (abbr != null) { | 97 if (abbr != null) { |
| 98 var existing = findByAbbreviation(abbr); | 98 var existing = findByAbbreviation(abbr); |
| 99 if (existing != null) { | 99 if (existing != null) { |
| 100 throw new ArgumentError( | 100 throw new ArgumentError( |
| 101 'Abbreviation "$abbr" is already used by "${existing.name}".'); | 101 'Abbreviation "$abbr" is already used by "${existing.name}".'); |
| 102 } | 102 } |
| 103 } | 103 } |
| 104 | 104 |
| 105 _options[name] = new Option(name, abbr, help, valueHelp, allowed, | 105 _options[name] = newOption(name, abbr, help, valueHelp, allowed, |
| 106 allowedHelp, defaultsTo, callback, isFlag: isFlag, negatable: negatable, | 106 allowedHelp, defaultsTo, callback, type, negatable: negatable, |
| 107 allowMultiple: allowMultiple, hide: hide); | 107 hide: hide); |
| 108 } | 108 } |
| 109 | 109 |
| 110 /// Parses [args], a list of command-line arguments, matches them against the | 110 /// Parses [args], a list of command-line arguments, matches them against the |
| 111 /// flags and options defined by this parser, and returns the result. | 111 /// flags and options defined by this parser, and returns the result. |
| 112 ArgResults parse(List<String> args) => | 112 ArgResults parse(List<String> args) => |
| 113 new Parser(null, this, args.toList(), null, null).parse(); | 113 new Parser(null, this, args.toList(), null, null).parse(); |
| 114 | 114 |
| 115 /// Generates a string displaying usage information for the defined options. | 115 /// Generates a string displaying usage information for the defined options. |
| 116 /// | 116 /// |
| 117 /// This is basically the help text shown on the command line. | 117 /// This is basically the help text shown on the command line. |
| 118 String getUsage() => new Usage(this).generate(); | 118 String getUsage() => new Usage(this).generate(); |
| 119 | 119 |
| 120 /// Get the default value for an option. Useful after parsing to test if the | 120 /// Get the default value for an option. Useful after parsing to test if the |
| 121 /// user specified something other than the default. | 121 /// user specified something other than the default. |
| 122 getDefault(String option) { | 122 getDefault(String option) { |
| 123 if (!options.containsKey(option)) { | 123 if (!options.containsKey(option)) { |
| 124 throw new ArgumentError('No option named $option'); | 124 throw new ArgumentError('No option named $option'); |
| 125 } | 125 } |
| 126 return options[option].defaultValue; | 126 return options[option].defaultValue; |
| 127 } | 127 } |
| 128 | 128 |
| 129 /// Finds the option whose abbreviation is [abbr], or `null` if no option has | 129 /// Finds the option whose abbreviation is [abbr], or `null` if no option has |
| 130 /// that abbreviation. | 130 /// that abbreviation. |
| 131 Option findByAbbreviation(String abbr) { | 131 Option findByAbbreviation(String abbr) { |
| 132 return options.values.firstWhere((option) => option.abbreviation == abbr, | 132 return options.values.firstWhere((option) => option.abbreviation == abbr, |
| 133 orElse: () => null); | 133 orElse: () => null); |
| 134 } | 134 } |
| 135 } | 135 } |
| 136 | |
| 137 /// The results of parsing a series of command line arguments using | |
| 138 /// [ArgParser.parse()]. | |
| 139 /// | |
| 140 /// Includes the parsed options and any remaining unparsed command line | |
| 141 /// arguments. | |
| 142 class ArgResults { | |
| 143 final Map<String, dynamic> _options; | |
| 144 | |
| 145 /// If these are the results for parsing a command's options, this will be the | |
| 146 /// name of the command. For top-level results, this returns `null`. | |
| 147 final String name; | |
| 148 | |
| 149 /// The command that was selected, or `null` if none was. | |
| 150 /// | |
| 151 /// This will contain the options that were selected for that command. | |
| 152 final ArgResults command; | |
| 153 | |
| 154 /// The remaining command-line arguments that were not parsed as options or | |
| 155 /// flags. | |
| 156 /// | |
| 157 /// If `--` was used to separate the options from the remaining arguments, | |
| 158 /// it will not be included in this list unless parsing stopped before the | |
| 159 /// `--` was reached. | |
| 160 final List<String> rest; | |
| 161 | |
| 162 /// Creates a new [ArgResults]. | |
| 163 ArgResults(this._options, this.name, this.command, List<String> rest) | |
| 164 : this.rest = new UnmodifiableListView(rest); | |
| 165 | |
| 166 /// Gets the parsed command-line option named [name]. | |
| 167 operator [](String name) { | |
| 168 if (!_options.containsKey(name)) { | |
| 169 throw new ArgumentError( | |
| 170 'Could not find an option named "$name".'); | |
| 171 } | |
| 172 | |
| 173 return _options[name]; | |
| 174 } | |
| 175 | |
| 176 /// Get the names of the options as an [Iterable]. | |
| 177 Iterable<String> get options => _options.keys; | |
| 178 } | |
| 179 | |
| OLD | NEW |