Add support for separators.
R=rnystrom@google.com
Review URL: https://codereview.chromium.org//1145413002
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c416d6..74a6d1e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 0.13.1
+
+* Add `ArgParser.addSeparator()`. Separators allow users to group their options
+ in the usage text.
+
## 0.13.0
* **Breaking change**: An option that allows multiple values will now
diff --git a/example/test_runner.dart b/example/test_runner.dart
index 9480f41..0d15e83 100644
--- a/example/test_runner.dart
+++ b/example/test_runner.dart
@@ -14,11 +14,7 @@
main() {
var parser = new ArgParser();
- parser.addOption('mode',
- abbr: 'm',
- defaultsTo: 'debug',
- help: 'Mode in which to run the tests',
- allowed: ['all', 'debug', 'release']);
+ parser.addSeparator('===== Platform');
parser.addOption('compiler',
abbr: 'c',
@@ -80,6 +76,14 @@
help: 'The operating system to run tests on',
allowed: ['linux', 'macos', 'windows']);
+ parser.addSeparator('===== Runtime');
+
+ parser.addOption('mode',
+ abbr: 'm',
+ defaultsTo: 'debug',
+ help: 'Mode in which to run the tests',
+ allowed: ['all', 'debug', 'release']);
+
parser.addFlag('checked',
defaultsTo: false, help: 'Run tests in checked mode');
@@ -88,6 +92,24 @@
parser.addOption('timeout', abbr: 't', help: 'Timeout in seconds');
+ parser.addOption('tasks',
+ abbr: 'j',
+ defaultsTo: Platform.numberOfProcessors.toString(),
+ help: 'The number of parallel tasks to run');
+
+ parser.addOption('shards',
+ defaultsTo: '1',
+ help: 'The number of instances that the tests will be sharded over');
+
+ parser.addOption('shard',
+ defaultsTo: '1',
+ help: 'The index of this instance when running in sharded mode');
+
+ parser.addFlag('valgrind',
+ defaultsTo: false, help: 'Run tests through valgrind');
+
+ parser.addSeparator('===== Output');
+
parser.addOption('progress',
abbr: 'p',
defaultsTo: 'compact',
@@ -106,32 +128,24 @@
defaultsTo: false,
help: 'Print a summary report of the number of tests, by expectation');
- parser.addOption('tasks',
- abbr: 'j',
- defaultsTo: Platform.numberOfProcessors.toString(),
- help: 'The number of parallel tasks to run');
-
- parser.addOption('shards',
- defaultsTo: '1',
- help: 'The number of instances that the tests will be sharded over');
-
- parser.addOption('shard',
- defaultsTo: '1',
- help: 'The index of this instance when running in sharded mode');
-
parser.addFlag('verbose',
abbr: 'v', defaultsTo: false, help: 'Verbose output');
parser.addFlag('list',
defaultsTo: false, help: 'List tests only, do not run them');
+ parser.addFlag('time',
+ help: 'Print timing information after running tests', defaultsTo: false);
+
+ parser.addFlag('batch',
+ abbr: 'b', help: 'Run browser tests in batch mode', defaultsTo: true);
+
+ parser.addSeparator('===== Miscellaneous');
+
parser.addFlag('keep-generated-tests',
defaultsTo: false,
help: 'Keep the generated files in the temporary directory');
- parser.addFlag('valgrind',
- defaultsTo: false, help: 'Run tests through valgrind');
-
parser.addOption('special-command', help: """
Special command support. Wraps the command line in
a special command. The special command should contain
@@ -143,15 +157,9 @@
'python -u valgrind.py @ suffix' the final command will be
'python -u valgrind.py dart file.dart suffix'""");
- parser.addFlag('time',
- help: 'Print timing information after running tests', defaultsTo: false);
-
parser.addOption('dart', help: 'Path to dart executable');
parser.addOption('drt', help: 'Path to content shell executable');
parser.addOption('dartium', help: 'Path to Dartium Chrome executable');
- parser.addFlag('batch',
- abbr: 'b', help: 'Run browser tests in batch mode', defaultsTo: true);
-
print(parser.usage);
}
diff --git a/lib/src/arg_parser.dart b/lib/src/arg_parser.dart
index 49d6aa6..c32741d 100644
--- a/lib/src/arg_parser.dart
+++ b/lib/src/arg_parser.dart
@@ -23,6 +23,10 @@
/// The commands that have been defined for this parser.
final Map<String, ArgParser> commands;
+ /// A list of the [Option]s in [options] intermingled with [String]
+ /// separators.
+ final _optionsAndSeparators = [];
+
/// Whether or not this parser parses options that appear after non-option
/// arguments.
final bool allowTrailingOptions;
@@ -110,9 +114,19 @@
}
}
- _options[name] = newOption(name, abbr, help, valueHelp, allowed,
+ var option = newOption(name, abbr, help, valueHelp, allowed,
allowedHelp, defaultsTo, callback, type,
negatable: negatable, splitCommas: splitCommas, hide: hide);
+ _options[name] = option;
+ _optionsAndSeparators.add(option);
+ }
+
+ /// Adds a separator line to the usage.
+ ///
+ /// In the usage text for the parser, this will appear between any options
+ /// added before this call and ones added after it.
+ void addSeparator(String text) {
+ _optionsAndSeparators.add(text);
}
/// Parses [args], a list of command-line arguments, matches them against the
@@ -124,12 +138,12 @@
///
/// This is basically the help text shown on the command line.
@Deprecated("Replaced with get usage. getUsage() will be removed in args 1.0")
- String getUsage() => new Usage(this).generate();
+ String getUsage() => usage;
/// Generates a string displaying usage information for the defined options.
///
/// This is basically the help text shown on the command line.
- String get usage => new Usage(this).generate();
+ String get usage => new Usage(_optionsAndSeparators).generate();
/// Get the default value for an option. Useful after parsing to test if the
/// user specified something other than the default.
diff --git a/lib/src/usage.dart b/lib/src/usage.dart
index 11be54b..177a810 100644
--- a/lib/src/usage.dart
+++ b/lib/src/usage.dart
@@ -22,8 +22,8 @@
class Usage {
static const NUM_COLUMNS = 3; // Abbreviation, long name, help.
- /// The parser this is generating usage for.
- final ArgParser args;
+ /// A list of the [Option]s intermingled with [String] separators.
+ final List optionsAndSeparators;
/// The working buffer for the generated usage text.
StringBuffer buffer;
@@ -53,7 +53,7 @@
/// content.
int newlinesNeeded = 0;
- Usage(this.args);
+ Usage(this.optionsAndSeparators);
/// Generates a string displaying usage information for the defined options.
/// This is basically the help text shown on the command line.
@@ -62,8 +62,17 @@
calculateColumnWidths();
- args.options.forEach((name, option) {
- if (option.hide) return;
+ for (var optionOrSeparator in optionsAndSeparators) {
+ if (optionOrSeparator is String) {
+ // Ensure that there's always a blank line before a separator.
+ if (buffer.isNotEmpty) buffer.write("\n\n");
+ buffer.write(optionOrSeparator);
+ newlinesNeeded = 1;
+ continue;
+ }
+
+ var option = optionOrSeparator as Option;
+ if (option.hide) continue;
write(0, getAbbreviation(option));
write(1, getLongOption(option));
@@ -94,7 +103,7 @@
// blank line after it. This gives space where it's useful while still
// keeping simple one-line options clumped together.
if (numHelpLines > 1) newline();
- });
+ }
return buffer.toString();
}
@@ -127,8 +136,9 @@
void calculateColumnWidths() {
int abbr = 0;
int title = 0;
- args.options.forEach((name, option) {
- if (option.hide) return;
+ for (var option in optionsAndSeparators) {
+ if (option is! Option) continue;
+ if (option.hide) continue;
// Make room in the first column if there are abbreviations.
abbr = max(abbr, getAbbreviation(option).length);
@@ -142,7 +152,7 @@
title = max(title, getAllowedTitle(allowed).length);
}
}
- });
+ }
// Leave a gutter between the columns.
title += 4;
diff --git a/pubspec.yaml b/pubspec.yaml
index cb373be..3b71ea3 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
name: args
-version: 0.13.1-dev
+version: 0.13.1
author: "Dart Team <misc@dartlang.org>"
homepage: https://github.com/dart-lang/args
description: >
diff --git a/test/usage_test.dart b/test/usage_test.dart
index 51efc05..492c517 100644
--- a/test/usage_test.dart
+++ b/test/usage_test.dart
@@ -205,6 +205,77 @@
--[no-]third The third flag
''');
});
+
+ group("separators", () {
+ test("separates options where it's placed", () {
+ var parser = new ArgParser();
+ parser.addFlag('zebra', help: 'First');
+ parser.addSeparator('Primate:');
+ parser.addFlag('monkey', help: 'Second');
+ parser.addSeparator('Marsupial:');
+ parser.addFlag('wombat', help: 'Third');
+
+ validateUsage(parser, '''
+ --[no-]zebra First
+
+ Primate:
+ --[no-]monkey Second
+
+ Marsupial:
+ --[no-]wombat Third
+ ''');
+ });
+
+ test("doesn't add extra newlines after a multiline option", () {
+ var parser = new ArgParser();
+ parser.addFlag('zebra', help: 'Multi\nline');
+ parser.addSeparator('Primate:');
+ parser.addFlag('monkey', help: 'Second');
+
+ validateUsage(parser, '''
+ --[no-]zebra Multi
+ line
+
+ Primate:
+ --[no-]monkey Second
+ ''');
+ });
+
+ test("doesn't add newlines if it's the first component", () {
+ var parser = new ArgParser();
+ parser.addSeparator('Equine:');
+ parser.addFlag('zebra', help: 'First');
+
+ validateUsage(parser, '''
+ Equine:
+ --[no-]zebra First
+ ''');
+ });
+
+ test("doesn't add trailing newlines if it's the last component", () {
+ var parser = new ArgParser();
+ parser.addFlag('zebra', help: 'First');
+ parser.addSeparator('Primate:');
+
+ validateUsage(parser, '''
+ --[no-]zebra First
+
+ Primate:
+ ''');
+ });
+
+ test("adds a newline after another separator", () {
+ var parser = new ArgParser();
+ parser.addSeparator('First');
+ parser.addSeparator('Second');
+
+ validateUsage(parser, '''
+ First
+
+ Second
+ ''');
+ });
+ });
});
}
