Modernize the docs for args.

pkg/args/lib/args.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/**
- * Parser support for transforming raw command-line arguments into a set
- * of options and values.
- *
- * This library supports [GNU][] and [POSIX][] style options, and it works
- * in both server-side and client-side apps.
- *
- * For information on installing this library, see the
- * [args package on pub.dartlang.org](http://pub.dartlang.org/packages/args).
- * Here's an example of importing this library:
- *
- *     import 'package:args/args.dart';
- *
- * ## Defining options
- *
- * To use this library, first create an [ArgParser]:
- *
- *     var parser = new ArgParser();
- *
- * Then define a set of options on that parser using [addOption()] and
- * [addFlag()]. Here's the minimal way to create an option named "name":
- *
- *     parser.addOption('name');
- *
- * When an option can only be set or unset (as opposed to taking a string
- * value), use a flag:
- *
- *     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);
- *
- * **Terminology note:**
- * From here on out, the term _option_ refers to both regular options and
- * flags. In cases where the distinction matters, this documentation uses
- * the term _non-flag option._
- *
- * Options can have an optional single-character abbreviation, specified
- * with the `abbr` parameter:
- *
- *     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);
- *
- * The default value for non-flag options can be any [String]. For flags,
- * it must be a [bool].
- *
- * To validate a non-flag option, you can use the `allowed` parameter to
- * provide an allowed set of values. When you do, the parser throws a
- * [FormatException] if the value for an option is not in the allowed set.
- * Here's an example of specifying allowed values:
- *
- *     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');
- *     });
- *
- * 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 value, or `null` if no default value is set.
- *
- * ## Parsing arguments
- *
- * Once you have an [ArgParser] set up with some options and flags, you
- * use it by calling [ArgParser.parse()] with a set of arguments:
- *
- *     var results = parser.parse(['some', 'command', 'line', 'args']);
- *
- * These arguments usually come from the arguments to main
- * (`main(List<String> arguments`), but you can pass in any list of strings.
- * The parse() method returns an 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']);
- *
- *     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].
- *
- *     print(results.rest); // ['something', 'else']
- *
- * To continue to parse options found after non-option arguments, call
- * parse() with `allowTrailingOptions: true`.
- *
- * ## Specifying options
- *
- * To actually pass in options and flags on the command line, use GNU or
- * POSIX style. Consider this option:
- *
- *     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
- *
- * Consider this flag:
- *
- *     parser.addFlag('name', abbr: 'n');
- *
- * You can set it to true using one of the following:
- *
- *     --name
- *     -n
- *
- * You can set it to false using the following:
- *
- *     --no-name
- *
- * Multiple flag abbreviations can be collapsed into a single argument. Say
- * you define these flags:
- *
- *     parser.addFlag('verbose', abbr: 'v');
- *     parser.addFlag('french', abbr: 'f');
- *     parser.addFlag('iambic-pentameter', abbr: 'i');
- *
- * You can set all three flags at once:
- *
- *     -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'
- *
- * 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]'
- *
- * ## Defining commands ##
- *
- * In addition to *options*, you can also define *commands*. A command is
- * a named argument that has its own set of options. For example, consider
- * this shell command:
- *
- *     $ 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');
- *
- * The addCommand() method 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 to addCommand:
- *
- *     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');
- *
- * 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
- *
- * 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');
- *
- *     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 "-a" appears after "commit", it is applied to that
- * command. If it appears to the left of "commit", it is given to the
- * top-level parser.
- *
- * ## Displaying usage
- *
- * You can automatically generate nice help text, suitable for use as the
- * output of `--help`. To display good usage information, you should
- * provide some help text when you create your options.
- *
- * 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');
- *
- * 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'
- *         });
- *
- * To display the help, use the ArgParser getUsage() method:
- *
- *     print(parser.getUsage());
- *
- * The resulting string looks something like this:
- *
- *     --mode            The compiler configuration
- *                       [debug, release]
- *
- *     --[no-]verbose    Show additional diagnostic info
- *     --arch            The architecture to compile for
- *
- *           [arm]       ARM Holding 32-bit chip
- *           [ia32]      Intel x86
- *
- * To assist the formatting of the usage help, single-line help text is
- * followed by a single new line. Options with multi-line help text are
- * followed by two new lines. This provides spatial diversity between options.
- *
- * [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
- */
 library args;
 
 import 'package:collection/wrappers.dart';
 
 import 'src/parser.dart';
 import 'src/usage.dart';
 import 'src/options.dart';
 export 'src/options.dart';
 
-/**
- * A class for taking a list of raw command line arguments and parsing out
- * options and flags from them.
- */
+/// A class for taking a list of raw command line arguments and parsing out
+/// options and flags from them.
 class ArgParser {
   final Map<String, Option> _options;
   final Map<String, ArgParser> _commands;
 
-  /**
-   * The options that have been defined for this parser.
-   */
+  /// The options that have been defined for this parser.
   final Map<String, Option> options;
 
-  /**
-   * The commands that have been defined for this parser.
-   */
+  /// The commands that have been defined for this parser.
   final Map<String, ArgParser> commands;
 
-  /**
-   * Whether or not this parser parses options that appear after non-option
-   * arguments.
-   */
+  /// Whether or not this parser parses options that appear after non-option
+  /// arguments.
   final bool allowTrailingOptions;
 
-  /**
-   * Creates a new ArgParser.
-   *
-   * If [allowTrailingOptions] is set, the parser will continue parsing even
-   * after it finds an argument that is neither an option nor a command.
-   * This allows options to be specified after regular arguments. Defaults to
-   * `false`.
-   */
+  /// Creates a new ArgParser.
+  ///
+  /// If [allowTrailingOptions] is set, the parser will continue parsing even
+  /// after it finds an argument that is neither an option nor a command.
+  /// This allows options to be specified after regular arguments. Defaults to
+  /// `false`.
   factory ArgParser({bool allowTrailingOptions}) =>
       new ArgParser._(<String, Option>{}, <String, ArgParser>{},
           allowTrailingOptions: allowTrailingOptions);
 
   ArgParser._(Map<String, Option> options, Map<String, ArgParser> commands,
       {bool allowTrailingOptions}) :
     this._options = options,
     this.options = new UnmodifiableMapView(options),
     this._commands = commands,
     this.commands = new UnmodifiableMapView(commands),
     this.allowTrailingOptions = allowTrailingOptions != null ?
         allowTrailingOptions : false;
 
-  /**
-   * Defines a command.
-   *
-   * A command is a named argument which may in turn define its own options and
-   * subcommands using the given parser. If [parser] is omitted, implicitly
-   * creates a new one. Returns the parser for the command.
-   */
+  /// Defines a command.
+  ///
+  /// A command is a named argument which may in turn define its own options and
+  /// subcommands using the given parser. If [parser] is omitted, implicitly
+  /// creates a new one. Returns the parser for the command.
   ArgParser addCommand(String name, [ArgParser parser]) {
     // Make sure the name isn't in use.
     if (_commands.containsKey(name)) {
       throw new ArgumentError('Duplicate command "$name".');
     }
 
     if (parser == null) parser = new ArgParser();
     _commands[name] = parser;
     return parser;
   }
 
-  /**
-   * Defines a flag. Throws an [ArgumentError] if:
-   *
-   * * There is already an option named [name].
-   * * There is already an option using abbreviation [abbr].
-   */
+  /// Defines a flag. Throws an [ArgumentError] if:
+  ///
+  /// * There is already an option named [name].
+  /// * There is already an option using abbreviation [abbr].
   void addFlag(String name, {String abbr, String help, bool defaultsTo: false,
       bool negatable: true, void callback(bool value), bool hide: false}) {
     _addOption(name, abbr, help, null, null, defaultsTo, callback,
         isFlag: true, negatable: negatable, hide: hide);
   }
 
-  /**
-   * Defines a value-taking option. Throws an [ArgumentError] if:
-   *
-   * * There is already an option with name [name].
-   * * There is already an option using abbreviation [abbr].
-   */
+  /// Defines a value-taking option. Throws an [ArgumentError] if:
+  ///
+  /// * There is already an option with name [name].
+  /// * There is already an option using abbreviation [abbr].
   void addOption(String name, {String abbr, String help, List<String> allowed,
       Map<String, String> allowedHelp, String defaultsTo,
       void callback(value), bool allowMultiple: false, bool hide: false}) {
     _addOption(name, abbr, help, allowed, allowedHelp, defaultsTo,
         callback, isFlag: false, allowMultiple: allowMultiple,
         hide: hide);
   }
 
   void _addOption(String name, String abbr, String help, List<String> allowed,
       Map<String, String> allowedHelp, defaultsTo,
@@ skipping 11 matching lines @@
         throw new ArgumentError(
             'Abbreviation "$abbr" is already used by "${existing.name}".');
       }
     }
 
     _options[name] = new Option(name, abbr, help, allowed, allowedHelp,
         defaultsTo, callback, isFlag: isFlag, negatable: negatable,
         allowMultiple: allowMultiple, hide: hide);
   }
 
-  /**
-   * Parses [args], a list of command-line arguments, matches them against the
-   * flags and options defined by this parser, and returns the result.
-   */
+  /// Parses [args], a list of command-line arguments, matches them against the
+  /// flags and options defined by this parser, and returns the result.
   ArgResults parse(List<String> args) =>
       new Parser(null, this, args.toList(), null, null).parse();
 
-  /**
-   * Generates a string displaying usage information for the defined options.
-   * This is basically the help text shown on the command line.
-   */
+  /// Generates a string displaying usage information for the defined options.
+  /// This is basically the help text shown on the command line.
   String getUsage() => new Usage(this).generate();
 
-  /**
-   * Get the default value for an option. Useful after parsing to test
-   * if the user specified something other than the default.
-   */
+  /// Get the default value for an option. Useful after parsing to test if the
+  /// user specified something other than the default.
   getDefault(String option) {
     if (!options.containsKey(option)) {
       throw new ArgumentError('No option named $option');
     }
     return options[option].defaultValue;
   }
 
-  /**
-   * Finds the option whose abbreviation is [abbr], or `null` if no option has
-   * that abbreviation.
-   */
+  /// Finds the option whose abbreviation is [abbr], or `null` if no option has
+  /// that abbreviation.
   Option findByAbbreviation(String abbr) {
     return options.values.firstWhere((option) => option.abbreviation == abbr,
         orElse: () => null);
   }
 }
 
-/**
- * The results of parsing a series of command line arguments using
- * [ArgParser.parse()]. Includes the parsed options and any remaining unparsed
- * command line arguments.
- */
+/// The results of parsing a series of command line arguments using
+/// [ArgParser.parse()]. Includes the parsed options and any remaining unparsed
+/// command line arguments.
 class ArgResults {
   final Map<String, dynamic> _options;
 
-  /**
-   * If these are the results for parsing a command's options, this will be
-   * the name of the command. For top-level results, this returns `null`.
-   */
+  /// If these are the results for parsing a command's options, this will be the
+  /// name of the command. For top-level results, this returns `null`.
   final String name;
 
-  /**
-   * The command that was selected, or `null` if none was. This will contain
-   * the options that were selected for that command.
-   */
+  /// The command that was selected, or `null` if none was. This will contain
+  /// the options that were selected for that command.
   final ArgResults command;
 
-  /**
-   * The remaining command-line arguments that were not parsed as options or
-   * flags. If `--` was used to separate the options from the remaining
-   * arguments, it will not be included in this list.
-   */
+  /// The remaining command-line arguments that were not parsed as options or
+  /// flags. If `--` was used to separate the options from the remaining
+  /// arguments, it will not be included in this list.
   final List<String> rest;
 
-  /** Creates a new [ArgResults]. */
+  /// Creates a new [ArgResults].
   ArgResults(this._options, this.name, this.command, List<String> rest)
     : this.rest = new UnmodifiableListView(rest);
 
-  /** Gets the parsed command-line option named [name]. */
+  /// Gets the parsed command-line option named [name].
   operator [](String name) {
     if (!_options.containsKey(name)) {
       throw new ArgumentError(
           'Could not find an option named "$name".');
     }
 
     return _options[name];
   }
 
-  /** Get the names of the options as an [Iterable]. */
+  /// Get the names of the options as an [Iterable].
   Iterable<String> get options => _options.keys;
 }