--- /dev/null
+/** 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);
+ }
+ });
+};
projects / dotfiles / .git / blobdiff