l0bsterssg

action_container.js (15055B)

---

 /** internal
  * class ActionContainer
  *
  * Action container. Parent for [[ArgumentParser]] and [[ArgumentGroup]]
  **/
 
 'use strict';
 
 var format = require('util').format;
 
 // Constants
 var c = require('./const');
 
 var $$ = require('./utils');
 
 //Actions
 var ActionHelp = require('./action/help');
 var ActionAppend = require('./action/append');
 var ActionAppendConstant = require('./action/append/constant');
 var ActionCount = require('./action/count');
 var ActionStore = require('./action/store');
 var ActionStoreConstant = require('./action/store/constant');
 var ActionStoreTrue = require('./action/store/true');
 var ActionStoreFalse = require('./action/store/false');
 var ActionVersion = require('./action/version');
 var ActionSubparsers = require('./action/subparsers');
 
 // Errors
 var argumentErrorHelper = require('./argument/error');
 
 /**
  * new ActionContainer(options)
  *
  * Action container. Parent for [[ArgumentParser]] and [[ArgumentGroup]]
  *
  * ##### Options:
  *
  * - `description` -- A description of what the program does
  * - `prefixChars`  -- Characters that prefix optional arguments
  * - `argumentDefault`  -- The default value for all arguments
  * - `conflictHandler` -- The conflict handler to use for duplicate arguments
  **/
 var ActionContainer = module.exports = function ActionContainer(options) {
   options = options || {};
 
   this.description = options.description;
   this.argumentDefault = options.argumentDefault;
   this.prefixChars = options.prefixChars || '';
   this.conflictHandler = options.conflictHandler;
 
   // set up registries
   this._registries = {};
 
   // register actions
   this.register('action', null, ActionStore);
   this.register('action', 'store', ActionStore);
   this.register('action', 'storeConst', ActionStoreConstant);
   this.register('action', 'storeTrue', ActionStoreTrue);
   this.register('action', 'storeFalse', ActionStoreFalse);
   this.register('action', 'append', ActionAppend);
   this.register('action', 'appendConst', ActionAppendConstant);
   this.register('action', 'count', ActionCount);
   this.register('action', 'help', ActionHelp);
   this.register('action', 'version', ActionVersion);
   this.register('action', 'parsers', ActionSubparsers);
 
   // raise an exception if the conflict handler is invalid
   this._getHandler();
 
   // action storage
   this._actions = [];
   this._optionStringActions = {};
 
   // groups
   this._actionGroups = [];
   this._mutuallyExclusiveGroups = [];
 
   // defaults storage
   this._defaults = {};
 
   // determines whether an "option" looks like a negative number
   // -1, -1.5 -5e+4
   this._regexpNegativeNumber = new RegExp('^[-]?[0-9]*\\.?[0-9]+([eE][-+]?[0-9]+)?$');
 
   // whether or not there are any optionals that look like negative
   // numbers -- uses a list so it can be shared and edited
   this._hasNegativeNumberOptionals = [];
 };
 
 // Groups must be required, then ActionContainer already defined
 var ArgumentGroup = require('./argument/group');
 var MutuallyExclusiveGroup = require('./argument/exclusive');
 
 //
 // Registration methods
 //
 
 /**
  * ActionContainer#register(registryName, value, object) -> Void
  * - registryName (String) : object type action|type
  * - value (string) : keyword
  * - object (Object|Function) : handler
  *
  *  Register handlers
  **/
 ActionContainer.prototype.register = function (registryName, value, object) {
   this._registries[registryName] = this._registries[registryName] || {};
   this._registries[registryName][value] = object;
 };
 
 ActionContainer.prototype._registryGet = function (registryName, value, defaultValue) {
   if (arguments.length < 3) {
     defaultValue = null;
   }
   return this._registries[registryName][value] || defaultValue;
 };
 
 //
 // Namespace default accessor methods
 //
 
 /**
  * ActionContainer#setDefaults(options) -> Void
  * - options (object):hash of options see [[Action.new]]
  *
  * Set defaults
  **/
 ActionContainer.prototype.setDefaults = function (options) {
   options = options || {};
   for (var property in options) {
     if ($$.has(options, property)) {
       this._defaults[property] = options[property];
     }
   }
 
   // if these defaults match any existing arguments, replace the previous
   // default on the object with the new one
   this._actions.forEach(function (action) {
     if ($$.has(options, action.dest)) {
       action.defaultValue = options[action.dest];
     }
   });
 };
 
 /**
  * ActionContainer#getDefault(dest) -> Mixed
  * - dest (string): action destination
  *
  * Return action default value
  **/
 ActionContainer.prototype.getDefault = function (dest) {
   var result = $$.has(this._defaults, dest) ? this._defaults[dest] : null;
 
   this._actions.forEach(function (action) {
     if (action.dest === dest && $$.has(action, 'defaultValue')) {
       result = action.defaultValue;
     }
   });
 
   return result;
 };
 //
 // Adding argument actions
 //
 
 /**
  * ActionContainer#addArgument(args, options) -> Object
  * - args (String|Array): argument key, or array of argument keys
  * - options (Object): action objects see [[Action.new]]
  *
  * #### Examples
  * - addArgument([ '-f', '--foo' ], { action: 'store', defaultValue: 1, ... })
  * - addArgument([ 'bar' ], { action: 'store', nargs: 1, ... })
  * - addArgument('--baz', { action: 'store', nargs: 1, ... })
  **/
 ActionContainer.prototype.addArgument = function (args, options) {
   args = args;
   options = options || {};
 
   if (typeof args === 'string') {
     args = [ args ];
   }
   if (!Array.isArray(args)) {
     throw new TypeError('addArgument first argument should be a string or an array');
   }
   if (typeof options !== 'object' || Array.isArray(options)) {
     throw new TypeError('addArgument second argument should be a hash');
   }
 
   // if no positional args are supplied or only one is supplied and
   // it doesn't look like an option string, parse a positional argument
   if (!args || args.length === 1 && this.prefixChars.indexOf(args[0][0]) < 0) {
     if (args && !!options.dest) {
       throw new Error('dest supplied twice for positional argument');
     }
     options = this._getPositional(args, options);
 
     // otherwise, we're adding an optional argument
   } else {
     options = this._getOptional(args, options);
   }
 
   // if no default was supplied, use the parser-level default
   if (typeof options.defaultValue === 'undefined') {
     var dest = options.dest;
     if ($$.has(this._defaults, dest)) {
       options.defaultValue = this._defaults[dest];
     } else if (typeof this.argumentDefault !== 'undefined') {
       options.defaultValue = this.argumentDefault;
     }
   }
 
   // create the action object, and add it to the parser
   var ActionClass = this._popActionClass(options);
   if (typeof ActionClass !== 'function') {
     throw new Error(format('Unknown action "%s".', ActionClass));
   }
   var action = new ActionClass(options);
 
   // throw an error if the action type is not callable
   var typeFunction = this._registryGet('type', action.type, action.type);
   if (typeof typeFunction !== 'function') {
     throw new Error(format('"%s" is not callable', typeFunction));
   }
 
   return this._addAction(action);
 };
 
 /**
  * ActionContainer#addArgumentGroup(options) -> ArgumentGroup
  * - options (Object): hash of options see [[ArgumentGroup.new]]
  *
  * Create new arguments groups
  **/
 ActionContainer.prototype.addArgumentGroup = function (options) {
   var group = new ArgumentGroup(this, options);
   this._actionGroups.push(group);
   return group;
 };
 
 /**
  * ActionContainer#addMutuallyExclusiveGroup(options) -> ArgumentGroup
  * - options (Object): {required: false}
  *
  * Create new mutual exclusive groups
  **/
 ActionContainer.prototype.addMutuallyExclusiveGroup = function (options) {
   var group = new MutuallyExclusiveGroup(this, options);
   this._mutuallyExclusiveGroups.push(group);
   return group;
 };
 
 ActionContainer.prototype._addAction = function (action) {
   var self = this;
 
   // resolve any conflicts
   this._checkConflict(action);
 
   // add to actions list
   this._actions.push(action);
   action.container = this;
 
   // index the action by any option strings it has
   action.optionStrings.forEach(function (optionString) {
     self._optionStringActions[optionString] = action;
   });
 
   // set the flag if any option strings look like negative numbers
   action.optionStrings.forEach(function (optionString) {
     if (optionString.match(self._regexpNegativeNumber)) {
       if (!self._hasNegativeNumberOptionals.some(Boolean)) {
         self._hasNegativeNumberOptionals.push(true);
       }
     }
   });
 
   // return the created action
   return action;
 };
 
 ActionContainer.prototype._removeAction = function (action) {
   var actionIndex = this._actions.indexOf(action);
   if (actionIndex >= 0) {
     this._actions.splice(actionIndex, 1);
   }
 };
 
 ActionContainer.prototype._addContainerActions = function (container) {
   // collect groups by titles
   var titleGroupMap = {};
   this._actionGroups.forEach(function (group) {
     if (titleGroupMap[group.title]) {
       throw new Error(format('Cannot merge actions - two groups are named "%s".', group.title));
     }
     titleGroupMap[group.title] = group;
   });
 
   // map each action to its group
   var groupMap = {};
   function actionHash(action) {
     // unique (hopefully?) string suitable as dictionary key
     return action.getName();
   }
   container._actionGroups.forEach(function (group) {
     // if a group with the title exists, use that, otherwise
     // create a new group matching the container's group
     if (!titleGroupMap[group.title]) {
       titleGroupMap[group.title] = this.addArgumentGroup({
         title: group.title,
         description: group.description
       });
     }
 
     // map the actions to their new group
     group._groupActions.forEach(function (action) {
       groupMap[actionHash(action)] = titleGroupMap[group.title];
     });
   }, this);
 
   // add container's mutually exclusive groups
   // NOTE: if add_mutually_exclusive_group ever gains title= and
   // description= then this code will need to be expanded as above
   var mutexGroup;
   container._mutuallyExclusiveGroups.forEach(function (group) {
     mutexGroup = this.addMutuallyExclusiveGroup({
       required: group.required
     });
     // map the actions to their new mutex group
     group._groupActions.forEach(function (action) {
       groupMap[actionHash(action)] = mutexGroup;
     });
   }, this);  // forEach takes a 'this' argument
 
   // add all actions to this container or their group
   container._actions.forEach(function (action) {
     var key = actionHash(action);
     if (groupMap[key]) {
       groupMap[key]._addAction(action);
     } else {
       this._addAction(action);
     }
   });
 };
 
 ActionContainer.prototype._getPositional = function (dest, options) {
   if (Array.isArray(dest)) {
     dest = dest[0];
   }
   // make sure required is not specified
   if (options.required) {
     throw new Error('"required" is an invalid argument for positionals.');
   }
 
   // mark positional arguments as required if at least one is
   // always required
   if (options.nargs !== c.OPTIONAL && options.nargs !== c.ZERO_OR_MORE) {
     options.required = true;
   }
   if (options.nargs === c.ZERO_OR_MORE && typeof options.defaultValue === 'undefined') {
     options.required = true;
   }
 
   // return the keyword arguments with no option strings
   options.dest = dest;
   options.optionStrings = [];
   return options;
 };
 
 ActionContainer.prototype._getOptional = function (args, options) {
   var prefixChars = this.prefixChars;
   var optionStrings = [];
   var optionStringsLong = [];
 
   // determine short and long option strings
   args.forEach(function (optionString) {
     // error on strings that don't start with an appropriate prefix
     if (prefixChars.indexOf(optionString[0]) < 0) {
       throw new Error(format('Invalid option string "%s": must start with a "%s".',
         optionString,
         prefixChars
       ));
     }
 
     // strings starting with two prefix characters are long options
     optionStrings.push(optionString);
     if (optionString.length > 1 && prefixChars.indexOf(optionString[1]) >= 0) {
       optionStringsLong.push(optionString);
     }
   });
 
   // infer dest, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
   var dest = options.dest || null;
   delete options.dest;
 
   if (!dest) {
     var optionStringDest = optionStringsLong.length ? optionStringsLong[0] : optionStrings[0];
     dest = $$.trimChars(optionStringDest, this.prefixChars);
 
     if (dest.length === 0) {
       throw new Error(
         format('dest= is required for options like "%s"', optionStrings.join(', '))
       );
     }
     dest = dest.replace(/-/g, '_');
   }
 
   // return the updated keyword arguments
   options.dest = dest;
   options.optionStrings = optionStrings;
 
   return options;
 };
 
 ActionContainer.prototype._popActionClass = function (options, defaultValue) {
   defaultValue = defaultValue || null;
 
   var action = (options.action || defaultValue);
   delete options.action;
 
   var actionClass = this._registryGet('action', action, action);
   return actionClass;
 };
 
 ActionContainer.prototype._getHandler = function () {
   var handlerString = this.conflictHandler;
   var handlerFuncName = '_handleConflict' + $$.capitalize(handlerString);
   var func = this[handlerFuncName];
   if (typeof func === 'undefined') {
     var msg = 'invalid conflict resolution value: ' + handlerString;
     throw new Error(msg);
   } else {
     return func;
   }
 };
 
 ActionContainer.prototype._checkConflict = function (action) {
   var optionStringActions = this._optionStringActions;
   var conflictOptionals = [];
 
   // find all options that conflict with this option
   // collect pairs, the string, and an existing action that it conflicts with
   action.optionStrings.forEach(function (optionString) {
     var conflOptional = optionStringActions[optionString];
     if (typeof conflOptional !== 'undefined') {
       conflictOptionals.push([ optionString, conflOptional ]);
     }
   });
 
   if (conflictOptionals.length > 0) {
     var conflictHandler = this._getHandler();
     conflictHandler.call(this, action, conflictOptionals);
   }
 };
 
 ActionContainer.prototype._handleConflictError = function (action, conflOptionals) {
   var conflicts = conflOptionals.map(function (pair) { return pair[0]; });
   conflicts = conflicts.join(', ');
   throw argumentErrorHelper(
     action,
     format('Conflicting option string(s): %s', conflicts)
   );
 };
 
 ActionContainer.prototype._handleConflictResolve = function (action, conflOptionals) {
   // remove all conflicting options
   var self = this;
   conflOptionals.forEach(function (pair) {
     var optionString = pair[0];
     var conflictingAction = pair[1];
     // remove the conflicting option string
     var i = conflictingAction.optionStrings.indexOf(optionString);
     if (i >= 0) {
       conflictingAction.optionStrings.splice(i, 1);
     }
     delete self._optionStringActions[optionString];
     // if the option now has no option string, remove it from the
     // container holding it
     if (conflictingAction.optionStrings.length === 0) {
       conflictingAction.container._removeAction(conflictingAction);
     }
   });
 };