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