2 * class ActionContainer
4 * Action container. Parent for [[ArgumentParser]] and [[ArgumentGroup]]
9 var format = require('util').format;
12 var c = require('./const');
14 var $$ = require('./utils');
17 var ActionHelp = require('./action/help');
18 var ActionAppend = require('./action/append');
19 var ActionAppendConstant = require('./action/append/constant');
20 var ActionCount = require('./action/count');
21 var ActionStore = require('./action/store');
22 var ActionStoreConstant = require('./action/store/constant');
23 var ActionStoreTrue = require('./action/store/true');
24 var ActionStoreFalse = require('./action/store/false');
25 var ActionVersion = require('./action/version');
26 var ActionSubparsers = require('./action/subparsers');
29 var argumentErrorHelper = require('./argument/error');
32 * new ActionContainer(options)
34 * Action container. Parent for [[ArgumentParser]] and [[ArgumentGroup]]
38 * - `description` -- A description of what the program does
39 * - `prefixChars` -- Characters that prefix optional arguments
40 * - `argumentDefault` -- The default value for all arguments
41 * - `conflictHandler` -- The conflict handler to use for duplicate arguments
43 var ActionContainer = module.exports = function ActionContainer(options) {
44 options = options || {};
46 this.description = options.description;
47 this.argumentDefault = options.argumentDefault;
48 this.prefixChars = options.prefixChars || '';
49 this.conflictHandler = options.conflictHandler;
52 this._registries = {};
55 this.register('action', null, ActionStore);
56 this.register('action', 'store', ActionStore);
57 this.register('action', 'storeConst', ActionStoreConstant);
58 this.register('action', 'storeTrue', ActionStoreTrue);
59 this.register('action', 'storeFalse', ActionStoreFalse);
60 this.register('action', 'append', ActionAppend);
61 this.register('action', 'appendConst', ActionAppendConstant);
62 this.register('action', 'count', ActionCount);
63 this.register('action', 'help', ActionHelp);
64 this.register('action', 'version', ActionVersion);
65 this.register('action', 'parsers', ActionSubparsers);
67 // raise an exception if the conflict handler is invalid
72 this._optionStringActions = {};
75 this._actionGroups = [];
76 this._mutuallyExclusiveGroups = [];
81 // determines whether an "option" looks like a negative number
83 this._regexpNegativeNumber = new RegExp('^[-]?[0-9]*\\.?[0-9]+([eE][-+]?[0-9]+)?$');
85 // whether or not there are any optionals that look like negative
86 // numbers -- uses a list so it can be shared and edited
87 this._hasNegativeNumberOptionals = [];
90 // Groups must be required, then ActionContainer already defined
91 var ArgumentGroup = require('./argument/group');
92 var MutuallyExclusiveGroup = require('./argument/exclusive');
95 // Registration methods
99 * ActionContainer#register(registryName, value, object) -> Void
100 * - registryName (String) : object type action|type
101 * - value (string) : keyword
102 * - object (Object|Function) : handler
106 ActionContainer.prototype.register = function (registryName, value, object) {
107 this._registries[registryName] = this._registries[registryName] || {};
108 this._registries[registryName][value] = object;
111 ActionContainer.prototype._registryGet = function (registryName, value, defaultValue) {
112 if (arguments.length < 3) {
115 return this._registries[registryName][value] || defaultValue;
119 // Namespace default accessor methods
123 * ActionContainer#setDefaults(options) -> Void
124 * - options (object):hash of options see [[Action.new]]
128 ActionContainer.prototype.setDefaults = function (options) {
129 options = options || {};
130 for (var property in options) {
131 if ($$.has(options, property)) {
132 this._defaults[property] = options[property];
136 // if these defaults match any existing arguments, replace the previous
137 // default on the object with the new one
138 this._actions.forEach(function (action) {
139 if ($$.has(options, action.dest)) {
140 action.defaultValue = options[action.dest];
146 * ActionContainer#getDefault(dest) -> Mixed
147 * - dest (string): action destination
149 * Return action default value
151 ActionContainer.prototype.getDefault = function (dest) {
152 var result = $$.has(this._defaults, dest) ? this._defaults[dest] : null;
154 this._actions.forEach(function (action) {
155 if (action.dest === dest && $$.has(action, 'defaultValue')) {
156 result = action.defaultValue;
163 // Adding argument actions
167 * ActionContainer#addArgument(args, options) -> Object
168 * - args (String|Array): argument key, or array of argument keys
169 * - options (Object): action objects see [[Action.new]]
172 * - addArgument([ '-f', '--foo' ], { action: 'store', defaultValue: 1, ... })
173 * - addArgument([ 'bar' ], { action: 'store', nargs: 1, ... })
174 * - addArgument('--baz', { action: 'store', nargs: 1, ... })
176 ActionContainer.prototype.addArgument = function (args, options) {
178 options = options || {};
180 if (typeof args === 'string') {
183 if (!Array.isArray(args)) {
184 throw new TypeError('addArgument first argument should be a string or an array');
186 if (typeof options !== 'object' || Array.isArray(options)) {
187 throw new TypeError('addArgument second argument should be a hash');
190 // if no positional args are supplied or only one is supplied and
191 // it doesn't look like an option string, parse a positional argument
192 if (!args || args.length === 1 && this.prefixChars.indexOf(args[0][0]) < 0) {
193 if (args && !!options.dest) {
194 throw new Error('dest supplied twice for positional argument');
196 options = this._getPositional(args, options);
198 // otherwise, we're adding an optional argument
200 options = this._getOptional(args, options);
203 // if no default was supplied, use the parser-level default
204 if (typeof options.defaultValue === 'undefined') {
205 var dest = options.dest;
206 if ($$.has(this._defaults, dest)) {
207 options.defaultValue = this._defaults[dest];
208 } else if (typeof this.argumentDefault !== 'undefined') {
209 options.defaultValue = this.argumentDefault;
213 // create the action object, and add it to the parser
214 var ActionClass = this._popActionClass(options);
215 if (typeof ActionClass !== 'function') {
216 throw new Error(format('Unknown action "%s".', ActionClass));
218 var action = new ActionClass(options);
220 // throw an error if the action type is not callable
221 var typeFunction = this._registryGet('type', action.type, action.type);
222 if (typeof typeFunction !== 'function') {
223 throw new Error(format('"%s" is not callable', typeFunction));
226 return this._addAction(action);
230 * ActionContainer#addArgumentGroup(options) -> ArgumentGroup
231 * - options (Object): hash of options see [[ArgumentGroup.new]]
233 * Create new arguments groups
235 ActionContainer.prototype.addArgumentGroup = function (options) {
236 var group = new ArgumentGroup(this, options);
237 this._actionGroups.push(group);
242 * ActionContainer#addMutuallyExclusiveGroup(options) -> ArgumentGroup
243 * - options (Object): {required: false}
245 * Create new mutual exclusive groups
247 ActionContainer.prototype.addMutuallyExclusiveGroup = function (options) {
248 var group = new MutuallyExclusiveGroup(this, options);
249 this._mutuallyExclusiveGroups.push(group);
253 ActionContainer.prototype._addAction = function (action) {
256 // resolve any conflicts
257 this._checkConflict(action);
259 // add to actions list
260 this._actions.push(action);
261 action.container = this;
263 // index the action by any option strings it has
264 action.optionStrings.forEach(function (optionString) {
265 self._optionStringActions[optionString] = action;
268 // set the flag if any option strings look like negative numbers
269 action.optionStrings.forEach(function (optionString) {
270 if (optionString.match(self._regexpNegativeNumber)) {
271 if (!self._hasNegativeNumberOptionals.some(Boolean)) {
272 self._hasNegativeNumberOptionals.push(true);
277 // return the created action
281 ActionContainer.prototype._removeAction = function (action) {
282 var actionIndex = this._actions.indexOf(action);
283 if (actionIndex >= 0) {
284 this._actions.splice(actionIndex, 1);
288 ActionContainer.prototype._addContainerActions = function (container) {
289 // collect groups by titles
290 var titleGroupMap = {};
291 this._actionGroups.forEach(function (group) {
292 if (titleGroupMap[group.title]) {
293 throw new Error(format('Cannot merge actions - two groups are named "%s".', group.title));
295 titleGroupMap[group.title] = group;
298 // map each action to its group
300 function actionHash(action) {
301 // unique (hopefully?) string suitable as dictionary key
302 return action.getName();
304 container._actionGroups.forEach(function (group) {
305 // if a group with the title exists, use that, otherwise
306 // create a new group matching the container's group
307 if (!titleGroupMap[group.title]) {
308 titleGroupMap[group.title] = this.addArgumentGroup({
310 description: group.description
314 // map the actions to their new group
315 group._groupActions.forEach(function (action) {
316 groupMap[actionHash(action)] = titleGroupMap[group.title];
320 // add container's mutually exclusive groups
321 // NOTE: if add_mutually_exclusive_group ever gains title= and
322 // description= then this code will need to be expanded as above
324 container._mutuallyExclusiveGroups.forEach(function (group) {
325 mutexGroup = this.addMutuallyExclusiveGroup({
326 required: group.required
328 // map the actions to their new mutex group
329 group._groupActions.forEach(function (action) {
330 groupMap[actionHash(action)] = mutexGroup;
332 }, this); // forEach takes a 'this' argument
334 // add all actions to this container or their group
335 container._actions.forEach(function (action) {
336 var key = actionHash(action);
338 groupMap[key]._addAction(action);
340 this._addAction(action);
345 ActionContainer.prototype._getPositional = function (dest, options) {
346 if (Array.isArray(dest)) {
349 // make sure required is not specified
350 if (options.required) {
351 throw new Error('"required" is an invalid argument for positionals.');
354 // mark positional arguments as required if at least one is
356 if (options.nargs !== c.OPTIONAL && options.nargs !== c.ZERO_OR_MORE) {
357 options.required = true;
359 if (options.nargs === c.ZERO_OR_MORE && typeof options.defaultValue === 'undefined') {
360 options.required = true;
363 // return the keyword arguments with no option strings
365 options.optionStrings = [];
369 ActionContainer.prototype._getOptional = function (args, options) {
370 var prefixChars = this.prefixChars;
371 var optionStrings = [];
372 var optionStringsLong = [];
374 // determine short and long option strings
375 args.forEach(function (optionString) {
376 // error on strings that don't start with an appropriate prefix
377 if (prefixChars.indexOf(optionString[0]) < 0) {
378 throw new Error(format('Invalid option string "%s": must start with a "%s".',
384 // strings starting with two prefix characters are long options
385 optionStrings.push(optionString);
386 if (optionString.length > 1 && prefixChars.indexOf(optionString[1]) >= 0) {
387 optionStringsLong.push(optionString);
391 // infer dest, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
392 var dest = options.dest || null;
396 var optionStringDest = optionStringsLong.length ? optionStringsLong[0] : optionStrings[0];
397 dest = $$.trimChars(optionStringDest, this.prefixChars);
399 if (dest.length === 0) {
401 format('dest= is required for options like "%s"', optionStrings.join(', '))
404 dest = dest.replace(/-/g, '_');
407 // return the updated keyword arguments
409 options.optionStrings = optionStrings;
414 ActionContainer.prototype._popActionClass = function (options, defaultValue) {
415 defaultValue = defaultValue || null;
417 var action = (options.action || defaultValue);
418 delete options.action;
420 var actionClass = this._registryGet('action', action, action);
424 ActionContainer.prototype._getHandler = function () {
425 var handlerString = this.conflictHandler;
426 var handlerFuncName = '_handleConflict' + $$.capitalize(handlerString);
427 var func = this[handlerFuncName];
428 if (typeof func === 'undefined') {
429 var msg = 'invalid conflict resolution value: ' + handlerString;
430 throw new Error(msg);
436 ActionContainer.prototype._checkConflict = function (action) {
437 var optionStringActions = this._optionStringActions;
438 var conflictOptionals = [];
440 // find all options that conflict with this option
441 // collect pairs, the string, and an existing action that it conflicts with
442 action.optionStrings.forEach(function (optionString) {
443 var conflOptional = optionStringActions[optionString];
444 if (typeof conflOptional !== 'undefined') {
445 conflictOptionals.push([ optionString, conflOptional ]);
449 if (conflictOptionals.length > 0) {
450 var conflictHandler = this._getHandler();
451 conflictHandler.call(this, action, conflictOptionals);
455 ActionContainer.prototype._handleConflictError = function (action, conflOptionals) {
456 var conflicts = conflOptionals.map(function (pair) { return pair[0]; });
457 conflicts = conflicts.join(', ');
458 throw argumentErrorHelper(
460 format('Conflicting option string(s): %s', conflicts)
464 ActionContainer.prototype._handleConflictResolve = function (action, conflOptionals) {
465 // remove all conflicting options
467 conflOptionals.forEach(function (pair) {
468 var optionString = pair[0];
469 var conflictingAction = pair[1];
470 // remove the conflicting option string
471 var i = conflictingAction.optionStrings.indexOf(optionString);
473 conflictingAction.optionStrings.splice(i, 1);
475 delete self._optionStringActions[optionString];
476 // if the option now has no option string, remove it from the
477 // container holding it
478 if (conflictingAction.optionStrings.length === 0) {
479 conflictingAction.container._removeAction(conflictingAction);