/** 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);
|
}
|
});
|
};
|
