Fixed missing comma in test and updated README syntax
Closes #1
R=rnystrom@google.com
Review URL: https://codereview.chromium.org//925003002
diff --git a/README.md b/README.md
index fe25d89..fa635cb 100644
--- a/README.md
+++ b/README.md
@@ -17,12 +17,16 @@
When an option can only be set or unset (as opposed to taking a string value),
use a flag:
- parser.addFlag('name');
+```dart
+parser.addFlag('name');
+```
Flag options, by default, accept a 'no-' prefix to negate the option. You can
disable the 'no-' prefix using the `negatable` parameter:
- parser.addFlag('name', negatable: false);
+```dart
+parser.addFlag('name', negatable: false);
+```
*Note:* From here on out, "option" refers to both regular options and flags. In
cases where the distinction matters, we'll use "non-flag option."
@@ -30,14 +34,18 @@
Options can have an optional single-character abbreviation, specified with the
`abbr` parameter:
- parser.addOption('mode', abbr: 'm');
- parser.addFlag('verbose', abbr: 'v');
+```dart
+parser.addOption('mode', abbr: 'm');
+parser.addFlag('verbose', abbr: 'v');
+```
Options can also have a default value, specified with the `defaultsTo`
parameter. The default value is used when arguments don't specify the option.
- parser.addOption('mode', defaultsTo: 'debug');
- parser.addFlag('verbose', defaultsTo: false);
+```dart
+parser.addOption('mode', defaultsTo: 'debug');
+parser.addFlag('verbose', defaultsTo: false);
+```
The default value for non-flag options can be any string. For flags, it must
be a `bool`.
@@ -47,16 +55,20 @@
value for an option is not in the allowed set. Here's an example of specifying
allowed values:
- parser.addOption('mode', allowed: ['debug', 'release']);
+```dart
+parser.addOption('mode', allowed: ['debug', 'release']);
+```
You can use the `callback` parameter to associate a function with an option.
Later, when parsing occurs, the callback function is invoked with the value of
the option:
- parser.addOption('mode', callback: (mode) => print('Got mode $mode'));
- parser.addFlag('verbose', callback: (verbose) {
- if (verbose) print('Verbose');
- });
+```dart
+parser.addOption('mode', callback: (mode) => print('Got mode $mode'));
+parser.addFlag('verbose', callback: (verbose) {
+ if (verbose) print('Verbose');
+});
+```
The callbacks for all options are called whenever a set of arguments is parsed.
If an option isn't provided in the args, its callback is passed the default
@@ -67,7 +79,9 @@
Once you have an [ArgParser][] set up with some options and flags, you use it by
calling [ArgParser.parse()][parse] with a set of arguments:
- var results = parser.parse(['some', 'command', 'line', 'args']);
+```dart
+var results = parser.parse(['some', 'command', 'line', 'args']);
+```
These arguments usually come from the arguments to `main()`. For example:
@@ -80,19 +94,23 @@
instance of [ArgResults][], a map-like object that contains the values of the
parsed options.
- var parser = new ArgParser();
- parser.addOption('mode');
- parser.addFlag('verbose', defaultsTo: true);
- var results = parser.parse(['--mode', 'debug', 'something', 'else']);
+```dart
+var parser = new ArgParser();
+parser.addOption('mode');
+parser.addFlag('verbose', defaultsTo: true);
+var results = parser.parse(['--mode', 'debug', 'something', 'else']);
- print(results['mode']); // debug
- print(results['verbose']); // true
+print(results['mode']); // debug
+print(results['verbose']); // true
+```
By default, the `parse()` method stops as soon as it reaches `--` by itself or
anything that the parser doesn't recognize as an option, flag, or option value.
If arguments still remain, they go into [ArgResults.rest][rest].
- print(results.rest); // ['something', 'else']
+```dart
+print(results.rest); // ['something', 'else']
+```
To continue to parse options found after non-option arguments, pass
`allowTrailingOptions: true` when creating the [ArgParser][].
@@ -102,56 +120,74 @@
To actually pass in options and flags on the command line, use GNU or POSIX
style. Consider this option:
- parser.addOption('name', abbr: 'n');
+```dart
+parser.addOption('name', abbr: 'n');
+```
You can specify its value on the command line using any of the following:
- --name=somevalue
- --name somevalue
- -nsomevalue
- -n somevalue
+```
+--name=somevalue
+--name somevalue
+-nsomevalue
+-n somevalue
+```
Consider this flag:
- parser.addFlag('name', abbr: 'n');
+```dart
+parser.addFlag('name', abbr: 'n');
+```
You can set it to true using one of the following:
- --name
- -n
+```
+--name
+-n
+```
You can set it to false using the following:
- --no-name
+```
+--no-name
+```
Multiple flag abbreviations can be collapsed into a single argument. Say you
define these flags:
- parser
- ..addFlag('verbose', abbr: 'v')
- ..addFlag('french', abbr: 'f')
- ..addFlag('iambic-pentameter', abbr: 'i');
+```dart
+parser
+ ..addFlag('verbose', abbr: 'v')
+ ..addFlag('french', abbr: 'f')
+ ..addFlag('iambic-pentameter', abbr: 'i');
+```
You can set all three flags at once:
- -vfi
+```
+-vfi
+```
By default, an option has only a single value, with later option values
overriding earlier ones; for example:
- var parser = new ArgParser();
- parser.addOption('mode');
- var results = parser.parse(['--mode', 'on', '--mode', 'off']);
- print(results['mode']); // prints 'off'
+```dart
+var parser = new ArgParser();
+parser.addOption('mode');
+var results = parser.parse(['--mode', 'on', '--mode', 'off']);
+print(results['mode']); // prints 'off'
+```
If you need multiple values, set the `allowMultiple` parameter. In that case the
option can occur multiple times, and the `parse()` method returns a list of
values:
- var parser = new ArgParser();
- parser.addOption('mode', allowMultiple: true);
- var results = parser.parse(['--mode', 'on', '--mode', 'off']);
- print(results['mode']); // prints '[on, off]'
+```dart
+var parser = new ArgParser();
+parser.addOption('mode', allowMultiple: true);
+var results = parser.parse(['--mode', 'on', '--mode', 'off']);
+print(results['mode']); // prints '[on, off]'
+```
## Defining commands ##
@@ -159,46 +195,58 @@
argument that has its own set of options. For example, consider this shell
command:
- $ git commit -a
+```
+$ git commit -a
+```
The executable is `git`, the command is `commit`, and the `-a` option is an
option passed to the command. You can add a command using the [addCommand][]
method:
- var parser = new ArgParser();
- var command = parser.addCommand('commit');
+```dart
+var parser = new ArgParser();
+var command = parser.addCommand('commit');
+```
It returns another [ArgParser][], which you can then use to define options
specific to that command. If you already have an [ArgParser][] for the command's
options, you can pass it in:
- var parser = new ArgParser();
- var command = new ArgParser();
- parser.addCommand('commit', command);
+```dart
+var parser = new ArgParser();
+var command = new ArgParser();
+parser.addCommand('commit', command);
+```
The [ArgParser][] for a command can then define options or flags:
- command.addFlag('all', abbr: 'a');
+```dart
+command.addFlag('all', abbr: 'a');
+```
You can add multiple commands to the same parser so that a user can select one
from a range of possible commands. When parsing an argument list, you can then
determine which command was entered and what options were provided for it.
- var results = parser.parse(['commit', '-a']);
- print(results.command.name); // "commit"
- print(results.command['all']); // true
+```dart
+var results = parser.parse(['commit', '-a']);
+print(results.command.name); // "commit"
+print(results.command['all']); // true
+```
Options for a command must appear after the command in the argument list. For
example, given the above parser, `"git -a commit"` is *not* valid. The parser
tries to find the right-most command that accepts an option. For example:
- var parser = new ArgParser();
- parser.addFlag('all', abbr: 'a');
- var command = parser.addCommand('commit');
- command.addFlag('all', abbr: 'a');
+```dart
+var parser = new ArgParser();
+parser.addFlag('all', abbr: 'a');
+var command = parser.addCommand('commit');
+command.addFlag('all', abbr: 'a');
- var results = parser.parse(['commit', '-a']);
- print(results.command['all']); // true
+var results = parser.parse(['commit', '-a']);
+print(results.command['all']); // true
+```
Here, both the top-level parser and the `"commit"` command can accept a `"-a"`
(which is probably a bad command line interface, admittedly). In that case, when
@@ -212,45 +260,51 @@
support for dispatching to [Command][]s based on command-line arguments, as well
as handling `--help` flags and invalid arguments. For example:
- var runner = new CommandRunner("git", "Distributed version control.")
- ..addCommand(new CommitCommand())
- ..addCommand(new StashCommand())
- ..run(['commit', '-a']); // Calls [CommitCommand.run()]
+```dart
+var runner = new CommandRunner("git", "Distributed version control.")
+ ..addCommand(new CommitCommand())
+ ..addCommand(new StashCommand())
+ ..run(['commit', '-a']); // Calls [CommitCommand.run()]
+```
Custom commands are defined by extending the [Command][] class. For example:
- class CommitCommand extends Command {
- // The [name] and [description] properties must be defined by every
- // subclass.
- final name = "commit";
- final description = "Record changes to the repository.";
+```dart
+class CommitCommand extends Command {
+ // The [name] and [description] properties must be defined by every
+ // subclass.
+ final name = "commit";
+ final description = "Record changes to the repository.";
- CommitCommand() {
- // [argParser] is automatically created by the parent class.
- argParser.addFlag('all', abbr: 'a');
- }
+ CommitCommand() {
+ // [argParser] is automatically created by the parent class.
+ argParser.addFlag('all', abbr: 'a');
+ }
- // [run] may also return a Future.
- void run() {
- // [options] is set before [run()] is called and contains the options
- // passed to this command.
- print(options['all']);
- }
- }
+ // [run] may also return a Future.
+ void run() {
+ // [options] is set before [run()] is called and contains the options
+ // passed to this command.
+ print(options['all']);
+ }
+}
+```
Commands can also have subcommands, which are added with [addSubcommand][]. A
command with subcommands can't run its own code, so [run][] doesn't need to be
implemented. For example:
- class StashCommand extends Command {
- final String name = "stash";
- final String description = "Stash changes in the working directory.";
+```dart
+class StashCommand extends Command {
+ final String name = "stash";
+ final String description = "Stash changes in the working directory.";
- StashCommand() {
- addSubcommand(new StashSaveCommand());
- addSubcommand(new StashListCommand());
- }
- }
+ StashCommand() {
+ addSubcommand(new StashSaveCommand());
+ addSubcommand(new StashListCommand());
+ }
+}
+```
[CommandRunner][] automatically adds a `help` command that displays usage
information for commands, as well as support for the `--help` flag for all
@@ -258,11 +312,13 @@
command, it throws a [UsageError][]; your `main()` method should catch these and
print them appropriately. For example:
- runner.run(arguments).catchError((error) {
- if (error is! UsageError) throw error;
- print(error);
- exit(64); // Exit code 64 indicates a usage error.
- });
+```dart
+runner.run(arguments).catchError((error) {
+ if (error is! UsageError) throw error;
+ print(error);
+ exit(64); // Exit code 64 indicates a usage error.
+});
+```
## Displaying usage
@@ -272,38 +328,48 @@
To define help text for an entire option, use the `help:` parameter:
- parser.addOption('mode', help: 'The compiler configuration',
- allowed: ['debug', 'release']);
- parser.addFlag('verbose', help: 'Show additional diagnostic info');
+```dart
+parser.addOption('mode', help: 'The compiler configuration',
+ allowed: ['debug', 'release']);
+parser.addFlag('verbose', help: 'Show additional diagnostic info');
+```
For non-flag options, you can also provide a help string for the parameter:
- parser.addOption('out', help: 'The output path', valueHelp: 'path',
- allowed: ['debug', 'release']);
+```dart
+parser.addOption('out', help: 'The output path', valueHelp: 'path',
+ allowed: ['debug', 'release']);
+```
For non-flag options, you can also provide detailed help for each expected value
by using the `allowedHelp:` parameter:
- parser.addOption('arch', help: 'The architecture to compile for',
- allowedHelp: {
- 'ia32': 'Intel x86',
- 'arm': 'ARM Holding 32-bit chip'
- });
+```dart
+parser.addOption('arch', help: 'The architecture to compile for',
+ allowedHelp: {
+ 'ia32': 'Intel x86',
+ 'arm': 'ARM Holding 32-bit chip'
+ });
+```
To display the help, use the [getUsage()][getUsage] method:
- print(parser.getUsage());
+```dart
+print(parser.getUsage());
+```
The resulting string looks something like this:
- --mode The compiler configuration
- [debug, release]
+```
+--mode The compiler configuration
+ [debug, release]
- --out=<path> The output path
- --[no-]verbose Show additional diagnostic info
- --arch The architecture to compile for
- [arm] ARM Holding 32-bit chip
- [ia32] Intel x86
+--out=<path> The output path
+--[no-]verbose Show additional diagnostic info
+--arch The architecture to compile for
+ [arm] ARM Holding 32-bit chip
+ [ia32] Intel x86
+```
[posix]: http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_02
[gnu]: http://www.gnu.org/prep/standards/standards.html#Command_002dLine-Interfaces
diff --git a/pubspec.yaml b/pubspec.yaml
index dc77d99..fdf99c0 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
name: args
-version: 0.12.2+4
+version: 0.12.2+5
author: "Dart Team <misc@dartlang.org>"
homepage: https://github.com/dart-lang/args
description: >
diff --git a/test/args_test.dart b/test/args_test.dart
index dd1634d..4c23ba5 100644
--- a/test/args_test.dart
+++ b/test/args_test.dart
@@ -302,8 +302,8 @@
];
const _VALID_OPTIONS = const [
- 'a' // One character.
- 'contains-dash',
+ 'a', // One character.
+ 'contains-dash',
'contains_underscore',
'ends-with-dash-',
'contains--doubledash--',
