Add ability to group commands by category in usage (#202) To enable https://github.com/flutter/flutter/issues/83706 Formatting is loosely based on what `Brew` does, and open to suggestions. Existing tests are unchanged. Example (all displayed commands categorized): <img width="669" alt="Screenshot 2021-07-23 at 16 22 40" src="https://user-images.githubusercontent.com/6655696/126796093-e8652385-c3d7-4600-83b1-76852ab46ea4.png">
diff --git a/CHANGELOG.md b/CHANGELOG.md index 59f7a33..3c2b591 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md
@@ -1,3 +1,7 @@ +## 2.3.0 + +* Add the ability to group commands by category in usage text. + ## 2.2.0 * Suggest similar commands if an unknown command is encountered, when using the
diff --git a/lib/command_runner.dart b/lib/command_runner.dart index ff6da4a..79fa282 100644 --- a/lib/command_runner.dart +++ b/lib/command_runner.dart
@@ -262,6 +262,12 @@ /// This defaults to the first line of [description]. String get summary => description.split('\n').first; + /// The command's category. + /// + /// Displayed in [parent]'s [CommandRunner.usage]. Commands with categories + /// will be grouped together, and displayed after commands without a category. + String get category => ''; + /// A single-line template for how to invoke this command (e.g. `"pub get /// `package`"`). String get invocation { @@ -455,20 +461,36 @@ // Show the commands alphabetically. names = names.toList()..sort(); + + // Group the commands by category. + var commandsByCategory = SplayTreeMap<String, List<Command>>(); + for (var name in names) { + var category = commands[name]!.category; + commandsByCategory.putIfAbsent(category, () => []).add(commands[name]!); + } + final categories = commandsByCategory.keys.toList(); + var length = names.map((name) => name.length).reduce(math.max); var buffer = StringBuffer('Available ${isSubcommand ? "sub" : ""}commands:'); var columnStart = length + 5; - for (var name in names) { - var lines = wrapTextAsLines(commands[name]!.summary, - start: columnStart, length: lineLength); - buffer.writeln(); - buffer.write(' ${padRight(name, length)} ${lines.first}'); - - for (var line in lines.skip(1)) { + for (var category in categories) { + if (category != '') { buffer.writeln(); - buffer.write(' ' * columnStart); - buffer.write(line); + buffer.writeln(); + buffer.write('$category'); + } + for (var command in commandsByCategory[category]!) { + var lines = wrapTextAsLines(command.summary, + start: columnStart, length: lineLength); + buffer.writeln(); + buffer.write(' ${padRight(command.name, length)} ${lines.first}'); + + for (var line in lines.skip(1)) { + buffer.writeln(); + buffer.write(' ' * columnStart); + buffer.write(line); + } } }
diff --git a/pubspec.yaml b/pubspec.yaml index 332a9bd..b2994c7 100644 --- a/pubspec.yaml +++ b/pubspec.yaml
@@ -1,5 +1,5 @@ name: args -version: 2.2.0 +version: 2.3.0 homepage: https://github.com/dart-lang/args description: >- Library for defining parsers for parsing raw command-line arguments into a set
diff --git a/test/command_runner_test.dart b/test/command_runner_test.dart index 4cc6066..3f152b0 100644 --- a/test/command_runner_test.dart +++ b/test/command_runner_test.dart
@@ -53,6 +53,101 @@ Run "test help <command>" for more information about a command.''')); }); + group('displays categories', () { + test('when some commands are categorized', () { + runner.addCommand(Category1Command()); + runner.addCommand(Category2Command()); + runner.addCommand(FooCommand()); + + expect(runner.usage, equals(''' +A test command runner. + +Usage: test <command> [arguments] + +Global options: +-h, --help Print this usage information. + +Available commands: + foo Set a value. + +Displayers + baz Display a value. + +Printers + bar Print a value. + +Run "test help <command>" for more information about a command.''')); + }); + + test('except when all commands in a category are hidden', () { + runner.addCommand(Category1Command()); + runner.addCommand(HiddenCategorizedCommand()); + + expect(runner.usage, equals(''' +A test command runner. + +Usage: test <command> [arguments] + +Global options: +-h, --help Print this usage information. + +Available commands: + +Printers + bar Print a value. + +Run "test help <command>" for more information about a command.''')); + }); + + test('when all commands are categorized', () { + runner.addCommand(Category1Command()); + runner.addCommand(Category2Command()); + + expect(runner.usage, equals(''' +A test command runner. + +Usage: test <command> [arguments] + +Global options: +-h, --help Print this usage information. + +Available commands: + +Displayers + baz Display a value. + +Printers + bar Print a value. + +Run "test help <command>" for more information about a command.''')); + }); + + test('when multiple commands are in a category', () { + runner.addCommand(Category1Command()); + runner.addCommand(Category2Command()); + runner.addCommand(Category2Command2()); + + expect(runner.usage, equals(''' +A test command runner. + +Usage: test <command> [arguments] + +Global options: +-h, --help Print this usage information. + +Available commands: + +Displayers + baz Display a value. + baz2 Display another value. + +Printers + bar Print a value. + +Run "test help <command>" for more information about a command.''')); + }); + }); + test('truncates newlines in command descriptions by default', () { runner.addCommand(MultilineCommand()); @@ -109,6 +204,7 @@ test("doesn't print hidden commands", () { runner ..addCommand(HiddenCommand()) + ..addCommand(HiddenCategorizedCommand()) ..addCommand(FooCommand()); expect(runner.usage, equals('''
diff --git a/test/test_utils.dart b/test/test_utils.dart index 9f2d3df..c580d71 100644 --- a/test/test_utils.dart +++ b/test/test_utils.dart
@@ -75,6 +75,69 @@ Future<String> run() async => 'hi'; } +class Category1Command extends Command { + var hasRun = false; + + @override + final name = 'bar'; + + @override + final description = 'Print a value.'; + + @override + final category = 'Printers'; + + @override + final takesArguments = false; + + @override + void run() { + hasRun = true; + } +} + +class Category2Command extends Command { + var hasRun = false; + + @override + final name = 'baz'; + + @override + final description = 'Display a value.'; + + @override + final category = 'Displayers'; + + @override + final takesArguments = false; + + @override + void run() { + hasRun = true; + } +} + +class Category2Command2 extends Command { + var hasRun = false; + + @override + final name = 'baz2'; + + @override + final description = 'Display another value.'; + + @override + final category = 'Displayers'; + + @override + final takesArguments = false; + + @override + void run() { + hasRun = true; + } +} + class MultilineCommand extends Command { var hasRun = false; @@ -168,6 +231,30 @@ } } +class HiddenCategorizedCommand extends Command { + var hasRun = false; + + @override + final name = 'hiddencategorized'; + + @override + final description = 'Set a value.'; + + @override + final category = 'Some category'; + + @override + final hidden = true; + + @override + final takesArguments = false; + + @override + void run() { + hasRun = true; + } +} + class AliasedCommand extends Command { var hasRun = false;
