1  /**
   2   * class ArgumentParser
   3   *
   4   * Object for parsing command line strings into js objects.
   5   *
   6   * Inherited from [[ActionContainer]]
   7   **/
   8  'use strict';
   9  
  10  var util    = require('util');
  11  var format  = require('util').format;
  12  var Path    = require('path');
  13  var sprintf = require('sprintf-js').sprintf;
  14  
  15  // Constants
  16  var c = require('./const');
  17  
  18  var $$ = require('./utils');
  19  
  20  var ActionContainer = require('./action_container');
  21  
  22  // Errors
  23  var argumentErrorHelper = require('./argument/error');
  24  
  25  var HelpFormatter = require('./help/formatter');
  26  
  27  var Namespace = require('./namespace');
  28  
  29  
  30  /**
  31   * new ArgumentParser(options)
  32   *
  33   * Create a new ArgumentParser object.
  34   *
  35   * ##### Options:
  36   * - `prog`  The name of the program (default: Path.basename(process.argv[1]))
  37   * - `usage`  A usage message (default: auto-generated from arguments)
  38   * - `description`  A description of what the program does
  39   * - `epilog`  Text following the argument descriptions
  40   * - `parents`  Parsers whose arguments should be copied into this one
  41   * - `formatterClass`  HelpFormatter class for printing help messages
  42   * - `prefixChars`  Characters that prefix optional arguments
  43   * - `fromfilePrefixChars` Characters that prefix files containing additional arguments
  44   * - `argumentDefault`  The default value for all arguments
  45   * - `addHelp`  Add a -h/-help option
  46   * - `conflictHandler`  Specifies how to handle conflicting argument names
  47   * - `debug`  Enable debug mode. Argument errors throw exception in
  48   *   debug mode and process.exit in normal. Used for development and
  49   *   testing (default: false)
  50   *
  51   * See also [original guide][1]
  52   *
  53   * [1]:http://docs.python.org/dev/library/argparse.html#argumentparser-objects
  54   **/
  55  function ArgumentParser(options) {
  56    if (!(this instanceof ArgumentParser)) {
  57      return new ArgumentParser(options);
  58    }
  59    var self = this;
  60    options = options || {};
  61  
  62    options.description = (options.description || null);
  63    options.argumentDefault = (options.argumentDefault || null);
  64    options.prefixChars = (options.prefixChars || '-');
  65    options.conflictHandler = (options.conflictHandler || 'error');
  66    ActionContainer.call(this, options);
  67  
  68    options.addHelp = typeof options.addHelp === 'undefined' || !!options.addHelp;
  69    options.parents = options.parents || [];
  70    // default program name
  71    options.prog = (options.prog || Path.basename(process.argv[1]));
  72    this.prog = options.prog;
  73    this.usage = options.usage;
  74    this.epilog = options.epilog;
  75    this.version = options.version;
  76  
  77    this.debug = (options.debug === true);
  78  
  79    this.formatterClass = (options.formatterClass || HelpFormatter);
  80    this.fromfilePrefixChars = options.fromfilePrefixChars || null;
  81    this._positionals = this.addArgumentGroup({ title: 'Positional arguments' });
  82    this._optionals = this.addArgumentGroup({ title: 'Optional arguments' });
  83    this._subparsers = null;
  84  
  85    // register types
  86    function FUNCTION_IDENTITY(o) {
  87      return o;
  88    }
  89    this.register('type', 'auto', FUNCTION_IDENTITY);
  90    this.register('type', null, FUNCTION_IDENTITY);
  91    this.register('type', 'int', function (x) {
  92      var result = parseInt(x, 10);
  93      if (isNaN(result)) {
  94        throw new Error(x + ' is not a valid integer.');
  95      }
  96      return result;
  97    });
  98    this.register('type', 'float', function (x) {
  99      var result = parseFloat(x);
 100      if (isNaN(result)) {
 101        throw new Error(x + ' is not a valid float.');
 102      }
 103      return result;
 104    });
 105    this.register('type', 'string', function (x) {
 106      return '' + x;
 107    });
 108  
 109    // add help and version arguments if necessary
 110    var defaultPrefix = (this.prefixChars.indexOf('-') > -1) ? '-' : this.prefixChars[0];
 111    if (options.addHelp) {
 112      this.addArgument(
 113        [ defaultPrefix + 'h', defaultPrefix + defaultPrefix + 'help' ],
 114        {
 115          action: 'help',
 116          defaultValue: c.SUPPRESS,
 117          help: 'Show this help message and exit.'
 118        }
 119      );
 120    }
 121    if (typeof this.version !== 'undefined') {
 122      this.addArgument(
 123        [ defaultPrefix + 'v', defaultPrefix + defaultPrefix + 'version' ],
 124        {
 125          action: 'version',
 126          version: this.version,
 127          defaultValue: c.SUPPRESS,
 128          help: "Show program's version number and exit."
 129        }
 130      );
 131    }
 132  
 133    // add parent arguments and defaults
 134    options.parents.forEach(function (parent) {
 135      self._addContainerActions(parent);
 136      if (typeof parent._defaults !== 'undefined') {
 137        for (var defaultKey in parent._defaults) {
 138          if (parent._defaults.hasOwnProperty(defaultKey)) {
 139            self._defaults[defaultKey] = parent._defaults[defaultKey];
 140          }
 141        }
 142      }
 143    });
 144  }
 145  
 146  util.inherits(ArgumentParser, ActionContainer);
 147  
 148  /**
 149   * ArgumentParser#addSubparsers(options) -> [[ActionSubparsers]]
 150   * - options (object): hash of options see [[ActionSubparsers.new]]
 151   *
 152   * See also [subcommands][1]
 153   *
 154   * [1]:http://docs.python.org/dev/library/argparse.html#sub-commands
 155   **/
 156  ArgumentParser.prototype.addSubparsers = function (options) {
 157    if (this._subparsers) {
 158      this.error('Cannot have multiple subparser arguments.');
 159    }
 160  
 161    options = options || {};
 162    options.debug = (this.debug === true);
 163    options.optionStrings = [];
 164    options.parserClass = (options.parserClass || ArgumentParser);
 165  
 166  
 167    if (!!options.title || !!options.description) {
 168  
 169      this._subparsers = this.addArgumentGroup({
 170        title: (options.title || 'subcommands'),
 171        description: options.description
 172      });
 173      delete options.title;
 174      delete options.description;
 175  
 176    } else {
 177      this._subparsers = this._positionals;
 178    }
 179  
 180    // prog defaults to the usage message of this parser, skipping
 181    // optional arguments and with no "usage:" prefix
 182    if (!options.prog) {
 183      var formatter = this._getFormatter();
 184      var positionals = this._getPositionalActions();
 185      var groups = this._mutuallyExclusiveGroups;
 186      formatter.addUsage(this.usage, positionals, groups, '');
 187      options.prog = formatter.formatHelp().trim();
 188    }
 189  
 190    // create the parsers action and add it to the positionals list
 191    var ParsersClass = this._popActionClass(options, 'parsers');
 192    var action = new ParsersClass(options);
 193    this._subparsers._addAction(action);
 194  
 195    // return the created parsers action
 196    return action;
 197  };
 198  
 199  ArgumentParser.prototype._addAction = function (action) {
 200    if (action.isOptional()) {
 201      this._optionals._addAction(action);
 202    } else {
 203      this._positionals._addAction(action);
 204    }
 205    return action;
 206  };
 207  
 208  ArgumentParser.prototype._getOptionalActions = function () {
 209    return this._actions.filter(function (action) {
 210      return action.isOptional();
 211    });
 212  };
 213  
 214  ArgumentParser.prototype._getPositionalActions = function () {
 215    return this._actions.filter(function (action) {
 216      return action.isPositional();
 217    });
 218  };
 219  
 220  
 221  /**
 222   * ArgumentParser#parseArgs(args, namespace) -> Namespace|Object
 223   * - args (array): input elements
 224   * - namespace (Namespace|Object): result object
 225   *
 226   * Parsed args and throws error if some arguments are not recognized
 227   *
 228   * See also [original guide][1]
 229   *
 230   * [1]:http://docs.python.org/dev/library/argparse.html#the-parse-args-method
 231   **/
 232  ArgumentParser.prototype.parseArgs = function (args, namespace) {
 233    var argv;
 234    var result = this.parseKnownArgs(args, namespace);
 235  
 236    args = result[0];
 237    argv = result[1];
 238    if (argv && argv.length > 0) {
 239      this.error(
 240        format('Unrecognized arguments: %s.', argv.join(' '))
 241      );
 242    }
 243    return args;
 244  };
 245  
 246  /**
 247   * ArgumentParser#parseKnownArgs(args, namespace) -> array
 248   * - args (array): input options
 249   * - namespace (Namespace|Object): result object
 250   *
 251   * Parse known arguments and return tuple of result object
 252   * and unknown args
 253   *
 254   * See also [original guide][1]
 255   *
 256   * [1]:http://docs.python.org/dev/library/argparse.html#partial-parsing
 257   **/
 258  ArgumentParser.prototype.parseKnownArgs = function (args, namespace) {
 259    var self = this;
 260  
 261    // args default to the system args
 262    args = args || process.argv.slice(2);
 263  
 264    // default Namespace built from parser defaults
 265    namespace = namespace || new Namespace();
 266  
 267    self._actions.forEach(function (action) {
 268      if (action.dest !== c.SUPPRESS) {
 269        if (!$$.has(namespace, action.dest)) {
 270          if (action.defaultValue !== c.SUPPRESS) {
 271            var defaultValue = action.defaultValue;
 272            if (typeof action.defaultValue === 'string') {
 273              defaultValue = self._getValue(action, defaultValue);
 274            }
 275            namespace[action.dest] = defaultValue;
 276          }
 277        }
 278      }
 279    });
 280  
 281    Object.keys(self._defaults).forEach(function (dest) {
 282      namespace[dest] = self._defaults[dest];
 283    });
 284  
 285    // parse the arguments and exit if there are any errors
 286    try {
 287      var res = this._parseKnownArgs(args, namespace);
 288  
 289      namespace = res[0];
 290      args = res[1];
 291      if ($$.has(namespace, c._UNRECOGNIZED_ARGS_ATTR)) {
 292        args = $$.arrayUnion(args, namespace[c._UNRECOGNIZED_ARGS_ATTR]);
 293        delete namespace[c._UNRECOGNIZED_ARGS_ATTR];
 294      }
 295      return [ namespace, args ];
 296    } catch (e) {
 297      this.error(e);
 298    }
 299  };
 300  
 301  ArgumentParser.prototype._parseKnownArgs = function (argStrings, namespace) {
 302    var self = this;
 303  
 304    var extras = [];
 305  
 306    // replace arg strings that are file references
 307    if (this.fromfilePrefixChars !== null) {
 308      argStrings = this._readArgsFromFiles(argStrings);
 309    }
 310    // map all mutually exclusive arguments to the other arguments
 311    // they can't occur with
 312    // Python has 'conflicts = action_conflicts.setdefault(mutex_action, [])'
 313    // though I can't conceive of a way in which an action could be a member
 314    // of two different mutually exclusive groups.
 315  
 316    function actionHash(action) {
 317      // some sort of hashable key for this action
 318      // action itself cannot be a key in actionConflicts
 319      // I think getName() (join of optionStrings) is unique enough
 320      return action.getName();
 321    }
 322  
 323    var conflicts, key;
 324    var actionConflicts = {};
 325  
 326    this._mutuallyExclusiveGroups.forEach(function (mutexGroup) {
 327      mutexGroup._groupActions.forEach(function (mutexAction, i, groupActions) {
 328        key = actionHash(mutexAction);
 329        if (!$$.has(actionConflicts, key)) {
 330          actionConflicts[key] = [];
 331        }
 332        conflicts = actionConflicts[key];
 333        conflicts.push.apply(conflicts, groupActions.slice(0, i));
 334        conflicts.push.apply(conflicts, groupActions.slice(i + 1));
 335      });
 336    });
 337  
 338    // find all option indices, and determine the arg_string_pattern
 339    // which has an 'O' if there is an option at an index,
 340    // an 'A' if there is an argument, or a '-' if there is a '--'
 341    var optionStringIndices = {};
 342  
 343    var argStringPatternParts = [];
 344  
 345    argStrings.forEach(function (argString, argStringIndex) {
 346      if (argString === '--') {
 347        argStringPatternParts.push('-');
 348        while (argStringIndex < argStrings.length) {
 349          argStringPatternParts.push('A');
 350          argStringIndex++;
 351        }
 352      } else {
 353        // otherwise, add the arg to the arg strings
 354        // and note the index if it was an option
 355        var pattern;
 356        var optionTuple = self._parseOptional(argString);
 357        if (!optionTuple) {
 358          pattern = 'A';
 359        } else {
 360          optionStringIndices[argStringIndex] = optionTuple;
 361          pattern = 'O';
 362        }
 363        argStringPatternParts.push(pattern);
 364      }
 365    });
 366    var argStringsPattern = argStringPatternParts.join('');
 367  
 368    var seenActions = [];
 369    var seenNonDefaultActions = [];
 370  
 371  
 372    function takeAction(action, argumentStrings, optionString) {
 373      seenActions.push(action);
 374      var argumentValues = self._getValues(action, argumentStrings);
 375  
 376      // error if this argument is not allowed with other previously
 377      // seen arguments, assuming that actions that use the default
 378      // value don't really count as "present"
 379      if (argumentValues !== action.defaultValue) {
 380        seenNonDefaultActions.push(action);
 381        if (actionConflicts[actionHash(action)]) {
 382          actionConflicts[actionHash(action)].forEach(function (actionConflict) {
 383            if (seenNonDefaultActions.indexOf(actionConflict) >= 0) {
 384              throw argumentErrorHelper(
 385                action,
 386                format('Not allowed with argument "%s".', actionConflict.getName())
 387              );
 388            }
 389          });
 390        }
 391      }
 392  
 393      if (argumentValues !== c.SUPPRESS) {
 394        action.call(self, namespace, argumentValues, optionString);
 395      }
 396    }
 397  
 398    function consumeOptional(startIndex) {
 399      // get the optional identified at this index
 400      var optionTuple = optionStringIndices[startIndex];
 401      var action = optionTuple[0];
 402      var optionString = optionTuple[1];
 403      var explicitArg = optionTuple[2];
 404  
 405      // identify additional optionals in the same arg string
 406      // (e.g. -xyz is the same as -x -y -z if no args are required)
 407      var actionTuples = [];
 408  
 409      var args, argCount, start, stop;
 410  
 411      for (;;) {
 412        if (!action) {
 413          extras.push(argStrings[startIndex]);
 414          return startIndex + 1;
 415        }
 416        if (explicitArg) {
 417          argCount = self._matchArgument(action, 'A');
 418  
 419          // if the action is a single-dash option and takes no
 420          // arguments, try to parse more single-dash options out
 421          // of the tail of the option string
 422          var chars = self.prefixChars;
 423          if (argCount === 0 && chars.indexOf(optionString[1]) < 0) {
 424            actionTuples.push([ action, [], optionString ]);
 425            optionString = optionString[0] + explicitArg[0];
 426            var newExplicitArg = explicitArg.slice(1) || null;
 427            var optionalsMap = self._optionStringActions;
 428  
 429            if (Object.keys(optionalsMap).indexOf(optionString) >= 0) {
 430              action = optionalsMap[optionString];
 431              explicitArg = newExplicitArg;
 432            } else {
 433              throw argumentErrorHelper(action, sprintf('ignored explicit argument %r', explicitArg));
 434            }
 435          } else if (argCount === 1) {
 436            // if the action expect exactly one argument, we've
 437            // successfully matched the option; exit the loop
 438            stop = startIndex + 1;
 439            args = [ explicitArg ];
 440            actionTuples.push([ action, args, optionString ]);
 441            break;
 442          } else {
 443            // error if a double-dash option did not use the
 444            // explicit argument
 445            throw argumentErrorHelper(action, sprintf('ignored explicit argument %r', explicitArg));
 446          }
 447        } else {
 448          // if there is no explicit argument, try to match the
 449          // optional's string arguments with the following strings
 450          // if successful, exit the loop
 451  
 452          start = startIndex + 1;
 453          var selectedPatterns = argStringsPattern.substr(start);
 454  
 455          argCount = self._matchArgument(action, selectedPatterns);
 456          stop = start + argCount;
 457  
 458  
 459          args = argStrings.slice(start, stop);
 460  
 461          actionTuples.push([ action, args, optionString ]);
 462          break;
 463        }
 464  
 465      }
 466  
 467      // add the Optional to the list and return the index at which
 468      // the Optional's string args stopped
 469      if (actionTuples.length < 1) {
 470        throw new Error('length should be > 0');
 471      }
 472      for (var i = 0; i < actionTuples.length; i++) {
 473        takeAction.apply(self, actionTuples[i]);
 474      }
 475      return stop;
 476    }
 477  
 478    // the list of Positionals left to be parsed; this is modified
 479    // by consume_positionals()
 480    var positionals = self._getPositionalActions();
 481  
 482    function consumePositionals(startIndex) {
 483      // match as many Positionals as possible
 484      var selectedPattern = argStringsPattern.substr(startIndex);
 485      var argCounts = self._matchArgumentsPartial(positionals, selectedPattern);
 486  
 487      // slice off the appropriate arg strings for each Positional
 488      // and add the Positional and its args to the list
 489      for (var i = 0; i < positionals.length; i++) {
 490        var action = positionals[i];
 491        var argCount = argCounts[i];
 492        if (typeof argCount === 'undefined') {
 493          continue;
 494        }
 495        var args = argStrings.slice(startIndex, startIndex + argCount);
 496  
 497        startIndex += argCount;
 498        takeAction(action, args);
 499      }
 500  
 501      // slice off the Positionals that we just parsed and return the
 502      // index at which the Positionals' string args stopped
 503      positionals = positionals.slice(argCounts.length);
 504      return startIndex;
 505    }
 506  
 507    // consume Positionals and Optionals alternately, until we have
 508    // passed the last option string
 509    var startIndex = 0;
 510    var position;
 511  
 512    var maxOptionStringIndex = -1;
 513  
 514    Object.keys(optionStringIndices).forEach(function (position) {
 515      maxOptionStringIndex = Math.max(maxOptionStringIndex, parseInt(position, 10));
 516    });
 517  
 518    var positionalsEndIndex, nextOptionStringIndex;
 519  
 520    while (startIndex <= maxOptionStringIndex) {
 521      // consume any Positionals preceding the next option
 522      nextOptionStringIndex = null;
 523      for (position in optionStringIndices) {
 524        if (!optionStringIndices.hasOwnProperty(position)) { continue; }
 525  
 526        position = parseInt(position, 10);
 527        if (position >= startIndex) {
 528          if (nextOptionStringIndex !== null) {
 529            nextOptionStringIndex = Math.min(nextOptionStringIndex, position);
 530          } else {
 531            nextOptionStringIndex = position;
 532          }
 533        }
 534      }
 535  
 536      if (startIndex !== nextOptionStringIndex) {
 537        positionalsEndIndex = consumePositionals(startIndex);
 538        // only try to parse the next optional if we didn't consume
 539        // the option string during the positionals parsing
 540        if (positionalsEndIndex > startIndex) {
 541          startIndex = positionalsEndIndex;
 542          continue;
 543        } else {
 544          startIndex = positionalsEndIndex;
 545        }
 546      }
 547  
 548      // if we consumed all the positionals we could and we're not
 549      // at the index of an option string, there were extra arguments
 550      if (!optionStringIndices[startIndex]) {
 551        var strings = argStrings.slice(startIndex, nextOptionStringIndex);
 552        extras = extras.concat(strings);
 553        startIndex = nextOptionStringIndex;
 554      }
 555      // consume the next optional and any arguments for it
 556      startIndex = consumeOptional(startIndex);
 557    }
 558  
 559    // consume any positionals following the last Optional
 560    var stopIndex = consumePositionals(startIndex);
 561  
 562    // if we didn't consume all the argument strings, there were extras
 563    extras = extras.concat(argStrings.slice(stopIndex));
 564  
 565    // if we didn't use all the Positional objects, there were too few
 566    // arg strings supplied.
 567    if (positionals.length > 0) {
 568      self.error('too few arguments');
 569    }
 570  
 571    // make sure all required actions were present
 572    self._actions.forEach(function (action) {
 573      if (action.required) {
 574        if (seenActions.indexOf(action) < 0) {
 575          self.error(format('Argument "%s" is required', action.getName()));
 576        }
 577      }
 578    });
 579  
 580    // make sure all required groups have one option present
 581    var actionUsed = false;
 582    self._mutuallyExclusiveGroups.forEach(function (group) {
 583      if (group.required) {
 584        actionUsed = group._groupActions.some(function (action) {
 585          return seenNonDefaultActions.indexOf(action) !== -1;
 586        });
 587  
 588        // if no actions were used, report the error
 589        if (!actionUsed) {
 590          var names = [];
 591          group._groupActions.forEach(function (action) {
 592            if (action.help !== c.SUPPRESS) {
 593              names.push(action.getName());
 594            }
 595          });
 596          names = names.join(' ');
 597          var msg = 'one of the arguments ' + names + ' is required';
 598          self.error(msg);
 599        }
 600      }
 601    });
 602  
 603    // return the updated namespace and the extra arguments
 604    return [ namespace, extras ];
 605  };
 606  
 607  ArgumentParser.prototype._readArgsFromFiles = function (argStrings) {
 608    // expand arguments referencing files
 609    var self = this;
 610    var fs = require('fs');
 611    var newArgStrings = [];
 612    argStrings.forEach(function (argString) {
 613      if (self.fromfilePrefixChars.indexOf(argString[0]) < 0) {
 614        // for regular arguments, just add them back into the list
 615        newArgStrings.push(argString);
 616      } else {
 617        // replace arguments referencing files with the file content
 618        try {
 619          var argstrs = [];
 620          var filename = argString.slice(1);
 621          var content = fs.readFileSync(filename, 'utf8');
 622          content = content.trim().split('\n');
 623          content.forEach(function (argLine) {
 624            self.convertArgLineToArgs(argLine).forEach(function (arg) {
 625              argstrs.push(arg);
 626            });
 627            argstrs = self._readArgsFromFiles(argstrs);
 628          });
 629          newArgStrings.push.apply(newArgStrings, argstrs);
 630        } catch (error) {
 631          return self.error(error.message);
 632        }
 633      }
 634    });
 635    return newArgStrings;
 636  };
 637  
 638  ArgumentParser.prototype.convertArgLineToArgs = function (argLine) {
 639    return [ argLine ];
 640  };
 641  
 642  ArgumentParser.prototype._matchArgument = function (action, regexpArgStrings) {
 643  
 644    // match the pattern for this action to the arg strings
 645    var regexpNargs = new RegExp('^' + this._getNargsPattern(action));
 646    var matches = regexpArgStrings.match(regexpNargs);
 647    var message;
 648  
 649    // throw an exception if we weren't able to find a match
 650    if (!matches) {
 651      switch (action.nargs) {
 652        /*eslint-disable no-undefined*/
 653        case undefined:
 654        case null:
 655          message = 'Expected one argument.';
 656          break;
 657        case c.OPTIONAL:
 658          message = 'Expected at most one argument.';
 659          break;
 660        case c.ONE_OR_MORE:
 661          message = 'Expected at least one argument.';
 662          break;
 663        default:
 664          message = 'Expected %s argument(s)';
 665      }
 666  
 667      throw argumentErrorHelper(
 668        action,
 669        format(message, action.nargs)
 670      );
 671    }
 672    // return the number of arguments matched
 673    return matches[1].length;
 674  };
 675  
 676  ArgumentParser.prototype._matchArgumentsPartial = function (actions, regexpArgStrings) {
 677    // progressively shorten the actions list by slicing off the
 678    // final actions until we find a match
 679    var self = this;
 680    var result = [];
 681    var actionSlice, pattern, matches;
 682    var i, j;
 683  
 684    function getLength(string) {
 685      return string.length;
 686    }
 687  
 688    for (i = actions.length; i > 0; i--) {
 689      pattern = '';
 690      actionSlice = actions.slice(0, i);
 691      for (j = 0; j < actionSlice.length; j++) {
 692        pattern += self._getNargsPattern(actionSlice[j]);
 693      }
 694  
 695      pattern = new RegExp('^' + pattern);
 696      matches = regexpArgStrings.match(pattern);
 697  
 698      if (matches && matches.length > 0) {
 699        // need only groups
 700        matches = matches.splice(1);
 701        result = result.concat(matches.map(getLength));
 702        break;
 703      }
 704    }
 705  
 706    // return the list of arg string counts
 707    return result;
 708  };
 709  
 710  ArgumentParser.prototype._parseOptional = function (argString) {
 711    var action, optionString, argExplicit, optionTuples;
 712  
 713    // if it's an empty string, it was meant to be a positional
 714    if (!argString) {
 715      return null;
 716    }
 717  
 718    // if it doesn't start with a prefix, it was meant to be positional
 719    if (this.prefixChars.indexOf(argString[0]) < 0) {
 720      return null;
 721    }
 722  
 723    // if the option string is present in the parser, return the action
 724    if (this._optionStringActions[argString]) {
 725      return [ this._optionStringActions[argString], argString, null ];
 726    }
 727  
 728    // if it's just a single character, it was meant to be positional
 729    if (argString.length === 1) {
 730      return null;
 731    }
 732  
 733    // if the option string before the "=" is present, return the action
 734    if (argString.indexOf('=') >= 0) {
 735      optionString = argString.split('=', 1)[0];
 736      argExplicit = argString.slice(optionString.length + 1);
 737  
 738      if (this._optionStringActions[optionString]) {
 739        action = this._optionStringActions[optionString];
 740        return [ action, optionString, argExplicit ];
 741      }
 742    }
 743  
 744    // search through all possible prefixes of the option string
 745    // and all actions in the parser for possible interpretations
 746    optionTuples = this._getOptionTuples(argString);
 747  
 748    // if multiple actions match, the option string was ambiguous
 749    if (optionTuples.length > 1) {
 750      var optionStrings = optionTuples.map(function (optionTuple) {
 751        return optionTuple[1];
 752      });
 753      this.error(format(
 754            'Ambiguous option: "%s" could match %s.',
 755            argString, optionStrings.join(', ')
 756      ));
 757    // if exactly one action matched, this segmentation is good,
 758    // so return the parsed action
 759    } else if (optionTuples.length === 1) {
 760      return optionTuples[0];
 761    }
 762  
 763    // if it was not found as an option, but it looks like a negative
 764    // number, it was meant to be positional
 765    // unless there are negative-number-like options
 766    if (argString.match(this._regexpNegativeNumber)) {
 767      if (!this._hasNegativeNumberOptionals.some(Boolean)) {
 768        return null;
 769      }
 770    }
 771    // if it contains a space, it was meant to be a positional
 772    if (argString.search(' ') >= 0) {
 773      return null;
 774    }
 775  
 776    // it was meant to be an optional but there is no such option
 777    // in this parser (though it might be a valid option in a subparser)
 778    return [ null, argString, null ];
 779  };
 780  
 781  ArgumentParser.prototype._getOptionTuples = function (optionString) {
 782    var result = [];
 783    var chars = this.prefixChars;
 784    var optionPrefix;
 785    var argExplicit;
 786    var action;
 787    var actionOptionString;
 788  
 789    // option strings starting with two prefix characters are only split at
 790    // the '='
 791    if (chars.indexOf(optionString[0]) >= 0 && chars.indexOf(optionString[1]) >= 0) {
 792      if (optionString.indexOf('=') >= 0) {
 793        var optionStringSplit = optionString.split('=', 1);
 794  
 795        optionPrefix = optionStringSplit[0];
 796        argExplicit = optionStringSplit[1];
 797      } else {
 798        optionPrefix = optionString;
 799        argExplicit = null;
 800      }
 801  
 802      for (actionOptionString in this._optionStringActions) {
 803        if (actionOptionString.substr(0, optionPrefix.length) === optionPrefix) {
 804          action = this._optionStringActions[actionOptionString];
 805          result.push([ action, actionOptionString, argExplicit ]);
 806        }
 807      }
 808  
 809    // single character options can be concatenated with their arguments
 810    // but multiple character options always have to have their argument
 811    // separate
 812    } else if (chars.indexOf(optionString[0]) >= 0 && chars.indexOf(optionString[1]) < 0) {
 813      optionPrefix = optionString;
 814      argExplicit = null;
 815      var optionPrefixShort = optionString.substr(0, 2);
 816      var argExplicitShort = optionString.substr(2);
 817  
 818      for (actionOptionString in this._optionStringActions) {
 819        if (!$$.has(this._optionStringActions, actionOptionString)) continue;
 820  
 821        action = this._optionStringActions[actionOptionString];
 822        if (actionOptionString === optionPrefixShort) {
 823          result.push([ action, actionOptionString, argExplicitShort ]);
 824        } else if (actionOptionString.substr(0, optionPrefix.length) === optionPrefix) {
 825          result.push([ action, actionOptionString, argExplicit ]);
 826        }
 827      }
 828  
 829    // shouldn't ever get here
 830    } else {
 831      throw new Error(format('Unexpected option string: %s.', optionString));
 832    }
 833    // return the collected option tuples
 834    return result;
 835  };
 836  
 837  ArgumentParser.prototype._getNargsPattern = function (action) {
 838    // in all examples below, we have to allow for '--' args
 839    // which are represented as '-' in the pattern
 840    var regexpNargs;
 841  
 842    switch (action.nargs) {
 843      // the default (null) is assumed to be a single argument
 844      case undefined:
 845      case null:
 846        regexpNargs = '(-*A-*)';
 847        break;
 848      // allow zero or more arguments
 849      case c.OPTIONAL:
 850        regexpNargs = '(-*A?-*)';
 851        break;
 852      // allow zero or more arguments
 853      case c.ZERO_OR_MORE:
 854        regexpNargs = '(-*[A-]*)';
 855        break;
 856      // allow one or more arguments
 857      case c.ONE_OR_MORE:
 858        regexpNargs = '(-*A[A-]*)';
 859        break;
 860      // allow any number of options or arguments
 861      case c.REMAINDER:
 862        regexpNargs = '([-AO]*)';
 863        break;
 864      // allow one argument followed by any number of options or arguments
 865      case c.PARSER:
 866        regexpNargs = '(-*A[-AO]*)';
 867        break;
 868      // all others should be integers
 869      default:
 870        regexpNargs = '(-*' + $$.repeat('-*A', action.nargs) + '-*)';
 871    }
 872  
 873    // if this is an optional action, -- is not allowed
 874    if (action.isOptional()) {
 875      regexpNargs = regexpNargs.replace(/-\*/g, '');
 876      regexpNargs = regexpNargs.replace(/-/g, '');
 877    }
 878  
 879    // return the pattern
 880    return regexpNargs;
 881  };
 882  
 883  //
 884  // Value conversion methods
 885  //
 886  
 887  ArgumentParser.prototype._getValues = function (action, argStrings) {
 888    var self = this;
 889  
 890    // for everything but PARSER args, strip out '--'
 891    if (action.nargs !== c.PARSER && action.nargs !== c.REMAINDER) {
 892      argStrings = argStrings.filter(function (arrayElement) {
 893        return arrayElement !== '--';
 894      });
 895    }
 896  
 897    var value, argString;
 898  
 899    // optional argument produces a default when not present
 900    if (argStrings.length === 0 && action.nargs === c.OPTIONAL) {
 901  
 902      value = (action.isOptional()) ? action.constant : action.defaultValue;
 903  
 904      if (typeof (value) === 'string') {
 905        value = this._getValue(action, value);
 906        this._checkValue(action, value);
 907      }
 908  
 909    // when nargs='*' on a positional, if there were no command-line
 910    // args, use the default if it is anything other than None
 911    } else if (argStrings.length === 0 && action.nargs === c.ZERO_OR_MORE &&
 912      action.optionStrings.length === 0) {
 913  
 914      value = (action.defaultValue || argStrings);
 915      this._checkValue(action, value);
 916  
 917    // single argument or optional argument produces a single value
 918    } else if (argStrings.length === 1 &&
 919          (!action.nargs || action.nargs === c.OPTIONAL)) {
 920  
 921      argString = argStrings[0];
 922      value = this._getValue(action, argString);
 923      this._checkValue(action, value);
 924  
 925    // REMAINDER arguments convert all values, checking none
 926    } else if (action.nargs === c.REMAINDER) {
 927      value = argStrings.map(function (v) {
 928        return self._getValue(action, v);
 929      });
 930  
 931    // PARSER arguments convert all values, but check only the first
 932    } else if (action.nargs === c.PARSER) {
 933      value = argStrings.map(function (v) {
 934        return self._getValue(action, v);
 935      });
 936      this._checkValue(action, value[0]);
 937  
 938    // all other types of nargs produce a list
 939    } else {
 940      value = argStrings.map(function (v) {
 941        return self._getValue(action, v);
 942      });
 943      value.forEach(function (v) {
 944        self._checkValue(action, v);
 945      });
 946    }
 947  
 948    // return the converted value
 949    return value;
 950  };
 951  
 952  ArgumentParser.prototype._getValue = function (action, argString) {
 953    var result;
 954  
 955    var typeFunction = this._registryGet('type', action.type, action.type);
 956    if (typeof typeFunction !== 'function') {
 957      var message = format('%s is not callable', typeFunction);
 958      throw argumentErrorHelper(action, message);
 959    }
 960  
 961    // convert the value to the appropriate type
 962    try {
 963      result = typeFunction(argString);
 964  
 965      // ArgumentTypeErrors indicate errors
 966      // If action.type is not a registered string, it is a function
 967      // Try to deduce its name for inclusion in the error message
 968      // Failing that, include the error message it raised.
 969    } catch (e) {
 970      var name = null;
 971      if (typeof action.type === 'string') {
 972        name = action.type;
 973      } else {
 974        name = action.type.name || action.type.displayName || '<function>';
 975      }
 976      var msg = format('Invalid %s value: %s', name, argString);
 977      if (name === '<function>') { msg += '\n' + e.message; }
 978      throw argumentErrorHelper(action, msg);
 979    }
 980    // return the converted value
 981    return result;
 982  };
 983  
 984  ArgumentParser.prototype._checkValue = function (action, value) {
 985    // converted value must be one of the choices (if specified)
 986    var choices = action.choices;
 987    if (choices) {
 988      // choise for argument can by array or string
 989      if ((typeof choices === 'string' || Array.isArray(choices)) &&
 990          choices.indexOf(value) !== -1) {
 991        return;
 992      }
 993      // choise for subparsers can by only hash
 994      if (typeof choices === 'object' && !Array.isArray(choices) && choices[value]) {
 995        return;
 996      }
 997  
 998      if (typeof choices === 'string') {
 999        choices = choices.split('').join(', ');
1000      } else if (Array.isArray(choices)) {
1001        choices =  choices.join(', ');
1002      } else {
1003        choices =  Object.keys(choices).join(', ');
1004      }
1005      var message = format('Invalid choice: %s (choose from [%s])', value, choices);
1006      throw argumentErrorHelper(action, message);
1007    }
1008  };
1009  
1010  //
1011  // Help formatting methods
1012  //
1013  
1014  /**
1015   * ArgumentParser#formatUsage -> string
1016   *
1017   * Return usage string
1018   *
1019   * See also [original guide][1]
1020   *
1021   * [1]:http://docs.python.org/dev/library/argparse.html#printing-help
1022   **/
1023  ArgumentParser.prototype.formatUsage = function () {
1024    var formatter = this._getFormatter();
1025    formatter.addUsage(this.usage, this._actions, this._mutuallyExclusiveGroups);
1026    return formatter.formatHelp();
1027  };
1028  
1029  /**
1030   * ArgumentParser#formatHelp -> string
1031   *
1032   * Return help
1033   *
1034   * See also [original guide][1]
1035   *
1036   * [1]:http://docs.python.org/dev/library/argparse.html#printing-help
1037   **/
1038  ArgumentParser.prototype.formatHelp = function () {
1039    var formatter = this._getFormatter();
1040  
1041    // usage
1042    formatter.addUsage(this.usage, this._actions, this._mutuallyExclusiveGroups);
1043  
1044    // description
1045    formatter.addText(this.description);
1046  
1047    // positionals, optionals and user-defined groups
1048    this._actionGroups.forEach(function (actionGroup) {
1049      formatter.startSection(actionGroup.title);
1050      formatter.addText(actionGroup.description);
1051      formatter.addArguments(actionGroup._groupActions);
1052      formatter.endSection();
1053    });
1054  
1055    // epilog
1056    formatter.addText(this.epilog);
1057  
1058    // determine help from format above
1059    return formatter.formatHelp();
1060  };
1061  
1062  ArgumentParser.prototype._getFormatter = function () {
1063    var FormatterClass = this.formatterClass;
1064    var formatter = new FormatterClass({ prog: this.prog });
1065    return formatter;
1066  };
1067  
1068  //
1069  //  Print functions
1070  //
1071  
1072  /**
1073   * ArgumentParser#printUsage() -> Void
1074   *
1075   * Print usage
1076   *
1077   * See also [original guide][1]
1078   *
1079   * [1]:http://docs.python.org/dev/library/argparse.html#printing-help
1080   **/
1081  ArgumentParser.prototype.printUsage = function () {
1082    this._printMessage(this.formatUsage());
1083  };
1084  
1085  /**
1086   * ArgumentParser#printHelp() -> Void
1087   *
1088   * Print help
1089   *
1090   * See also [original guide][1]
1091   *
1092   * [1]:http://docs.python.org/dev/library/argparse.html#printing-help
1093   **/
1094  ArgumentParser.prototype.printHelp = function () {
1095    this._printMessage(this.formatHelp());
1096  };
1097  
1098  ArgumentParser.prototype._printMessage = function (message, stream) {
1099    if (!stream) {
1100      stream = process.stdout;
1101    }
1102    if (message) {
1103      stream.write('' + message);
1104    }
1105  };
1106  
1107  //
1108  //  Exit functions
1109  //
1110  
1111  /**
1112   * ArgumentParser#exit(status=0, message) -> Void
1113   * - status (int): exit status
1114   * - message (string): message
1115   *
1116   * Print message in stderr/stdout and exit program
1117   **/
1118  ArgumentParser.prototype.exit = function (status, message) {
1119    if (message) {
1120      if (status === 0) {
1121        this._printMessage(message);
1122      } else {
1123        this._printMessage(message, process.stderr);
1124      }
1125    }
1126  
1127    process.exit(status);
1128  };
1129  
1130  /**
1131   * ArgumentParser#error(message) -> Void
1132   * - err (Error|string): message
1133   *
1134   * Error method Prints a usage message incorporating the message to stderr and
1135   * exits. If you override this in a subclass,
1136   * it should not return -- it should
1137   * either exit or throw an exception.
1138   *
1139   **/
1140  ArgumentParser.prototype.error = function (err) {
1141    var message;
1142    if (err instanceof Error) {
1143      if (this.debug === true) {
1144        throw err;
1145      }
1146      message = err.message;
1147    } else {
1148      message = err;
1149    }
1150    var msg = format('%s: error: %s', this.prog, message) + c.EOL;
1151  
1152    if (this.debug === true) {
1153      throw new Error(msg);
1154    }
1155  
1156    this.printUsage(process.stderr);
1157  
1158    return this.exit(2, msg);
1159  };
1160  
1161  module.exports = ArgumentParser;