| OLD | NEW |
| 1 // Copyright (c) 2014, 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.command_runner; | 5 library args.command_runner; |
| 6 | 6 |
| 7 import 'dart:async'; | 7 import 'dart:async'; |
| 8 import 'dart:collection'; | 8 import 'dart:collection'; |
| 9 import 'dart:math' as math; | 9 import 'dart:math' as math; |
| 10 | 10 |
| (...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 54 | 54 |
| 55 ${_getCommandUsage(_commands)} | 55 ${_getCommandUsage(_commands)} |
| 56 | 56 |
| 57 Run "$executableName help <command>" for more information about a command.'''; | 57 Run "$executableName help <command>" for more information about a command.'''; |
| 58 | 58 |
| 59 if (usageFooter != null) usage += "\n$usageFooter"; | 59 if (usageFooter != null) usage += "\n$usageFooter"; |
| 60 return usage; | 60 return usage; |
| 61 } | 61 } |
| 62 | 62 |
| 63 /// An unmodifiable view of all top-level commands defined for this runner. | 63 /// An unmodifiable view of all top-level commands defined for this runner. |
| 64 Map<String, Command> get commands => | 64 Map<String, Command> get commands => new UnmodifiableMapView(_commands); |
| 65 new UnmodifiableMapView(_commands); | |
| 66 final _commands = new Map<String, Command>(); | 65 final _commands = new Map<String, Command>(); |
| 67 | 66 |
| 68 /// The top-level argument parser. | 67 /// The top-level argument parser. |
| 69 /// | 68 /// |
| 70 /// Global options should be registered with this parser; they'll end up | 69 /// Global options should be registered with this parser; they'll end up |
| 71 /// available via [Command.globalResults]. Commands should be registered with | 70 /// available via [Command.globalResults]. Commands should be registered with |
| 72 /// [addCommand] rather than directly on the parser. | 71 /// [addCommand] rather than directly on the parser. |
| 73 final argParser = new ArgParser(); | 72 final argParser = new ArgParser(); |
| 74 | 73 |
| 75 CommandRunner(this.executableName, this.description) { | 74 CommandRunner(this.executableName, this.description) { |
| 76 argParser.addFlag('help', abbr: 'h', negatable: false, | 75 argParser.addFlag('help', |
| 77 help: 'Print this usage information.'); | 76 abbr: 'h', negatable: false, help: 'Print this usage information.'); |
| 78 addCommand(new HelpCommand()); | 77 addCommand(new HelpCommand()); |
| 79 } | 78 } |
| 80 | 79 |
| 81 /// Prints the usage information for this runner. | 80 /// Prints the usage information for this runner. |
| 82 /// | 81 /// |
| 83 /// This is called internally by [run] and can be overridden by subclasses to | 82 /// This is called internally by [run] and can be overridden by subclasses to |
| 84 /// control how output is displayed or integrate with a logging system. | 83 /// control how output is displayed or integrate with a logging system. |
| 85 void printUsage() => print(usage); | 84 void printUsage() => print(usage); |
| 86 | 85 |
| 87 /// Throws a [UsageException] with [message]. | 86 /// Throws a [UsageException] with [message]. |
| (...skipping 111 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 199 /// A single-line template for how to invoke this command (e.g. `"pub get | 198 /// A single-line template for how to invoke this command (e.g. `"pub get |
| 200 /// [package]"`). | 199 /// [package]"`). |
| 201 String get invocation { | 200 String get invocation { |
| 202 var parents = [name]; | 201 var parents = [name]; |
| 203 for (var command = parent; command != null; command = command.parent) { | 202 for (var command = parent; command != null; command = command.parent) { |
| 204 parents.add(command.name); | 203 parents.add(command.name); |
| 205 } | 204 } |
| 206 parents.add(runner.executableName); | 205 parents.add(runner.executableName); |
| 207 | 206 |
| 208 var invocation = parents.reversed.join(" "); | 207 var invocation = parents.reversed.join(" "); |
| 209 return _subcommands.isNotEmpty ? | 208 return _subcommands.isNotEmpty |
| 210 "$invocation <subcommand> [arguments]" : | 209 ? "$invocation <subcommand> [arguments]" |
| 211 "$invocation [arguments]"; | 210 : "$invocation [arguments]"; |
| 212 } | 211 } |
| 213 | 212 |
| 214 /// The command's parent command, if this is a subcommand. | 213 /// The command's parent command, if this is a subcommand. |
| 215 /// | 214 /// |
| 216 /// This will be `null` until [Command.addSubcommmand] has been called with | 215 /// This will be `null` until [Command.addSubcommmand] has been called with |
| 217 /// this command. | 216 /// this command. |
| 218 Command get parent => _parent; | 217 Command get parent => _parent; |
| 219 Command _parent; | 218 Command _parent; |
| 220 | 219 |
| 221 /// The command runner for this command. | 220 /// The command runner for this command. |
| (...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 256 | 255 |
| 257 /// An optional footer for [usage]. | 256 /// An optional footer for [usage]. |
| 258 /// | 257 /// |
| 259 /// If a subclass overrides this to return a string, it will automatically be | 258 /// If a subclass overrides this to return a string, it will automatically be |
| 260 /// added to the end of [usage]. | 259 /// added to the end of [usage]. |
| 261 final String usageFooter = null; | 260 final String usageFooter = null; |
| 262 | 261 |
| 263 /// Returns [usage] with [description] removed from the beginning. | 262 /// Returns [usage] with [description] removed from the beginning. |
| 264 String get _usageWithoutDescription { | 263 String get _usageWithoutDescription { |
| 265 var buffer = new StringBuffer() | 264 var buffer = new StringBuffer() |
| 266 ..writeln('Usage: $invocation') | 265 ..writeln('Usage: $invocation') |
| 267 ..writeln(argParser.usage); | 266 ..writeln(argParser.usage); |
| 268 | 267 |
| 269 if (_subcommands.isNotEmpty) { | 268 if (_subcommands.isNotEmpty) { |
| 270 buffer.writeln(); | 269 buffer.writeln(); |
| 271 buffer.writeln(_getCommandUsage(_subcommands, isSubcommand: true)); | 270 buffer.writeln(_getCommandUsage(_subcommands, isSubcommand: true)); |
| 272 } | 271 } |
| 273 | 272 |
| 274 buffer.writeln(); | 273 buffer.writeln(); |
| 275 buffer.write('Run "${runner.executableName} help" to see global options.'); | 274 buffer.write('Run "${runner.executableName} help" to see global options.'); |
| 276 | 275 |
| 277 if (usageFooter != null) { | 276 if (usageFooter != null) { |
| 278 buffer.writeln(); | 277 buffer.writeln(); |
| 279 buffer.write(usageFooter); | 278 buffer.write(usageFooter); |
| 280 } | 279 } |
| 281 | 280 |
| 282 return buffer.toString(); | 281 return buffer.toString(); |
| 283 } | 282 } |
| 284 | 283 |
| 285 /// An unmodifiable view of all sublevel commands of this command. | 284 /// An unmodifiable view of all sublevel commands of this command. |
| 286 Map<String, Command> get subcommands => | 285 Map<String, Command> get subcommands => new UnmodifiableMapView(_subcommands); |
| 287 new UnmodifiableMapView(_subcommands); | |
| 288 final _subcommands = new Map<String, Command>(); | 286 final _subcommands = new Map<String, Command>(); |
| 289 | 287 |
| 290 /// Whether or not this command should be hidden from help listings. | 288 /// Whether or not this command should be hidden from help listings. |
| 291 /// | 289 /// |
| 292 /// This is intended to be overridden by commands that want to mark themselves | 290 /// This is intended to be overridden by commands that want to mark themselves |
| 293 /// hidden. | 291 /// hidden. |
| 294 /// | 292 /// |
| 295 /// By default, leaf commands are always visible. Branch commands are visible | 293 /// By default, leaf commands are always visible. Branch commands are visible |
| 296 /// as long as any of their leaf commands are visible. | 294 /// as long as any of their leaf commands are visible. |
| 297 bool get hidden { | 295 bool get hidden { |
| (...skipping 16 matching lines...) Expand all Loading... |
| 314 | 312 |
| 315 /// Alternate names for this command. | 313 /// Alternate names for this command. |
| 316 /// | 314 /// |
| 317 /// These names won't be used in the documentation, but they will work when | 315 /// These names won't be used in the documentation, but they will work when |
| 318 /// invoked on the command line. | 316 /// invoked on the command line. |
| 319 /// | 317 /// |
| 320 /// This is intended to be overridden. | 318 /// This is intended to be overridden. |
| 321 final aliases = const <String>[]; | 319 final aliases = const <String>[]; |
| 322 | 320 |
| 323 Command() { | 321 Command() { |
| 324 argParser.addFlag('help', abbr: 'h', negatable: false, | 322 argParser.addFlag('help', |
| 325 help: 'Print this usage information.'); | 323 abbr: 'h', negatable: false, help: 'Print this usage information.'); |
| 326 } | 324 } |
| 327 | 325 |
| 328 /// Runs this command. | 326 /// Runs this command. |
| 329 /// | 327 /// |
| 330 /// If this returns a [Future], [CommandRunner.run] won't complete until the | 328 /// If this returns a [Future], [CommandRunner.run] won't complete until the |
| 331 /// returned [Future] does. Otherwise, the return value is ignored. | 329 /// returned [Future] does. Otherwise, the return value is ignored. |
| 332 run() { | 330 run() { |
| 333 throw new UnimplementedError("Leaf command $this must implement run()."); | 331 throw new UnimplementedError("Leaf command $this must implement run()."); |
| 334 } | 332 } |
| 335 | 333 |
| (...skipping 18 matching lines...) Expand all Loading... |
| 354 throw new UsageException(message, _usageWithoutDescription); | 352 throw new UsageException(message, _usageWithoutDescription); |
| 355 } | 353 } |
| 356 | 354 |
| 357 /// Returns a string representation of [commands] fit for use in a usage string. | 355 /// Returns a string representation of [commands] fit for use in a usage string. |
| 358 /// | 356 /// |
| 359 /// [isSubcommand] indicates whether the commands should be called "commands" or | 357 /// [isSubcommand] indicates whether the commands should be called "commands" or |
| 360 /// "subcommands". | 358 /// "subcommands". |
| 361 String _getCommandUsage(Map<String, Command> commands, | 359 String _getCommandUsage(Map<String, Command> commands, |
| 362 {bool isSubcommand: false}) { | 360 {bool isSubcommand: false}) { |
| 363 // Don't include aliases. | 361 // Don't include aliases. |
| 364 var names = commands.keys | 362 var names = |
| 365 .where((name) => !commands[name].aliases.contains(name)); | 363 commands.keys.where((name) => !commands[name].aliases.contains(name)); |
| 366 | 364 |
| 367 // Filter out hidden ones, unless they are all hidden. | 365 // Filter out hidden ones, unless they are all hidden. |
| 368 var visible = names.where((name) => !commands[name].hidden); | 366 var visible = names.where((name) => !commands[name].hidden); |
| 369 if (visible.isNotEmpty) names = visible; | 367 if (visible.isNotEmpty) names = visible; |
| 370 | 368 |
| 371 // Show the commands alphabetically. | 369 // Show the commands alphabetically. |
| 372 names = names.toList()..sort(); | 370 names = names.toList()..sort(); |
| 373 var length = names.map((name) => name.length).reduce(math.max); | 371 var length = names.map((name) => name.length).reduce(math.max); |
| 374 | 372 |
| 375 var buffer = new StringBuffer( | 373 var buffer = |
| 376 'Available ${isSubcommand ? "sub" : ""}commands:'); | 374 new StringBuffer('Available ${isSubcommand ? "sub" : ""}commands:'); |
| 377 for (var name in names) { | 375 for (var name in names) { |
| 378 buffer.writeln(); | 376 buffer.writeln(); |
| 379 buffer.write(' ${padRight(name, length)} ' | 377 buffer.write(' ${padRight(name, length)} ' |
| 380 '${commands[name].description.split("\n").first}'); | 378 '${commands[name].description.split("\n").first}'); |
| 381 } | 379 } |
| 382 | 380 |
| 383 return buffer.toString(); | 381 return buffer.toString(); |
| 384 } | 382 } |
| OLD | NEW |