source: trip-planner-front/node_modules/dashdash/lib/dashdash.js@ bdd6491

Last change on this file since bdd6491 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit
  • Property mode set to 100644
File size: 34.5 KB
RevLine 
[6a3a178]1/**
2 * dashdash - A light, featureful and explicit option parsing library for
3 * node.js.
4 */
5// vim: set ts=4 sts=4 sw=4 et:
6
7var assert = require('assert-plus');
8var format = require('util').format;
9var fs = require('fs');
10var path = require('path');
11
12
13var DEBUG = true;
14if (DEBUG) {
15 var debug = console.warn;
16} else {
17 var debug = function () {};
18}
19
20
21
22// ---- internal support stuff
23
24// Replace {{variable}} in `s` with the template data in `d`.
25function renderTemplate(s, d) {
26 return s.replace(/{{([a-zA-Z]+)}}/g, function (match, key) {
27 return d.hasOwnProperty(key) ? d[key] : match;
28 });
29}
30
31/**
32 * Return a shallow copy of the given object;
33 */
34function shallowCopy(obj) {
35 if (!obj) {
36 return (obj);
37 }
38 var copy = {};
39 Object.keys(obj).forEach(function (k) {
40 copy[k] = obj[k];
41 });
42 return (copy);
43}
44
45
46function space(n) {
47 var s = '';
48 for (var i = 0; i < n; i++) {
49 s += ' ';
50 }
51 return s;
52}
53
54
55function makeIndent(arg, deflen, name) {
56 if (arg === null || arg === undefined)
57 return space(deflen);
58 else if (typeof (arg) === 'number')
59 return space(arg);
60 else if (typeof (arg) === 'string')
61 return arg;
62 else
63 assert.fail('invalid "' + name + '": not a string or number: ' + arg);
64}
65
66
67/**
68 * Return an array of lines wrapping the given text to the given width.
69 * This splits on whitespace. Single tokens longer than `width` are not
70 * broken up.
71 */
72function textwrap(s, width) {
73 var words = s.trim().split(/\s+/);
74 var lines = [];
75 var line = '';
76 words.forEach(function (w) {
77 var newLength = line.length + w.length;
78 if (line.length > 0)
79 newLength += 1;
80 if (newLength > width) {
81 lines.push(line);
82 line = '';
83 }
84 if (line.length > 0)
85 line += ' ';
86 line += w;
87 });
88 lines.push(line);
89 return lines;
90}
91
92
93/**
94 * Transform an option name to a "key" that is used as the field
95 * on the `opts` object returned from `<parser>.parse()`.
96 *
97 * Transformations:
98 * - '-' -> '_': This allow one to use hyphen in option names (common)
99 * but not have to do silly things like `opt["dry-run"]` to access the
100 * parsed results.
101 */
102function optionKeyFromName(name) {
103 return name.replace(/-/g, '_');
104}
105
106
107
108// ---- Option types
109
110function parseBool(option, optstr, arg) {
111 return Boolean(arg);
112}
113
114function parseString(option, optstr, arg) {
115 assert.string(arg, 'arg');
116 return arg;
117}
118
119function parseNumber(option, optstr, arg) {
120 assert.string(arg, 'arg');
121 var num = Number(arg);
122 if (isNaN(num)) {
123 throw new Error(format('arg for "%s" is not a number: "%s"',
124 optstr, arg));
125 }
126 return num;
127}
128
129function parseInteger(option, optstr, arg) {
130 assert.string(arg, 'arg');
131 var num = Number(arg);
132 if (!/^[0-9-]+$/.test(arg) || isNaN(num)) {
133 throw new Error(format('arg for "%s" is not an integer: "%s"',
134 optstr, arg));
135 }
136 return num;
137}
138
139function parsePositiveInteger(option, optstr, arg) {
140 assert.string(arg, 'arg');
141 var num = Number(arg);
142 if (!/^[0-9]+$/.test(arg) || isNaN(num) || num === 0) {
143 throw new Error(format('arg for "%s" is not a positive integer: "%s"',
144 optstr, arg));
145 }
146 return num;
147}
148
149/**
150 * Supported date args:
151 * - epoch second times (e.g. 1396031701)
152 * - ISO 8601 format: YYYY-MM-DD[THH:MM:SS[.sss][Z]]
153 * 2014-03-28T18:35:01.489Z
154 * 2014-03-28T18:35:01.489
155 * 2014-03-28T18:35:01Z
156 * 2014-03-28T18:35:01
157 * 2014-03-28
158 */
159function parseDate(option, optstr, arg) {
160 assert.string(arg, 'arg');
161 var date;
162 if (/^\d+$/.test(arg)) {
163 // epoch seconds
164 date = new Date(Number(arg) * 1000);
165 /* JSSTYLED */
166 } else if (/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?Z?)?$/i.test(arg)) {
167 // ISO 8601 format
168 date = new Date(arg);
169 } else {
170 throw new Error(format('arg for "%s" is not a valid date format: "%s"',
171 optstr, arg));
172 }
173 if (date.toString() === 'Invalid Date') {
174 throw new Error(format('arg for "%s" is an invalid date: "%s"',
175 optstr, arg));
176 }
177 return date;
178}
179
180var optionTypes = {
181 bool: {
182 takesArg: false,
183 parseArg: parseBool
184 },
185 string: {
186 takesArg: true,
187 helpArg: 'ARG',
188 parseArg: parseString
189 },
190 number: {
191 takesArg: true,
192 helpArg: 'NUM',
193 parseArg: parseNumber
194 },
195 integer: {
196 takesArg: true,
197 helpArg: 'INT',
198 parseArg: parseInteger
199 },
200 positiveInteger: {
201 takesArg: true,
202 helpArg: 'INT',
203 parseArg: parsePositiveInteger
204 },
205 date: {
206 takesArg: true,
207 helpArg: 'DATE',
208 parseArg: parseDate
209 },
210 arrayOfBool: {
211 takesArg: false,
212 array: true,
213 parseArg: parseBool
214 },
215 arrayOfString: {
216 takesArg: true,
217 helpArg: 'ARG',
218 array: true,
219 parseArg: parseString
220 },
221 arrayOfNumber: {
222 takesArg: true,
223 helpArg: 'NUM',
224 array: true,
225 parseArg: parseNumber
226 },
227 arrayOfInteger: {
228 takesArg: true,
229 helpArg: 'INT',
230 array: true,
231 parseArg: parseInteger
232 },
233 arrayOfPositiveInteger: {
234 takesArg: true,
235 helpArg: 'INT',
236 array: true,
237 parseArg: parsePositiveInteger
238 },
239 arrayOfDate: {
240 takesArg: true,
241 helpArg: 'INT',
242 array: true,
243 parseArg: parseDate
244 },
245};
246
247
248
249// ---- Parser
250
251/**
252 * Parser constructor.
253 *
254 * @param config {Object} The parser configuration
255 * - options {Array} Array of option specs. See the README for how to
256 * specify each option spec.
257 * - allowUnknown {Boolean} Default false. Whether to throw on unknown
258 * options. If false, then unknown args are included in the _args array.
259 * - interspersed {Boolean} Default true. Whether to allow interspersed
260 * arguments (non-options) and options. E.g.:
261 * node tool.js arg1 arg2 -v
262 * '-v' is after some args here. If `interspersed: false` then '-v'
263 * would not be parsed out. Note that regardless of `interspersed`
264 * the presence of '--' will stop option parsing, as all good
265 * option parsers should.
266 */
267function Parser(config) {
268 assert.object(config, 'config');
269 assert.arrayOfObject(config.options, 'config.options');
270 assert.optionalBool(config.interspersed, 'config.interspersed');
271 var self = this;
272
273 // Allow interspersed arguments (true by default).
274 this.interspersed = (config.interspersed !== undefined
275 ? config.interspersed : true);
276
277 // Don't allow unknown flags (true by default).
278 this.allowUnknown = (config.allowUnknown !== undefined
279 ? config.allowUnknown : false);
280
281 this.options = config.options.map(function (o) { return shallowCopy(o); });
282 this.optionFromName = {};
283 this.optionFromEnv = {};
284 for (var i = 0; i < this.options.length; i++) {
285 var o = this.options[i];
286 if (o.group !== undefined && o.group !== null) {
287 assert.optionalString(o.group,
288 format('config.options.%d.group', i));
289 continue;
290 }
291 assert.ok(optionTypes[o.type],
292 format('invalid config.options.%d.type: "%s" in %j',
293 i, o.type, o));
294 assert.optionalString(o.name, format('config.options.%d.name', i));
295 assert.optionalArrayOfString(o.names,
296 format('config.options.%d.names', i));
297 assert.ok((o.name || o.names) && !(o.name && o.names),
298 format('exactly one of "name" or "names" required: %j', o));
299 assert.optionalString(o.help, format('config.options.%d.help', i));
300 var env = o.env || [];
301 if (typeof (env) === 'string') {
302 env = [env];
303 }
304 assert.optionalArrayOfString(env, format('config.options.%d.env', i));
305 assert.optionalString(o.helpGroup,
306 format('config.options.%d.helpGroup', i));
307 assert.optionalBool(o.helpWrap,
308 format('config.options.%d.helpWrap', i));
309 assert.optionalBool(o.hidden, format('config.options.%d.hidden', i));
310
311 if (o.name) {
312 o.names = [o.name];
313 } else {
314 assert.string(o.names[0],
315 format('config.options.%d.names is empty', i));
316 }
317 o.key = optionKeyFromName(o.names[0]);
318 o.names.forEach(function (n) {
319 if (self.optionFromName[n]) {
320 throw new Error(format(
321 'option name collision: "%s" used in %j and %j',
322 n, self.optionFromName[n], o));
323 }
324 self.optionFromName[n] = o;
325 });
326 env.forEach(function (n) {
327 if (self.optionFromEnv[n]) {
328 throw new Error(format(
329 'option env collision: "%s" used in %j and %j',
330 n, self.optionFromEnv[n], o));
331 }
332 self.optionFromEnv[n] = o;
333 });
334 }
335}
336
337Parser.prototype.optionTakesArg = function optionTakesArg(option) {
338 return optionTypes[option.type].takesArg;
339};
340
341/**
342 * Parse options from the given argv.
343 *
344 * @param inputs {Object} Optional.
345 * - argv {Array} Optional. The argv to parse. Defaults to
346 * `process.argv`.
347 * - slice {Number} The index into argv at which options/args begin.
348 * Default is 2, as appropriate for `process.argv`.
349 * - env {Object} Optional. The env to use for 'env' entries in the
350 * option specs. Defaults to `process.env`.
351 * @returns {Object} Parsed `opts`. It has special keys `_args` (the
352 * remaining args from `argv`) and `_order` (gives the order that
353 * options were specified).
354 */
355Parser.prototype.parse = function parse(inputs) {
356 var self = this;
357
358 // Old API was `parse([argv, [slice]])`
359 if (Array.isArray(arguments[0])) {
360 inputs = {argv: arguments[0], slice: arguments[1]};
361 }
362
363 assert.optionalObject(inputs, 'inputs');
364 if (!inputs) {
365 inputs = {};
366 }
367 assert.optionalArrayOfString(inputs.argv, 'inputs.argv');
368 //assert.optionalNumber(slice, 'slice');
369 var argv = inputs.argv || process.argv;
370 var slice = inputs.slice !== undefined ? inputs.slice : 2;
371 var args = argv.slice(slice);
372 var env = inputs.env || process.env;
373 var opts = {};
374 var _order = [];
375
376 function addOpt(option, optstr, key, val, from) {
377 var type = optionTypes[option.type];
378 var parsedVal = type.parseArg(option, optstr, val);
379 if (type.array) {
380 if (!opts[key]) {
381 opts[key] = [];
382 }
383 if (type.arrayFlatten && Array.isArray(parsedVal)) {
384 for (var i = 0; i < parsedVal.length; i++) {
385 opts[key].push(parsedVal[i]);
386 }
387 } else {
388 opts[key].push(parsedVal);
389 }
390 } else {
391 opts[key] = parsedVal;
392 }
393 var item = { key: key, value: parsedVal, from: from };
394 _order.push(item);
395 }
396
397 // Parse args.
398 var _args = [];
399 var i = 0;
400 outer: while (i < args.length) {
401 var arg = args[i];
402
403 // End of options marker.
404 if (arg === '--') {
405 i++;
406 break;
407
408 // Long option
409 } else if (arg.slice(0, 2) === '--') {
410 var name = arg.slice(2);
411 var val = null;
412 var idx = name.indexOf('=');
413 if (idx !== -1) {
414 val = name.slice(idx + 1);
415 name = name.slice(0, idx);
416 }
417 var option = this.optionFromName[name];
418 if (!option) {
419 if (!this.allowUnknown)
420 throw new Error(format('unknown option: "--%s"', name));
421 else if (this.interspersed)
422 _args.push(arg);
423 else
424 break outer;
425 } else {
426 var takesArg = this.optionTakesArg(option);
427 if (val !== null && !takesArg) {
428 throw new Error(format('argument given to "--%s" option '
429 + 'that does not take one: "%s"', name, arg));
430 }
431 if (!takesArg) {
432 addOpt(option, '--'+name, option.key, true, 'argv');
433 } else if (val !== null) {
434 addOpt(option, '--'+name, option.key, val, 'argv');
435 } else if (i + 1 >= args.length) {
436 throw new Error(format('do not have enough args for "--%s" '
437 + 'option', name));
438 } else {
439 addOpt(option, '--'+name, option.key, args[i + 1], 'argv');
440 i++;
441 }
442 }
443
444 // Short option
445 } else if (arg[0] === '-' && arg.length > 1) {
446 var j = 1;
447 var allFound = true;
448 while (j < arg.length) {
449 var name = arg[j];
450 var option = this.optionFromName[name];
451 if (!option) {
452 allFound = false;
453 if (this.allowUnknown) {
454 if (this.interspersed) {
455 _args.push(arg);
456 break;
457 } else
458 break outer;
459 } else if (arg.length > 2) {
460 throw new Error(format(
461 'unknown option: "-%s" in "%s" group',
462 name, arg));
463 } else {
464 throw new Error(format('unknown option: "-%s"', name));
465 }
466 } else if (this.optionTakesArg(option)) {
467 break;
468 }
469 j++;
470 }
471
472 j = 1;
473 while (allFound && j < arg.length) {
474 var name = arg[j];
475 var val = arg.slice(j + 1); // option val if it takes an arg
476 var option = this.optionFromName[name];
477 var takesArg = this.optionTakesArg(option);
478 if (!takesArg) {
479 addOpt(option, '-'+name, option.key, true, 'argv');
480 } else if (val) {
481 addOpt(option, '-'+name, option.key, val, 'argv');
482 break;
483 } else {
484 if (i + 1 >= args.length) {
485 throw new Error(format('do not have enough args '
486 + 'for "-%s" option', name));
487 }
488 addOpt(option, '-'+name, option.key, args[i + 1], 'argv');
489 i++;
490 break;
491 }
492 j++;
493 }
494
495 // An interspersed arg
496 } else if (this.interspersed) {
497 _args.push(arg);
498
499 // An arg and interspersed args are not allowed, so done options.
500 } else {
501 break outer;
502 }
503 i++;
504 }
505 _args = _args.concat(args.slice(i));
506
507 // Parse environment.
508 Object.keys(this.optionFromEnv).forEach(function (envname) {
509 var val = env[envname];
510 if (val === undefined)
511 return;
512 var option = self.optionFromEnv[envname];
513 if (opts[option.key] !== undefined)
514 return;
515 var takesArg = self.optionTakesArg(option);
516 if (takesArg) {
517 addOpt(option, envname, option.key, val, 'env');
518 } else if (val !== '') {
519 // Boolean envvar handling:
520 // - VAR=<empty-string> not set (as if the VAR was not set)
521 // - VAR=0 false
522 // - anything else true
523 addOpt(option, envname, option.key, (val !== '0'), 'env');
524 }
525 });
526
527 // Apply default values.
528 this.options.forEach(function (o) {
529 if (opts[o.key] === undefined) {
530 if (o.default !== undefined) {
531 opts[o.key] = o.default;
532 } else if (o.type && optionTypes[o.type].default !== undefined) {
533 opts[o.key] = optionTypes[o.type].default;
534 }
535 }
536 });
537
538 opts._order = _order;
539 opts._args = _args;
540 return opts;
541};
542
543
544/**
545 * Return help output for the current options.
546 *
547 * E.g.: if the current options are:
548 * [{names: ['help', 'h'], type: 'bool', help: 'Show help and exit.'}]
549 * then this would return:
550 * ' -h, --help Show help and exit.\n'
551 *
552 * @param config {Object} Config for controlling the option help output.
553 * - indent {Number|String} Default 4. An indent/prefix to use for
554 * each option line.
555 * - nameSort {String} Default is 'length'. By default the names are
556 * sorted to put the short opts first (i.e. '-h, --help' preferred
557 * to '--help, -h'). Set to 'none' to not do this sorting.
558 * - maxCol {Number} Default 80. Note that long tokens in a help string
559 * can go past this.
560 * - helpCol {Number} Set to specify a specific column at which
561 * option help will be aligned. By default this is determined
562 * automatically.
563 * - minHelpCol {Number} Default 20.
564 * - maxHelpCol {Number} Default 40.
565 * - includeEnv {Boolean} Default false. If true, a note stating the `env`
566 * envvar (if specified for this option) will be appended to the help
567 * output.
568 * - includeDefault {Boolean} Default false. If true, a note stating
569 * the `default` for this option, if any, will be appended to the help
570 * output.
571 * - helpWrap {Boolean} Default true. Wrap help text in helpCol..maxCol
572 * bounds.
573 * @returns {String}
574 */
575Parser.prototype.help = function help(config) {
576 config = config || {};
577 assert.object(config, 'config');
578
579 var indent = makeIndent(config.indent, 4, 'config.indent');
580 var headingIndent = makeIndent(config.headingIndent,
581 Math.round(indent.length / 2), 'config.headingIndent');
582
583 assert.optionalString(config.nameSort, 'config.nameSort');
584 var nameSort = config.nameSort || 'length';
585 assert.ok(~['length', 'none'].indexOf(nameSort),
586 'invalid "config.nameSort"');
587 assert.optionalNumber(config.maxCol, 'config.maxCol');
588 assert.optionalNumber(config.maxHelpCol, 'config.maxHelpCol');
589 assert.optionalNumber(config.minHelpCol, 'config.minHelpCol');
590 assert.optionalNumber(config.helpCol, 'config.helpCol');
591 assert.optionalBool(config.includeEnv, 'config.includeEnv');
592 assert.optionalBool(config.includeDefault, 'config.includeDefault');
593 assert.optionalBool(config.helpWrap, 'config.helpWrap');
594 var maxCol = config.maxCol || 80;
595 var minHelpCol = config.minHelpCol || 20;
596 var maxHelpCol = config.maxHelpCol || 40;
597
598 var lines = [];
599 var maxWidth = 0;
600 this.options.forEach(function (o) {
601 if (o.hidden) {
602 return;
603 }
604 if (o.group !== undefined && o.group !== null) {
605 // We deal with groups in the next pass
606 lines.push(null);
607 return;
608 }
609 var type = optionTypes[o.type];
610 var arg = o.helpArg || type.helpArg || 'ARG';
611 var line = '';
612 var names = o.names.slice();
613 if (nameSort === 'length') {
614 names.sort(function (a, b) {
615 if (a.length < b.length)
616 return -1;
617 else if (b.length < a.length)
618 return 1;
619 else
620 return 0;
621 })
622 }
623 names.forEach(function (name, i) {
624 if (i > 0)
625 line += ', ';
626 if (name.length === 1) {
627 line += '-' + name
628 if (type.takesArg)
629 line += ' ' + arg;
630 } else {
631 line += '--' + name
632 if (type.takesArg)
633 line += '=' + arg;
634 }
635 });
636 maxWidth = Math.max(maxWidth, line.length);
637 lines.push(line);
638 });
639
640 // Add help strings.
641 var helpCol = config.helpCol;
642 if (!helpCol) {
643 helpCol = maxWidth + indent.length + 2;
644 helpCol = Math.min(Math.max(helpCol, minHelpCol), maxHelpCol);
645 }
646 var i = -1;
647 this.options.forEach(function (o) {
648 if (o.hidden) {
649 return;
650 }
651 i++;
652
653 if (o.group !== undefined && o.group !== null) {
654 if (o.group === '') {
655 // Support a empty string "group" to have a blank line between
656 // sets of options.
657 lines[i] = '';
658 } else {
659 // Render the group heading with the heading-specific indent.
660 lines[i] = (i === 0 ? '' : '\n') + headingIndent +
661 o.group + ':';
662 }
663 return;
664 }
665
666 var helpDefault;
667 if (config.includeDefault) {
668 if (o.default !== undefined) {
669 helpDefault = format('Default: %j', o.default);
670 } else if (o.type && optionTypes[o.type].default !== undefined) {
671 helpDefault = format('Default: %j',
672 optionTypes[o.type].default);
673 }
674 }
675
676 var line = lines[i] = indent + lines[i];
677 if (!o.help && !(config.includeEnv && o.env) && !helpDefault) {
678 return;
679 }
680 var n = helpCol - line.length;
681 if (n >= 0) {
682 line += space(n);
683 } else {
684 line += '\n' + space(helpCol);
685 }
686
687 var helpEnv = '';
688 if (o.env && o.env.length && config.includeEnv) {
689 helpEnv += 'Environment: ';
690 var type = optionTypes[o.type];
691 var arg = o.helpArg || type.helpArg || 'ARG';
692 var envs = (Array.isArray(o.env) ? o.env : [o.env]).map(
693 function (e) {
694 if (type.takesArg) {
695 return e + '=' + arg;
696 } else {
697 return e + '=1';
698 }
699 }
700 );
701 helpEnv += envs.join(', ');
702 }
703 var help = (o.help || '').trim();
704 if (o.helpWrap !== false && config.helpWrap !== false) {
705 // Wrap help description normally.
706 if (help.length && !~'.!?"\''.indexOf(help.slice(-1))) {
707 help += '.';
708 }
709 if (help.length) {
710 help += ' ';
711 }
712 help += helpEnv;
713 if (helpDefault) {
714 if (helpEnv) {
715 help += '. ';
716 }
717 help += helpDefault;
718 }
719 line += textwrap(help, maxCol - helpCol).join(
720 '\n' + space(helpCol));
721 } else {
722 // Do not wrap help description, but indent newlines appropriately.
723 var helpLines = help.split('\n').filter(
724 function (ln) { return ln.length });
725 if (helpEnv !== '') {
726 helpLines.push(helpEnv);
727 }
728 if (helpDefault) {
729 helpLines.push(helpDefault);
730 }
731 line += helpLines.join('\n' + space(helpCol));
732 }
733
734 lines[i] = line;
735 });
736
737 var rv = '';
738 if (lines.length > 0) {
739 rv = lines.join('\n') + '\n';
740 }
741 return rv;
742};
743
744
745/**
746 * Return a string suitable for a Bash completion file for this tool.
747 *
748 * @param args.name {String} The tool name.
749 * @param args.specExtra {String} Optional. Extra Bash code content to add
750 * to the end of the "spec". Typically this is used to append Bash
751 * "complete_TYPE" functions for custom option types. See
752 * "examples/ddcompletion.js" for an example.
753 * @param args.argtypes {Array} Optional. Array of completion types for
754 * positional args (i.e. non-options). E.g.
755 * argtypes = ['fruit', 'veggie', 'file']
756 * will result in completion of fruits for the first arg, veggies for the
757 * second, and filenames for the third and subsequent positional args.
758 * If not given, positional args will use Bash's 'default' completion.
759 * See `specExtra` for providing Bash `complete_TYPE` functions, e.g.
760 * `complete_fruit` and `complete_veggie` in this example.
761 */
762Parser.prototype.bashCompletion = function bashCompletion(args) {
763 assert.object(args, 'args');
764 assert.string(args.name, 'args.name');
765 assert.optionalString(args.specExtra, 'args.specExtra');
766 assert.optionalArrayOfString(args.argtypes, 'args.argtypes');
767
768 return bashCompletionFromOptions({
769 name: args.name,
770 specExtra: args.specExtra,
771 argtypes: args.argtypes,
772 options: this.options
773 });
774};
775
776
777// ---- Bash completion
778
779const BASH_COMPLETION_TEMPLATE_PATH = path.join(
780 __dirname, '../etc/dashdash.bash_completion.in');
781
782/**
783 * Return the Bash completion "spec" (the string value for the "{{spec}}"
784 * var in the "dashdash.bash_completion.in" template) for this tool.
785 *
786 * The "spec" is Bash code that defines the CLI options and subcmds for
787 * the template's completion code. It looks something like this:
788 *
789 * local cmd_shortopts="-J ..."
790 * local cmd_longopts="--help ..."
791 * local cmd_optargs="-p=tritonprofile ..."
792 *
793 * @param args.options {Array} The array of dashdash option specs.
794 * @param args.context {String} Optional. A context string for the "local cmd*"
795 * vars in the spec. By default it is the empty string. When used to
796 * scope for completion on a *sub-command* (e.g. for "git log" on a "git"
797 * tool), then it would have a value (e.g. "__log"). See
798 * <http://github.com/trentm/node-cmdln> Bash completion for details.
799 * @param opts.includeHidden {Boolean} Optional. Default false. By default
800 * hidden options and subcmds are "excluded". Here excluded means they
801 * won't be offered as a completion, but if used, their argument type
802 * will be completed. "Hidden" options and subcmds are ones with the
803 * `hidden: true` attribute to exclude them from default help output.
804 * @param args.argtypes {Array} Optional. Array of completion types for
805 * positional args (i.e. non-options). E.g.
806 * argtypes = ['fruit', 'veggie', 'file']
807 * will result in completion of fruits for the first arg, veggies for the
808 * second, and filenames for the third and subsequent positional args.
809 * If not given, positional args will use Bash's 'default' completion.
810 * See `specExtra` for providing Bash `complete_TYPE` functions, e.g.
811 * `complete_fruit` and `complete_veggie` in this example.
812 */
813function bashCompletionSpecFromOptions(args) {
814 assert.object(args, 'args');
815 assert.object(args.options, 'args.options');
816 assert.optionalString(args.context, 'args.context');
817 assert.optionalBool(args.includeHidden, 'args.includeHidden');
818 assert.optionalArrayOfString(args.argtypes, 'args.argtypes');
819
820 var context = args.context || '';
821 var includeHidden = (args.includeHidden === undefined
822 ? false : args.includeHidden);
823
824 var spec = [];
825 var shortopts = [];
826 var longopts = [];
827 var optargs = [];
828 (args.options || []).forEach(function (o) {
829 if (o.group !== undefined && o.group !== null) {
830 // Skip group headers.
831 return;
832 }
833
834 var optNames = o.names || [o.name];
835 var optType = getOptionType(o.type);
836 if (optType.takesArg) {
837 var completionType = o.completionType ||
838 optType.completionType || o.type;
839 optNames.forEach(function (optName) {
840 if (optName.length === 1) {
841 if (includeHidden || !o.hidden) {
842 shortopts.push('-' + optName);
843 }
844 // Include even hidden options in `optargs` so that bash
845 // completion of its arg still works.
846 optargs.push('-' + optName + '=' + completionType);
847 } else {
848 if (includeHidden || !o.hidden) {
849 longopts.push('--' + optName);
850 }
851 optargs.push('--' + optName + '=' + completionType);
852 }
853 });
854 } else {
855 optNames.forEach(function (optName) {
856 if (includeHidden || !o.hidden) {
857 if (optName.length === 1) {
858 shortopts.push('-' + optName);
859 } else {
860 longopts.push('--' + optName);
861 }
862 }
863 });
864 }
865 });
866
867 spec.push(format('local cmd%s_shortopts="%s"',
868 context, shortopts.sort().join(' ')));
869 spec.push(format('local cmd%s_longopts="%s"',
870 context, longopts.sort().join(' ')));
871 spec.push(format('local cmd%s_optargs="%s"',
872 context, optargs.sort().join(' ')));
873 if (args.argtypes) {
874 spec.push(format('local cmd%s_argtypes="%s"',
875 context, args.argtypes.join(' ')));
876 }
877 return spec.join('\n');
878}
879
880
881/**
882 * Return a string suitable for a Bash completion file for this tool.
883 *
884 * @param args.name {String} The tool name.
885 * @param args.options {Array} The array of dashdash option specs.
886 * @param args.specExtra {String} Optional. Extra Bash code content to add
887 * to the end of the "spec". Typically this is used to append Bash
888 * "complete_TYPE" functions for custom option types. See
889 * "examples/ddcompletion.js" for an example.
890 * @param args.argtypes {Array} Optional. Array of completion types for
891 * positional args (i.e. non-options). E.g.
892 * argtypes = ['fruit', 'veggie', 'file']
893 * will result in completion of fruits for the first arg, veggies for the
894 * second, and filenames for the third and subsequent positional args.
895 * If not given, positional args will use Bash's 'default' completion.
896 * See `specExtra` for providing Bash `complete_TYPE` functions, e.g.
897 * `complete_fruit` and `complete_veggie` in this example.
898 */
899function bashCompletionFromOptions(args) {
900 assert.object(args, 'args');
901 assert.object(args.options, 'args.options');
902 assert.string(args.name, 'args.name');
903 assert.optionalString(args.specExtra, 'args.specExtra');
904 assert.optionalArrayOfString(args.argtypes, 'args.argtypes');
905
906 // Gather template data.
907 var data = {
908 name: args.name,
909 date: new Date(),
910 spec: bashCompletionSpecFromOptions({
911 options: args.options,
912 argtypes: args.argtypes
913 }),
914 };
915 if (args.specExtra) {
916 data.spec += '\n\n' + args.specExtra;
917 }
918
919 // Render template.
920 var template = fs.readFileSync(BASH_COMPLETION_TEMPLATE_PATH, 'utf8');
921 return renderTemplate(template, data);
922}
923
924
925
926// ---- exports
927
928function createParser(config) {
929 return new Parser(config);
930}
931
932/**
933 * Parse argv with the given options.
934 *
935 * @param config {Object} A merge of all the available fields from
936 * `dashdash.Parser` and `dashdash.Parser.parse`: options, interspersed,
937 * argv, env, slice.
938 */
939function parse(config) {
940 assert.object(config, 'config');
941 assert.optionalArrayOfString(config.argv, 'config.argv');
942 assert.optionalObject(config.env, 'config.env');
943 var config = shallowCopy(config);
944 var argv = config.argv;
945 delete config.argv;
946 var env = config.env;
947 delete config.env;
948
949 var parser = new Parser(config);
950 return parser.parse({argv: argv, env: env});
951}
952
953
954/**
955 * Add a new option type.
956 *
957 * @params optionType {Object}:
958 * - name {String} Required.
959 * - takesArg {Boolean} Required. Whether this type of option takes an
960 * argument on process.argv. Typically this is true for all but the
961 * "bool" type.
962 * - helpArg {String} Required iff `takesArg === true`. The string to
963 * show in generated help for options of this type.
964 * - parseArg {Function} Require. `function (option, optstr, arg)` parser
965 * that takes a string argument and returns an instance of the
966 * appropriate type, or throws an error if the arg is invalid.
967 * - array {Boolean} Optional. Set to true if this is an 'arrayOf' type
968 * that collects multiple usages of the option in process.argv and
969 * puts results in an array.
970 * - arrayFlatten {Boolean} Optional. XXX
971 * - default Optional. Default value for options of this type, if no
972 * default is specified in the option type usage.
973 */
974function addOptionType(optionType) {
975 assert.object(optionType, 'optionType');
976 assert.string(optionType.name, 'optionType.name');
977 assert.bool(optionType.takesArg, 'optionType.takesArg');
978 if (optionType.takesArg) {
979 assert.string(optionType.helpArg, 'optionType.helpArg');
980 }
981 assert.func(optionType.parseArg, 'optionType.parseArg');
982 assert.optionalBool(optionType.array, 'optionType.array');
983 assert.optionalBool(optionType.arrayFlatten, 'optionType.arrayFlatten');
984
985 optionTypes[optionType.name] = {
986 takesArg: optionType.takesArg,
987 helpArg: optionType.helpArg,
988 parseArg: optionType.parseArg,
989 array: optionType.array,
990 arrayFlatten: optionType.arrayFlatten,
991 default: optionType.default
992 }
993}
994
995
996function getOptionType(name) {
997 assert.string(name, 'name');
998 return optionTypes[name];
999}
1000
1001
1002/**
1003 * Return a synopsis string for the given option spec.
1004 *
1005 * Examples:
1006 * > synopsisFromOpt({names: ['help', 'h'], type: 'bool'});
1007 * '[ --help | -h ]'
1008 * > synopsisFromOpt({name: 'file', type: 'string', helpArg: 'FILE'});
1009 * '[ --file=FILE ]'
1010 */
1011function synopsisFromOpt(o) {
1012 assert.object(o, 'o');
1013
1014 if (o.hasOwnProperty('group')) {
1015 return null;
1016 }
1017 var names = o.names || [o.name];
1018 // `type` here could be undefined if, for example, the command has a
1019 // dashdash option spec with a bogus 'type'.
1020 var type = getOptionType(o.type);
1021 var helpArg = o.helpArg || (type && type.helpArg) || 'ARG';
1022 var parts = [];
1023 names.forEach(function (name) {
1024 var part = (name.length === 1 ? '-' : '--') + name;
1025 if (type && type.takesArg) {
1026 part += (name.length === 1 ? ' ' + helpArg : '=' + helpArg);
1027 }
1028 parts.push(part);
1029 });
1030 return ('[ ' + parts.join(' | ') + ' ]');
1031};
1032
1033
1034module.exports = {
1035 createParser: createParser,
1036 Parser: Parser,
1037 parse: parse,
1038 addOptionType: addOptionType,
1039 getOptionType: getOptionType,
1040 synopsisFromOpt: synopsisFromOpt,
1041
1042 // Bash completion-related exports
1043 BASH_COMPLETION_TEMPLATE_PATH: BASH_COMPLETION_TEMPLATE_PATH,
1044 bashCompletionFromOptions: bashCompletionFromOptions,
1045 bashCompletionSpecFromOptions: bashCompletionSpecFromOptions,
1046
1047 // Export the parseFoo parsers because they might be useful as primitives
1048 // for custom option types.
1049 parseBool: parseBool,
1050 parseString: parseString,
1051 parseNumber: parseNumber,
1052 parseInteger: parseInteger,
1053 parsePositiveInteger: parsePositiveInteger,
1054 parseDate: parseDate
1055};
Note: See TracBrowser for help on using the repository browser.