action_container.js 15 KB

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