Add "--verbose" to "--help" and hide most options normally.
Makes the "dart format help" and error messages much easier on the eyes.
Fix #938.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b5c1b8..36bfcf2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+# 1.3.7
+
+* Split help into verbose and non-verbose lists (#938).
+
# 1.3.6
* Change the path used in error messages when reading from stdin from "<stdin>"
diff --git a/bin/format.dart b/bin/format.dart
index 88193e2..bb4780c 100644
--- a/bin/format.dart
+++ b/bin/format.dart
@@ -16,7 +16,8 @@
void main(List<String> args) {
var parser = ArgParser(allowTrailingOptions: true);
- defineOptions(parser, oldCli: true);
+ defineOptions(parser,
+ oldCli: true, verbose: args.contains('--verbose') || args.contains('-v'));
ArgResults argResults;
try {
@@ -35,6 +36,10 @@
return;
}
+ if (argResults['verbose'] && !argResults['help']) {
+ usageError(parser, 'Can only use --verbose with --help.');
+ }
+
List<int> selection;
try {
selection = parseSelection(argResults, 'preserve');
diff --git a/lib/src/cli/format_command.dart b/lib/src/cli/format_command.dart
index baea3e0..b312381 100644
--- a/lib/src/cli/format_command.dart
+++ b/lib/src/cli/format_command.dart
@@ -24,8 +24,8 @@
String get invocation =>
'${runner.executableName} $name [options...] <files or directories...>';
- FormatCommand() {
- defineOptions(argParser, oldCli: false);
+ FormatCommand({bool verbose = false}) {
+ defineOptions(argParser, oldCli: false, verbose: verbose);
}
@override
@@ -75,6 +75,11 @@
summary = Summary.none;
}
+ // Can't use --verbose with anything but --help.
+ if (argResults['verbose'] && !argResults['help']) {
+ usageException('Can only use --verbose with --help.');
+ }
+
// Can't use any summary with JSON output.
if (output == Output.json && summary != Summary.none) {
usageException('Cannot print a summary with JSON output.');
diff --git a/lib/src/cli/options.dart b/lib/src/cli/options.dart
index 2c056c5..d36f0c5 100644
--- a/lib/src/cli/options.dart
+++ b/lib/src/cli/options.dart
@@ -5,15 +5,27 @@
import '../style_fix.dart';
-void defineOptions(ArgParser parser, {bool oldCli = false}) {
- parser.addSeparator('Common options:');
+void defineOptions(ArgParser parser, {bool oldCli = false, verbose = false}) {
+ if (oldCli) {
+ // The Command class implicitly adds "--help", so we only need to manually
+ // add it for the old CLI.
+ parser.addFlag('help',
+ abbr: 'h',
+ negatable: false,
+ help: 'Show this usage information.\n'
+ '(pass "--verbose" or "-v" to see all options)');
+ // Always make verbose hidden since the help text for --help explains it.
+ parser.addFlag('verbose', abbr: 'v', negatable: false, hide: true);
+ } else {
+ parser.addFlag('verbose',
+ abbr: 'v',
+ negatable: false,
+ help: 'Show all options and flags with --help.');
+ }
+
+ if (verbose) parser.addSeparator('Common options:');
if (oldCli) {
- // Command implicitly adds "--help", so we only need to manually add it for
- // the old CLI.
- parser.addFlag('help',
- abbr: 'h', negatable: false, help: 'Shows this usage information.');
-
parser.addFlag('overwrite',
abbr: 'w',
negatable: false,
@@ -42,7 +54,8 @@
'changed': 'Only the names of files whose formatting is changed.',
'none': 'No file names or directories.',
},
- defaultsTo: 'changed');
+ defaultsTo: 'changed',
+ hide: !verbose);
parser.addOption('summary',
help: 'Summary shown after formatting completes.',
allowed: ['line', 'profile', 'none'],
@@ -51,45 +64,56 @@
'profile': 'Tracks how long it took for format each file.',
'none': 'No summary.'
},
- defaultsTo: 'line');
+ defaultsTo: 'line',
+ hide: !verbose);
}
- parser.addSeparator('Non-whitespace fixes (off by default):');
+ if (verbose) parser.addSeparator('Non-whitespace fixes (off by default):');
parser.addFlag('fix', negatable: false, help: 'Apply all style fixes.');
for (var fix in StyleFix.all) {
// TODO(rnystrom): Allow negating this if used in concert with "--fix"?
- parser.addFlag('fix-${fix.name}', negatable: false, help: fix.description);
+ parser.addFlag('fix-${fix.name}',
+ negatable: false, help: fix.description, hide: !verbose);
}
- parser.addSeparator('Other options:');
+ if (verbose) parser.addSeparator('Other options:');
parser.addOption('line-length',
abbr: 'l', help: 'Wrap lines longer than this.', defaultsTo: '80');
parser.addOption('indent',
- abbr: 'i', help: 'Spaces of leading indentation.', defaultsTo: '0');
+ abbr: 'i',
+ help: 'Spaces of leading indentation.',
+ defaultsTo: '0',
+ hide: !verbose);
if (oldCli) {
parser.addFlag('machine',
abbr: 'm',
negatable: false,
- help: 'Produce machine-readable JSON output.');
+ help: 'Produce machine-readable JSON output.',
+ hide: !verbose);
}
parser.addFlag('set-exit-if-changed',
negatable: false,
- help: 'Return exit code 1 if there are any formatting changes.');
+ help: 'Return exit code 1 if there are any formatting changes.',
+ hide: !verbose);
parser.addFlag('follow-links',
negatable: false,
help: 'Follow links to files and directories.\n'
- 'If unset, links will be ignored.');
+ 'If unset, links will be ignored.',
+ hide: !verbose);
parser.addFlag('version',
- negatable: false, help: 'Show version information.');
+ negatable: false, help: 'Show dart_style version.', hide: !verbose);
- parser.addSeparator('Options when formatting from stdin:');
+ if (verbose) parser.addSeparator('Options when formatting from stdin:');
parser.addOption(oldCli ? 'preserve' : 'selection',
- help: 'Selection to preserve formatted as "start:length".');
+ help: 'Selection to preserve formatted as "start:length".',
+ hide: !verbose);
parser.addOption('stdin-name',
- help: 'The path name to show when an error occurs.', defaultsTo: 'stdin');
+ help: 'The path name to show when an error occurs.',
+ defaultsTo: 'stdin',
+ hide: !verbose);
if (oldCli) {
parser.addFlag('profile', negatable: false, hide: true);
diff --git a/pubspec.yaml b/pubspec.yaml
index cd72c61..3d8b8ed 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,6 +1,6 @@
name: dart_style
# Note: See tool/grind.dart for how to bump the version.
-version: 1.3.6
+version: 1.3.7-dev
description: >-
Opinionated, automatic Dart source code formatter.
Provides an API and a CLI tool.
diff --git a/test/command_line_test.dart b/test/command_line_test.dart
index a8d7629..7284e50 100644
--- a/test/command_line_test.dart
+++ b/test/command_line_test.dart
@@ -112,14 +112,38 @@
await process.shouldExit(0);
});
- test('--help', () async {
- var process = await runFormatter(['--help']);
- await expectLater(
- process.stdout, emits('Idiomatically formats Dart source code.'));
- await expectLater(process.stdout, emits(''));
- await expectLater(process.stdout,
- emits('Usage: dartfmt [options...] [files or directories...]'));
- await process.shouldExit(0);
+ group('--help', () {
+ test('non-verbose shows description and common options', () async {
+ var process = await runFormatter(['--help']);
+ await expectLater(
+ process.stdout, emits('Idiomatically formats Dart source code.'));
+ await expectLater(process.stdout, emits(''));
+ await expectLater(process.stdout,
+ emits('Usage: dartfmt [options...] [files or directories...]'));
+ await expectLater(process.stdout, emitsThrough(contains('--overwrite')));
+ await expectLater(process.stdout, emitsThrough(contains('--fix')));
+ await expectLater(process.stdout, neverEmits(contains('--set-exit-if-changed')));
+ await process.shouldExit(0);
+ });
+
+ test('verbose shows description and all options', () async {
+ var process = await runFormatter(['--help', '--verbose']);
+ await expectLater(
+ process.stdout, emits('Idiomatically formats Dart source code.'));
+ await expectLater(process.stdout, emits(''));
+ await expectLater(process.stdout,
+ emits('Usage: dartfmt [options...] [files or directories...]'));
+ await expectLater(process.stdout, emitsThrough(contains('--overwrite')));
+ await expectLater(process.stdout, emitsThrough(contains('--fix')));
+ await expectLater(process.stdout, emitsThrough(contains('--set-exit-if-changed')));
+ await process.shouldExit(0);
+ });
+ });
+
+ test('--verbose errors if not used with --help', () async {
+ var process = await runFormatterOnDir(['--verbose']);
+ expect(await process.stdout.next, 'Can only use --verbose with --help.');
+ await process.shouldExit(64);
});
test('only prints a hidden directory once', () async {
diff --git a/test/command_test.dart b/test/command_test.dart
index f18f3c2..c59eab1 100644
--- a/test/command_test.dart
+++ b/test/command_test.dart
@@ -280,11 +280,33 @@
await process.shouldExit(0);
});
- test('--help', () async {
- var process = await runCommand(['--help']);
- expect(
- await process.stdout.next, 'Idiomatically formats Dart source code.');
- await process.shouldExit(0);
+ group('--help', () {
+ test('non-verbose shows description and common options', () async {
+ var process = await runCommand(['--help']);
+ expect(
+ await process.stdout.next, 'Idiomatically formats Dart source code.');
+ await expectLater(process.stdout, emitsThrough(contains('-o, --output')));
+ await expectLater(process.stdout, emitsThrough(contains('--fix')));
+ await expectLater(process.stdout, neverEmits(contains('--summary')));
+ await process.shouldExit(0);
+ });
+
+ test('verbose shows description and all options', () async {
+ var process = await runCommand(['--help', '--verbose']);
+ expect(
+ await process.stdout.next, 'Idiomatically formats Dart source code.');
+ await expectLater(process.stdout, emitsThrough(contains('-o, --output')));
+ await expectLater(process.stdout, emitsThrough(contains('--show')));
+ await expectLater(process.stdout, emitsThrough(contains('--summary')));
+ await expectLater(process.stdout, emitsThrough(contains('--fix')));
+ await process.shouldExit(0);
+ });
+ });
+
+ test('--verbose errors if not used with --help', () async {
+ var process = await runCommandOnDir(['--verbose']);
+ expect(await process.stderr.next, 'Can only use --verbose with --help.');
+ await process.shouldExit(64);
});
group('fix', () {
diff --git a/tool/command_shell.dart b/tool/command_shell.dart
index e9f3531..dc12146 100644
--- a/tool/command_shell.dart
+++ b/tool/command_shell.dart
@@ -11,13 +11,16 @@
///
/// This enables tests to spawn this executable in order to verify the output
/// it prints.
-void main(List<String> command) async {
+void main(List<String> arguments) async {
var runner =
CommandRunner('dartfmt', 'Idiomatically formats Dart source code.');
- runner.addCommand(FormatCommand());
+ runner.argParser.addFlag('verbose',
+ abbr: 'v', negatable: false, help: 'Show verbose help.');
+ runner.addCommand(FormatCommand(
+ verbose: arguments.contains('-v') || arguments.contains('--verbose')));
try {
- await runner.runCommand(runner.parse(command));
+ await runner.runCommand(runner.parse(arguments));
} on UsageException catch (exception) {
stderr.writeln(exception);
exit(64);
