review.tizen.org Git - platform/framework/web/crosswalk-tizen.git/blob

   1 /** internal
   2  * class ActionContainer
   3  *
   4  * Action container. Parent for [[ArgumentParser]] and [[ArgumentGroup]]
   5  **/
   6
   7 'use strict';
   8
   9 var format = require('util').format;
  10 var _      = require('lodash');
  11
  12 // Constants
  13 var $$ = require('./const');
  14
  15 //Actions
  16 var ActionHelp = require('./action/help');
  17 var ActionAppend = require('./action/append');
  18 var ActionAppendConstant = require('./action/append/constant');
  19 var ActionCount = require('./action/count');
  20 var ActionStore = require('./action/store');
  21 var ActionStoreConstant = require('./action/store/constant');
  22 var ActionStoreTrue = require('./action/store/true');
  23 var ActionStoreFalse = require('./action/store/false');
  24 var ActionVersion = require('./action/version');
  25 var ActionSubparsers = require('./action/subparsers');
  26
  27 // Errors
  28 var argumentErrorHelper = require('./argument/error');
  29
  30
  31
  32 /**
  33  * new ActionContainer(options)
  34  *
  35  * Action container. Parent for [[ArgumentParser]] and [[ArgumentGroup]]
  36  *
  37  * ##### Options:
  38  *
  39  * - `description` -- A description of what the program does
  40  * - `prefixChars`  -- Characters that prefix optional arguments
  41  * - `argumentDefault`  -- The default value for all arguments
  42  * - `conflictHandler` -- The conflict handler to use for duplicate arguments
  43  **/
  44 var ActionContainer = module.exports = function ActionContainer(options) {
  45   options = options || {};
  46
  47   this.description = options.description;
  48   this.argumentDefault = options.argumentDefault;
  49   this.prefixChars = options.prefixChars || '';
  50   this.conflictHandler = options.conflictHandler;
  51
  52   // set up registries
  53   this._registries = {};
  54
  55   // register actions
  56   this.register('action', null, ActionStore);
  57   this.register('action', 'store', ActionStore);
  58   this.register('action', 'storeConst', ActionStoreConstant);
  59   this.register('action', 'storeTrue', ActionStoreTrue);
  60   this.register('action', 'storeFalse', ActionStoreFalse);
  61   this.register('action', 'append', ActionAppend);
  62   this.register('action', 'appendConst', ActionAppendConstant);
  63   this.register('action', 'count', ActionCount);
  64   this.register('action', 'help', ActionHelp);
  65   this.register('action', 'version', ActionVersion);
  66   this.register('action', 'parsers', ActionSubparsers);
  67
  68   // raise an exception if the conflict handler is invalid
  69   this._getHandler();
  70
  71   // action storage
  72   this._actions = [];
  73   this._optionStringActions = {};
  74
  75   // groups
  76   this._actionGroups = [];
  77   this._mutuallyExclusiveGroups = [];
  78
  79   // defaults storage
  80   this._defaults = {};
  81
  82   // determines whether an "option" looks like a negative number
  83   // -1, -1.5 -5e+4
  84   this._regexpNegativeNumber = new RegExp('^[-]?[0-9]*\\.?[0-9]+([eE][-+]?[0-9]+)?$');
  85
  86   // whether or not there are any optionals that look like negative
  87   // numbers -- uses a list so it can be shared and edited
  88   this._hasNegativeNumberOptionals = [];
  89 };
  90
  91 // Groups must be required, then ActionContainer already defined
  92 var ArgumentGroup = require('./argument/group');
  93 var MutuallyExclusiveGroup = require('./argument/exclusive');
  94
  95 //
  96 // Registration methods
  97 //
  98
  99 /**
 100  * ActionContainer#register(registryName, value, object) -> Void
 101  * - registryName (String) : object type action|type
 102  * - value (string) : keyword
 103  * - object (Object|Function) : handler
 104  *
 105  *  Register handlers
 106  **/
 107 ActionContainer.prototype.register = function (registryName, value, object) {
 108   this._registries[registryName] = this._registries[registryName] || {};
 109   this._registries[registryName][value] = object;
 110 };
 111
 112 ActionContainer.prototype._registryGet = function (registryName, value, defaultValue) {
 113   if (3 > arguments.length) {
 114     defaultValue = null;
 115   }
 116   return this._registries[registryName][value] || defaultValue;
 117 };
 118
 119 //
 120 // Namespace default accessor methods
 121 //
 122
 123 /**
 124  * ActionContainer#setDefaults(options) -> Void
 125  * - options (object):hash of options see [[Action.new]]
 126  *
 127  * Set defaults
 128  **/
 129 ActionContainer.prototype.setDefaults = function (options) {
 130   options = options || {};
 131   for (var property in options) {
 132     this._defaults[property] = options[property];
 133   }
 134
 135   // if these defaults match any existing arguments, replace the previous
 136   // default on the object with the new one
 137   this._actions.forEach(function (action) {
 138     if (action.dest in options) {
 139       action.defaultValue = options[action.dest];
 140     }
 141   });
 142 };
 143
 144 /**
 145  * ActionContainer#getDefault(dest) -> Mixed
 146  * - dest (string): action destination
 147  *
 148  * Return action default value
 149  **/
 150 ActionContainer.prototype.getDefault = function (dest) {
 151   var result = (_.has(this._defaults, dest)) ? this._defaults[dest] : null;
 152
 153   this._actions.forEach(function (action) {
 154     if (action.dest === dest && _.has(action, 'defaultValue')) {
 155       result = action.defaultValue;
 156     }
 157   });
 158
 159   return result;
 160 };
 161 //
 162 // Adding argument actions
 163 //
 164
 165 /**
 166  * ActionContainer#addArgument(args, options) -> Object
 167  * - args (Array): array of argument keys
 168  * - options (Object): action objects see [[Action.new]]
 169  *
 170  * #### Examples
 171  * - addArgument([-f, --foo], {action:'store', defaultValue=1, ...})
 172  * - addArgument(['bar'], action: 'store', nargs:1, ...})
 173  **/
 174 ActionContainer.prototype.addArgument = function (args, options) {
 175   args = args;
 176   options = options || {};
 177
 178   if (!_.isArray(args)) {
 179     throw new TypeError('addArgument first argument should be an array');
 180   }
 181   if (!_.isObject(options) || _.isArray(options)) {
 182     throw new TypeError('addArgument second argument should be a hash');
 183   }
 184
 185   // if no positional args are supplied or only one is supplied and
 186   // it doesn't look like an option string, parse a positional argument
 187   if (!args || args.length === 1 && this.prefixChars.indexOf(args[0][0]) < 0) {
 188     if (args && !!options.dest) {
 189       throw new Error('dest supplied twice for positional argument');
 190     }
 191     options = this._getPositional(args, options);
 192
 193     // otherwise, we're adding an optional argument
 194   } else {
 195     options = this._getOptional(args, options);
 196   }
 197
 198   // if no default was supplied, use the parser-level default
 199   if (_.isUndefined(options.defaultValue)) {
 200     var dest = options.dest;
 201     if (_.has(this._defaults, dest)) {
 202       options.defaultValue = this._defaults[dest];
 203     } else if (!_.isUndefined(this.argumentDefault)) {
 204       options.defaultValue = this.argumentDefault;
 205     }
 206   }
 207
 208   // create the action object, and add it to the parser
 209   var ActionClass = this._popActionClass(options);
 210   if (! _.isFunction(ActionClass)) {
 211     throw new Error(format('Unknown action "%s".', ActionClass));
 212   }
 213   var action = new ActionClass(options);
 214
 215   // throw an error if the action type is not callable
 216   var typeFunction = this._registryGet('type', action.type, action.type);
 217   if (!_.isFunction(typeFunction)) {
 218     throw new Error(format('"%s" is not callable', typeFunction));
 219   }
 220
 221   return this._addAction(action);
 222 };
 223
 224 /**
 225  * ActionContainer#addArgumentGroup(options) -> ArgumentGroup
 226  * - options (Object): hash of options see [[ArgumentGroup.new]]
 227  *
 228  * Create new arguments groups
 229  **/
 230 ActionContainer.prototype.addArgumentGroup = function (options) {
 231   var group = new ArgumentGroup(this, options);
 232   this._actionGroups.push(group);
 233   return group;
 234 };
 235
 236 /**
 237  * ActionContainer#addMutuallyExclusiveGroup(options) -> ArgumentGroup
 238  * - options (Object): {required: false}
 239  *
 240  * Create new mutual exclusive groups
 241  **/
 242 ActionContainer.prototype.addMutuallyExclusiveGroup = function (options) {
 243   var group = new MutuallyExclusiveGroup(this, options);
 244   this._mutuallyExclusiveGroups.push(group);
 245   return group;
 246 };
 247
 248 ActionContainer.prototype._addAction = function (action) {
 249   var self = this;
 250
 251   // resolve any conflicts
 252   this._checkConflict(action);
 253
 254   // add to actions list
 255   this._actions.push(action);
 256   action.container = this;
 257
 258   // index the action by any option strings it has
 259   action.optionStrings.forEach(function (optionString) {
 260     self._optionStringActions[optionString] = action;
 261   });
 262
 263   // set the flag if any option strings look like negative numbers
 264   action.optionStrings.forEach(function (optionString) {
 265     if (optionString.match(self._regexpNegativeNumber)) {
 266       if (!_.any(self._hasNegativeNumberOptionals)) {
 267         self._hasNegativeNumberOptionals.push(true);
 268       }
 269     }
 270   });
 271
 272   // return the created action
 273   return action;
 274 };
 275
 276 ActionContainer.prototype._removeAction = function (action) {
 277   var actionIndex = this._actions.indexOf(action);
 278   if (actionIndex >= 0) {
 279     this._actions.splice(actionIndex, 1);
 280   }
 281 };
 282
 283 ActionContainer.prototype._addContainerActions = function (container) {
 284   // collect groups by titles
 285   var titleGroupMap = {};
 286   this._actionGroups.forEach(function (group) {
 287     if (titleGroupMap[group.title]) {
 288       throw new Error(format('Cannot merge actions - two groups are named "%s".', group.title));
 289     }
 290     titleGroupMap[group.title] = group;
 291   });
 292
 293   // map each action to its group
 294   var groupMap = {};
 295   function actionHash(action) {
 296     // unique (hopefully?) string suitable as dictionary key
 297     return action.getName();
 298   }
 299   container._actionGroups.forEach(function (group) {
 300     // if a group with the title exists, use that, otherwise
 301     // create a new group matching the container's group
 302     if (!titleGroupMap[group.title]) {
 303       titleGroupMap[group.title] = this.addArgumentGroup({
 304         title: group.title,
 305         description: group.description
 306       });
 307     }
 308
 309     // map the actions to their new group
 310     group._groupActions.forEach(function (action) {
 311       groupMap[actionHash(action)] = titleGroupMap[group.title];
 312     });
 313   }, this);
 314
 315   // add container's mutually exclusive groups
 316   // NOTE: if add_mutually_exclusive_group ever gains title= and
 317   // description= then this code will need to be expanded as above
 318   var mutexGroup;
 319   container._mutuallyExclusiveGroups.forEach(function (group) {
 320     mutexGroup = this.addMutuallyExclusiveGroup({
 321         required: group.required
 322       });
 323     // map the actions to their new mutex group
 324     group._groupActions.forEach(function (action) {
 325       groupMap[actionHash(action)] = mutexGroup;
 326     });
 327   }, this);  // forEach takes a 'this' argument
 328
 329   // add all actions to this container or their group
 330   container._actions.forEach(function (action) {
 331     var key = actionHash(action);
 332     if (!!groupMap[key]) {
 333       groupMap[key]._addAction(action);
 334     }
 335     else
 336     {
 337       this._addAction(action);
 338     }
 339   });
 340 };
 341
 342 ActionContainer.prototype._getPositional = function (dest, options) {
 343   if (_.isArray(dest)) {
 344     dest = _.first(dest);
 345   }
 346   // make sure required is not specified
 347   if (options.required) {
 348     throw new Error('"required" is an invalid argument for positionals.');
 349   }
 350
 351   // mark positional arguments as required if at least one is
 352   // always required
 353   if (options.nargs !== $$.OPTIONAL && options.nargs !== $$.ZERO_OR_MORE) {
 354     options.required = true;
 355   }
 356   if (options.nargs === $$.ZERO_OR_MORE && options.defaultValue === undefined) {
 357     options.required = true;
 358   }
 359
 360   // return the keyword arguments with no option strings
 361   options.dest = dest;
 362   options.optionStrings = [];
 363   return options;
 364 };
 365
 366 ActionContainer.prototype._getOptional = function (args, options) {
 367   var prefixChars = this.prefixChars;
 368   var optionStrings = [];
 369   var optionStringsLong = [];
 370
 371   // determine short and long option strings
 372   args.forEach(function (optionString) {
 373     // error on strings that don't start with an appropriate prefix
 374     if (prefixChars.indexOf(optionString[0]) < 0) {
 375       throw new Error(format('Invalid option string "%s": must start with a "%s".',
 376         optionString,
 377         prefixChars
 378       ));
 379     }
 380
 381     // strings starting with two prefix characters are long options
 382     optionStrings.push(optionString);
 383     if (optionString.length > 1 && prefixChars.indexOf(optionString[1]) >= 0) {
 384       optionStringsLong.push(optionString);
 385     }
 386   });
 387
 388   // infer dest, '--foo-bar' -> 'foo_bar' and '-x' -> 'x'
 389   var dest = options.dest || null;
 390   delete options.dest;
 391
 392   if (!dest) {
 393     var optionStringDest = optionStringsLong.length ? optionStringsLong[0] :optionStrings[0];
 394     dest = _.trim(optionStringDest, this.prefixChars);
 395
 396     if (dest.length === 0) {
 397       throw new Error(
 398         format('dest= is required for options like "%s"', optionStrings.join(', '))
 399       );
 400     }
 401     dest = dest.replace(/-/g, '_');
 402   }
 403
 404   // return the updated keyword arguments
 405   options.dest = dest;
 406   options.optionStrings = optionStrings;
 407
 408   return options;
 409 };
 410
 411 ActionContainer.prototype._popActionClass = function (options, defaultValue) {
 412   defaultValue = defaultValue || null;
 413
 414   var action = (options.action || defaultValue);
 415   delete options.action;
 416
 417   var actionClass = this._registryGet('action', action, action);
 418   return actionClass;
 419 };
 420
 421 ActionContainer.prototype._getHandler = function () {
 422   var handlerString = this.conflictHandler;
 423   var handlerFuncName = "_handleConflict" + _.capitalize(handlerString);
 424   var func = this[handlerFuncName];
 425   if (typeof func === 'undefined') {
 426     var msg = "invalid conflict resolution value: " + handlerString;
 427     throw new Error(msg);
 428   } else {
 429     return func;
 430   }
 431 };
 432
 433 ActionContainer.prototype._checkConflict = function (action) {
 434   var optionStringActions = this._optionStringActions;
 435   var conflictOptionals = [];
 436
 437   // find all options that conflict with this option
 438   // collect pairs, the string, and an existing action that it conflicts with
 439   action.optionStrings.forEach(function (optionString) {
 440     var conflOptional = optionStringActions[optionString];
 441     if (typeof conflOptional !== 'undefined') {
 442       conflictOptionals.push([optionString, conflOptional]);
 443     }
 444   });
 445
 446   if (conflictOptionals.length > 0) {
 447     var conflictHandler = this._getHandler();
 448     conflictHandler.call(this, action, conflictOptionals);
 449   }
 450 };
 451
 452 ActionContainer.prototype._handleConflictError = function (action, conflOptionals) {
 453   var conflicts = _.map(conflOptionals, function (pair) {return pair[0]; });
 454   conflicts = conflicts.join(', ');
 455   throw argumentErrorHelper(
 456     action,
 457     format('Conflicting option string(s): %s', conflicts)
 458   );
 459 };
 460
 461 ActionContainer.prototype._handleConflictResolve = function (action, conflOptionals) {
 462   // remove all conflicting options
 463   var self = this;
 464   conflOptionals.forEach(function (pair) {
 465     var optionString = pair[0];
 466     var conflictingAction = pair[1];
 467     // remove the conflicting option string
 468     var i = conflictingAction.optionStrings.indexOf(optionString);
 469     if (i >= 0) {
 470       conflictingAction.optionStrings.splice(i, 1);
 471     }
 472     delete self._optionStringActions[optionString];
 473     // if the option now has no option string, remove it from the
 474     // container holding it
 475     if (conflictingAction.optionStrings.length === 0) {
 476       conflictingAction.container._removeAction(conflictingAction);
 477     }
 478   });
 479 };