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.
 */
class ArgParser {
  final Map<String, Option> _options;
  final Map<String, ArgParser> _commands;

  /**
   * The options that have been defined for this parser.
   */
  final Map<String, Option> options;

  /**
   * The commands that have been defined for this parser.
   */
  final Map<String, ArgParser> commands;

  /** Creates a new ArgParser. */
  factory ArgParser() =>
      new ArgParser._(<String, Option>{}, <String, ArgParser>{});

  ArgParser._(Map<String, Option> options, Map<String, ArgParser> commands) :
    this._options = options,
    this.options = new UnmodifiableMapView(options),
    this._commands = commands,
    this.commands = new UnmodifiableMapView(commands);

  /**
   * 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].
   */
  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].
   */
  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,
      void callback(value), {bool isFlag, bool negatable: false,
      bool allowMultiple: false, bool hide: false}) {
    // Make sure the name isn't in use.
    if (_options.containsKey(name)) {
      throw new ArgumentError('Duplicate option "$name".');
    }

    // Make sure the abbreviation isn't too long or in use.
    if (abbr != null) {
      var existing = findByAbbreviation(abbr);
      if (existing != null) {
        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.
   *
   * 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.
   *
   * [allowTrailingOptions] is false by default, so when a non-option,
   * non-command argument is encountered, it and all remaining arguments,
   * even those that look like options are passed to the innermost command.
   */
  ArgResults parse(List<String> args, {bool allowTrailingOptions}) {
    if (allowTrailingOptions == null) allowTrailingOptions = false;
    return new Parser(null, this, args.toList(), null, null,
        allowTrailingOptions: allowTrailingOptions).parse();
  }

  /**
   * 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.
   */
  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.
   */
  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.
 */
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`.
   */
  final String name;

  /**
   * 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.
   */
  final List<String> rest;

  /** 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]. */
  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]. */
  Iterable<String> get options => _options.keys;
}