lib/src/parser.dart - args - Git at Google

 // 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.

 library args.src.parser;

 import 'arg_parser.dart';
 import 'arg_results.dart';
 import 'option.dart';

 final _SOLO_OPT = new RegExp(r'^-([a-zA-Z0-9])$');
 final _ABBR_OPT = new RegExp(r'^-([a-zA-Z0-9]+)(.*)$');
 final _LONG_OPT = new RegExp(r'^--([a-zA-Z\-_0-9]+)(=(.*))?$');

 /// The actual argument parsing class.
 ///
 /// Unlike [ArgParser] which is really more an "arg grammar", this is the class
 /// that does the parsing and holds the mutable state required during a parse.
 class Parser {
   /// If parser is parsing a command's options, this will be the name of the
   /// command. For top-level results, this returns `null`.
   final String commandName;

   /// The parser for the supercommand of this command parser, or `null` if this
   /// is the top-level parser.
   final Parser parent;

   /// The grammar being parsed.
   final ArgParser grammar;

   /// The arguments being parsed.
   final List<String> args;

   /// The remaining non-option, non-command arguments.
   final rest = <String>[];

   /// The accumulated parsed options.
   final Map<String, dynamic> results = <String, dynamic>{};

   Parser(this.commandName, this.grammar, this.args, this.parent, rest) {
     if (rest != null) this.rest.addAll(rest);
   }

   /// The current argument being parsed.
   String get current => args[0];

   /// Parses the arguments. This can only be called once.
   ArgResults parse() {
     var arguments = args.toList();
     var commandResults = null;

     // Parse the args.
     while (args.length > 0) {
       if (current == '--') {
         // Reached the argument terminator, so stop here.
         args.removeAt(0);
         break;
       }

       // Try to parse the current argument as a command. This happens before
       // options so that commands can have option-like names.
       var command = grammar.commands[current];
       if (command != null) {
         validate(rest.isEmpty, 'Cannot specify arguments before a command.');
         var commandName = args.removeAt(0);
         var commandParser = new Parser(commandName, command, args, this, rest);
         commandResults = commandParser.parse();

         // All remaining arguments were passed to command so clear them here.
         rest.clear();
         break;
       }

       // Try to parse the current argument as an option. Note that the order
       // here matters.
       if (parseSoloOption()) continue;
       if (parseAbbreviation(this)) continue;
       if (parseLongOption()) continue;

       // This argument is neither option nor command, so stop parsing unless
       // the [allowTrailingOptions] option is set.
       if (!grammar.allowTrailingOptions) break;
       rest.add(args.removeAt(0));
     }

     // Invoke the callbacks.
     grammar.options.forEach((name, option) {
       if (option.callback == null) return;
       option.callback(option.getOrDefault(results[name]));
     });

     // Add in the leftover arguments we didn't parse to the innermost command.
     rest.addAll(args);
     args.clear();
     return newArgResults(
         grammar, results, commandName, commandResults, rest, arguments);
   }

   /// Pulls the value for [option] from the second argument in [args].
   ///
   /// Validates that there is a valid value there.
   void readNextArgAsValue(Option option) {
     // Take the option argument from the next command line arg.
     validate(args.length > 0, 'Missing argument for "${option.name}".');

     // Make sure it isn't an option itself.
     validate(!_ABBR_OPT.hasMatch(current) && !_LONG_OPT.hasMatch(current),
         'Missing argument for "${option.name}".');

     setOption(results, option, current);
     args.removeAt(0);
   }

   /// Tries to parse the current argument as a "solo" option, which is a single
   /// hyphen followed by a single letter.
   ///
   /// We treat this differently than collapsed abbreviations (like "-abc") to
   /// handle the possible value that may follow it.
   bool parseSoloOption() {
     var soloOpt = _SOLO_OPT.firstMatch(current);
     if (soloOpt == null) return false;

     var option = grammar.findByAbbreviation(soloOpt[1]);
     if (option == null) {
       // Walk up to the parent command if possible.
       validate(
           parent != null, 'Could not find an option or flag "-${soloOpt[1]}".');
       return parent.parseSoloOption();
     }

     args.removeAt(0);

     if (option.isFlag) {
       setOption(results, option, true);
     } else {
       readNextArgAsValue(option);
     }

     return true;
   }

   /// Tries to parse the current argument as a series of collapsed abbreviations
   /// (like "-abc") or a single abbreviation with the value directly attached
   /// to it (like "-mrelease").
   bool parseAbbreviation(Parser innermostCommand) {
     var abbrOpt = _ABBR_OPT.firstMatch(current);
     if (abbrOpt == null) return false;

     // If the first character is the abbreviation for a non-flag option, then
     // the rest is the value.
     var c = abbrOpt[1].substring(0, 1);
     var first = grammar.findByAbbreviation(c);
     if (first == null) {
       // Walk up to the parent command if possible.
       validate(
           parent != null, 'Could not find an option with short name "-$c".');
       return parent.parseAbbreviation(innermostCommand);
     } else if (!first.isFlag) {
       // The first character is a non-flag option, so the rest must be the
       // value.
       var value = '${abbrOpt[1].substring(1)}${abbrOpt[2]}';
       setOption(results, first, value);
     } else {
       // If we got some non-flag characters, then it must be a value, but
       // if we got here, it's a flag, which is wrong.
       validate(abbrOpt[2] == '',
           'Option "-$c" is a flag and cannot handle value '
           '"${abbrOpt[1].substring(1)}${abbrOpt[2]}".');

       // Not an option, so all characters should be flags.
       // We use "innermostCommand" here so that if a parent command parses the
       // *first* letter, subcommands can still be found to parse the other
       // letters.
       for (var i = 0; i < abbrOpt[1].length; i++) {
         var c = abbrOpt[1].substring(i, i + 1);
         innermostCommand.parseShortFlag(c);
       }
     }

     args.removeAt(0);
     return true;
   }

   void parseShortFlag(String c) {
     var option = grammar.findByAbbreviation(c);
     if (option == null) {
       // Walk up to the parent command if possible.
       validate(
           parent != null, 'Could not find an option with short name "-$c".');
       parent.parseShortFlag(c);
       return;
     }

     // In a list of short options, only the first can be a non-flag. If
     // we get here we've checked that already.
     validate(
         option.isFlag, 'Option "-$c" must be a flag to be in a collapsed "-".');

     setOption(results, option, true);
   }

   /// Tries to parse the current argument as a long-form named option, which
   /// may include a value like "--mode=release" or "--mode release".
   bool parseLongOption() {
     var longOpt = _LONG_OPT.firstMatch(current);
     if (longOpt == null) return false;

     var name = longOpt[1];
     var option = grammar.options[name];
     if (option != null) {
       args.removeAt(0);
       if (option.isFlag) {
         validate(longOpt[3] == null,
             'Flag option "$name" should not be given a value.');

         setOption(results, option, true);
       } else if (longOpt[3] != null) {
         // We have a value like --foo=bar.
         setOption(results, option, longOpt[3]);
       } else {
         // Option like --foo, so look for the value as the next arg.
         readNextArgAsValue(option);
       }
     } else if (name.startsWith('no-')) {
       // See if it's a negated flag.
       name = name.substring('no-'.length);
       option = grammar.options[name];
       if (option == null) {
         // Walk up to the parent command if possible.
         validate(parent != null, 'Could not find an option named "$name".');
         return parent.parseLongOption();
       }

       args.removeAt(0);
       validate(option.isFlag, 'Cannot negate non-flag option "$name".');
       validate(option.negatable, 'Cannot negate option "$name".');

       setOption(results, option, false);
     } else {
       // Walk up to the parent command if possible.
       validate(parent != null, 'Could not find an option named "$name".');
       return parent.parseLongOption();
     }

     return true;
   }

   /// Called during parsing to validate the arguments.
   ///
   /// Throws a [FormatException] if [condition] is `false`.
   void validate(bool condition, String message) {
     if (!condition) throw new FormatException(message);
   }

   /// Validates and stores [value] as the value for [option].
   void setOption(Map results, Option option, value) {
     // See if it's one of the allowed values.
     if (option.allowed != null) {
       validate(option.allowed.any((allow) => allow == value),
           '"$value" is not an allowed value for option "${option.name}".');
     }

     if (option.isMultiple) {
       var list = results.putIfAbsent(option.name, () => []);
       list.add(value);
     } else {
       results[option.name] = value;
     }
   }
 }
	// 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.

	library args.src.parser;

	import 'arg_parser.dart';
	import 'arg_results.dart';
	import 'option.dart';

	final _SOLO_OPT = new RegExp(r'^-([a-zA-Z0-9])$');
	final _ABBR_OPT = new RegExp(r'^-([a-zA-Z0-9]+)(.*)$');
	final _LONG_OPT = new RegExp(r'^--([a-zA-Z\-_0-9]+)(=(.*))?$');

	/// The actual argument parsing class.
	///
	/// Unlike [ArgParser] which is really more an "arg grammar", this is the class
	/// that does the parsing and holds the mutable state required during a parse.
	class Parser {
	/// If parser is parsing a command's options, this will be the name of the
	/// command. For top-level results, this returns `null`.
	final String commandName;

	/// The parser for the supercommand of this command parser, or `null` if this
	/// is the top-level parser.
	final Parser parent;

	/// The grammar being parsed.
	final ArgParser grammar;

	/// The arguments being parsed.
	final List<String> args;

	/// The remaining non-option, non-command arguments.
	final rest = <String>[];

	/// The accumulated parsed options.
	final Map<String, dynamic> results = <String, dynamic>{};

	Parser(this.commandName, this.grammar, this.args, this.parent, rest) {
	if (rest != null) this.rest.addAll(rest);
	}

	/// The current argument being parsed.
	String get current => args[0];

	/// Parses the arguments. This can only be called once.
	ArgResults parse() {
	var arguments = args.toList();
	var commandResults = null;

	// Parse the args.
	while (args.length > 0) {
	if (current == '--') {
	// Reached the argument terminator, so stop here.
	args.removeAt(0);
	break;
	}

	// Try to parse the current argument as a command. This happens before
	// options so that commands can have option-like names.
	var command = grammar.commands[current];
	if (command != null) {
	validate(rest.isEmpty, 'Cannot specify arguments before a command.');
	var commandName = args.removeAt(0);
	var commandParser = new Parser(commandName, command, args, this, rest);
	commandResults = commandParser.parse();

	// All remaining arguments were passed to command so clear them here.
	rest.clear();
	break;
	}

	// Try to parse the current argument as an option. Note that the order
	// here matters.
	if (parseSoloOption()) continue;
	if (parseAbbreviation(this)) continue;
	if (parseLongOption()) continue;

	// This argument is neither option nor command, so stop parsing unless
	// the [allowTrailingOptions] option is set.
	if (!grammar.allowTrailingOptions) break;
	rest.add(args.removeAt(0));
	}

	// Invoke the callbacks.
	grammar.options.forEach((name, option) {
	if (option.callback == null) return;
	option.callback(option.getOrDefault(results[name]));
	});

	// Add in the leftover arguments we didn't parse to the innermost command.
	rest.addAll(args);
	args.clear();
	return newArgResults(
	grammar, results, commandName, commandResults, rest, arguments);
	}

	/// Pulls the value for [option] from the second argument in [args].
	///
	/// Validates that there is a valid value there.
	void readNextArgAsValue(Option option) {
	// Take the option argument from the next command line arg.
	validate(args.length > 0, 'Missing argument for "${option.name}".');

	// Make sure it isn't an option itself.
	validate(!_ABBR_OPT.hasMatch(current) && !_LONG_OPT.hasMatch(current),
	'Missing argument for "${option.name}".');

	setOption(results, option, current);
	args.removeAt(0);
	}

	/// Tries to parse the current argument as a "solo" option, which is a single
	/// hyphen followed by a single letter.
	///
	/// We treat this differently than collapsed abbreviations (like "-abc") to
	/// handle the possible value that may follow it.
	bool parseSoloOption() {
	var soloOpt = _SOLO_OPT.firstMatch(current);
	if (soloOpt == null) return false;

	var option = grammar.findByAbbreviation(soloOpt[1]);
	if (option == null) {
	// Walk up to the parent command if possible.
	validate(
	parent != null, 'Could not find an option or flag "-${soloOpt[1]}".');
	return parent.parseSoloOption();
	}

	args.removeAt(0);

	if (option.isFlag) {
	setOption(results, option, true);
	} else {
	readNextArgAsValue(option);
	}

	return true;
	}

	/// Tries to parse the current argument as a series of collapsed abbreviations
	/// (like "-abc") or a single abbreviation with the value directly attached
	/// to it (like "-mrelease").
	bool parseAbbreviation(Parser innermostCommand) {
	var abbrOpt = _ABBR_OPT.firstMatch(current);
	if (abbrOpt == null) return false;

	// If the first character is the abbreviation for a non-flag option, then
	// the rest is the value.
	var c = abbrOpt[1].substring(0, 1);
	var first = grammar.findByAbbreviation(c);
	if (first == null) {
	// Walk up to the parent command if possible.
	validate(
	parent != null, 'Could not find an option with short name "-$c".');
	return parent.parseAbbreviation(innermostCommand);
	} else if (!first.isFlag) {
	// The first character is a non-flag option, so the rest must be the
	// value.
	var value = '${abbrOpt[1].substring(1)}${abbrOpt[2]}';
	setOption(results, first, value);
	} else {
	// If we got some non-flag characters, then it must be a value, but
	// if we got here, it's a flag, which is wrong.
	validate(abbrOpt[2] == '',
	'Option "-$c" is a flag and cannot handle value '
	'"${abbrOpt[1].substring(1)}${abbrOpt[2]}".');

	// Not an option, so all characters should be flags.
	// We use "innermostCommand" here so that if a parent command parses the
	// first letter, subcommands can still be found to parse the other
	// letters.
	for (var i = 0; i < abbrOpt[1].length; i++) {
	var c = abbrOpt[1].substring(i, i + 1);
	innermostCommand.parseShortFlag(c);
	}
	}

	args.removeAt(0);
	return true;
	}

	void parseShortFlag(String c) {
	var option = grammar.findByAbbreviation(c);
	if (option == null) {
	// Walk up to the parent command if possible.
	validate(
	parent != null, 'Could not find an option with short name "-$c".');
	parent.parseShortFlag(c);
	return;
	}

	// In a list of short options, only the first can be a non-flag. If
	// we get here we've checked that already.
	validate(
	option.isFlag, 'Option "-$c" must be a flag to be in a collapsed "-".');

	setOption(results, option, true);
	}

	/// Tries to parse the current argument as a long-form named option, which
	/// may include a value like "--mode=release" or "--mode release".
	bool parseLongOption() {
	var longOpt = _LONG_OPT.firstMatch(current);
	if (longOpt == null) return false;

	var name = longOpt[1];
	var option = grammar.options[name];
	if (option != null) {
	args.removeAt(0);
	if (option.isFlag) {
	validate(longOpt[3] == null,
	'Flag option "$name" should not be given a value.');

	setOption(results, option, true);
	} else if (longOpt[3] != null) {
	// We have a value like --foo=bar.
	setOption(results, option, longOpt[3]);
	} else {
	// Option like --foo, so look for the value as the next arg.
	readNextArgAsValue(option);
	}
	} else if (name.startsWith('no-')) {
	// See if it's a negated flag.
	name = name.substring('no-'.length);
	option = grammar.options[name];
	if (option == null) {
	// Walk up to the parent command if possible.
	validate(parent != null, 'Could not find an option named "$name".');
	return parent.parseLongOption();
	}

	args.removeAt(0);
	validate(option.isFlag, 'Cannot negate non-flag option "$name".');
	validate(option.negatable, 'Cannot negate option "$name".');

	setOption(results, option, false);
	} else {
	// Walk up to the parent command if possible.
	validate(parent != null, 'Could not find an option named "$name".');
	return parent.parseLongOption();
	}

	return true;
	}

	/// Called during parsing to validate the arguments.
	///
	/// Throws a [FormatException] if [condition] is `false`.
	void validate(bool condition, String message) {
	if (!condition) throw new FormatException(message);
	}

	/// Validates and stores [value] as the value for [option].
	void setOption(Map results, Option option, value) {
	// See if it's one of the allowed values.
	if (option.allowed != null) {
	validate(option.allowed.any((allow) => allow == value),
	'"$value" is not an allowed value for option "${option.name}".');
	}

	if (option.isMultiple) {
	var list = results.putIfAbsent(option.name, () => []);
	list.add(value);
	} else {
	results[option.name] = value;
	}
	}
	}