Add an explicit distinction between a command's description and summary.
ff4dd9a8e2255f998fd2f017205d9f908f82b8de broke some users who were
relying on only the first line of a command's description being included
in its runner's usage as a summary. That is once again the default
behavior.
To support the use case described in #42, there's a new Command.summary
getter that explicitly controls the summary included in the parent
runner's usage. This defaults to the first line of the description, but
may be overridden to declare a multi-line summary.
Closes #42
R=rnystrom@google.com
Review URL: https://codereview.chromium.org//1812923003 .
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 47c0cb5..ae90612 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,14 @@
+## 0.13.4
+
+* By default, only the first line of a command's description is included in its
+ parent runner's usage string. This returns to the default behavior from
+ before 0.13.3+1.
+
+* A `Command.summary` getter has been added to explicitly control the summary
+ that appears in the parent runner's usage string. This getter defaults to the
+ first line of the description, but can be overridden if the user wants a
+ multi-line summary.
+
## 0.13.3+6
* README fixes.
diff --git a/lib/command_runner.dart b/lib/command_runner.dart
index 3cc952e..d0cbf26 100644
--- a/lib/command_runner.dart
+++ b/lib/command_runner.dart
@@ -190,9 +190,15 @@
/// The name of this command.
String get name;
- /// A short description of this command.
+ /// A description of this command, included in [usage].
String get description;
+ /// A short description of this command, included in [parent]'s
+ /// [CommandRunner.usage].
+ ///
+ /// This defaults to the first line of [description].
+ String get summary => description.split("\n").first;
+
/// A single-line template for how to invoke this command (e.g. `"pub get
/// [package]"`).
String get invocation {
@@ -371,7 +377,7 @@
var buffer =
new StringBuffer('Available ${isSubcommand ? "sub" : ""}commands:');
for (var name in names) {
- var lines = commands[name].description.split("\n");
+ var lines = commands[name].summary.split("\n");
buffer.writeln();
buffer.write(' ${padRight(name, length)} ${lines.first}');
diff --git a/pubspec.yaml b/pubspec.yaml
index 128dd7f..38b5654 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
name: args
-version: 0.13.3+6
+version: 0.13.4
author: "Dart Team <misc@dartlang.org>"
homepage: https://github.com/dart-lang/args
description: >
diff --git a/test/command_runner_test.dart b/test/command_runner_test.dart
index bccc7b3..9961e7d 100644
--- a/test/command_runner_test.dart
+++ b/test/command_runner_test.dart
@@ -54,7 +54,7 @@
Run "test help <command>" for more information about a command."""));
});
- test("supports newlines in command descriptions", () {
+ test("truncates newlines in command descriptions by default", () {
runner.addCommand(new MultilineCommand());
expect(runner.usage, equals("""
@@ -68,6 +68,24 @@
Available commands:
help Display help information for test.
multiline Multi
+
+Run "test help <command>" for more information about a command."""));
+ });
+
+ test("supports newlines in command summaries", () {
+ runner.addCommand(new MultilineSummaryCommand());
+
+ expect(runner.usage, equals("""
+A test command runner.
+
+Usage: test <command> [arguments]
+
+Global options:
+-h, --help Print this usage information.
+
+Available commands:
+ help Display help information for test.
+ multiline Multi
line.
Run "test help <command>" for more information about a command."""));
diff --git a/test/utils.dart b/test/utils.dart
index 4ecc502..1fd8468 100644
--- a/test/utils.dart
+++ b/test/utils.dart
@@ -39,6 +39,10 @@
}
}
+class MultilineSummaryCommand extends MultilineCommand {
+ String get summary => description;
+}
+
class HiddenCommand extends Command {
var hasRun = false;
