From 7cd2737306cb067bb64f6f099b157a8d02f81e69 Mon Sep 17 00:00:00 2001 From: Jeff Williams Date: Tue, 6 Nov 2012 05:15:22 -0800 Subject: [PATCH] reorganize/rename option-parsing files, plus some minor cleanup --- jsdoc.js | 4 +- rhino_modules/common/args.js | 170 ----------------- rhino_modules/jsdoc/opts/argparser.js | 177 ++++++++++++++++++ .../jsdoc/opts/{parser.js => args.js} | 11 +- .../args.js => jsdoc/opts/argparser.js} | 11 +- test/specs/jsdoc/opts/{parser.js => args.js} | 129 ++++++------- 6 files changed, 254 insertions(+), 248 deletions(-) delete mode 100644 rhino_modules/common/args.js create mode 100644 rhino_modules/jsdoc/opts/argparser.js rename rhino_modules/jsdoc/opts/{parser.js => args.js} (95%) rename test/specs/{common/args.js => jsdoc/opts/argparser.js} (69%) rename test/specs/jsdoc/opts/{parser.js => args.js} (65%) diff --git a/jsdoc.js b/jsdoc.js index c30f8d03..e603f966 100644 --- a/jsdoc.js +++ b/jsdoc.js @@ -186,7 +186,7 @@ function main() { docs, jsdoc = { opts: { - parser: require('jsdoc/opts/parser'), + args: require('jsdoc/opts/args'), } }, resolver, @@ -286,7 +286,7 @@ function main() { } - env.opts = jsdoc.opts.parser.parse(env.args); + env.opts = jsdoc.opts.args.parse(env.args); env.vm = detectVm(); diff --git a/rhino_modules/common/args.js b/rhino_modules/common/args.js deleted file mode 100644 index c221246c..00000000 --- a/rhino_modules/common/args.js +++ /dev/null @@ -1,170 +0,0 @@ -/** - Parse the command line arguments. - @module common/args - @author Michael Mathews - @license Apache License 2.0 - See file 'LICENSE.md' in this project. - */ -(function() { - var hasOwnProp = Object.prototype.hasOwnProperty; - - /** - Create an instance of the parser. - @classdesc A parser to interpret the key value pairs entered on the command - line. - @constructor - */ - exports.ArgParser = function() { - this._options = []; - this._shortNameIndex = {}; - this._longNameIndex = {}; - }; - - exports.ArgParser.prototype._getOptionByShortName = function(name) { - if (hasOwnProp.call(this._shortNameIndex, name)) { - return this._options[this._shortNameIndex[name]]; - } - return null; - }; - - exports.ArgParser.prototype._getOptionByLongName = function(name) { - if (hasOwnProp.call(this._longNameIndex, name)) { - return this._options[this._longNameIndex[name]]; - } - return null; - }; - - /** - * Provide information about a legal option. - * @param {character} shortName The short name of the option, entered like: -T. - * @param {string} longName The equivalent long name of the option, entered like: --test. - * @param {boolean} hasValue Does this option require a value? Like: -t templatename - * @param {string} helpText - * @param {boolean} [canHaveMultiple=false] - * @param {function} [coercer] A function to coerce the given value to a specific type. - * @example - * myParser.addOption('t', 'template', true, 'The path to the template.'); - * myParser.addOption('h', 'help', false, 'Show the help message.'); - */ - exports.ArgParser.prototype.addOption = function(shortName, longName, hasValue, helpText, canHaveMultiple, coercer) { - this._options.push({shortName: shortName, longName: longName, hasValue: hasValue, helpText: helpText, canHaveMultiple: (canHaveMultiple || false), coercer: coercer}); - - if (shortName) { - this._shortNameIndex[shortName] = this._options.length - 1; - } - if (longName) { - this._longNameIndex[longName] = this._options.length - 1; - } - }; - - /** - Generate a summary of all the options with corresponding help text. - @returns {string} - */ - exports.ArgParser.prototype.help = function() { - var helpArr = ['OPTIONS:'], - option, optionHelp; - - for (var i = 0, leni = this._options.length; i < leni; i++) { - option = this._options[i]; - optionHelp = '\t'; - - if (option.shortName) { - optionHelp += '-' + option.shortName + (option.longName ? ', ' : ''); - } - - if (option.longName) { - optionHelp += '--' + option.longName; - } - - if (option.hasValue) { - optionHelp += ' '; - } - - optionHelp += '\t\t' + option.helpText; - helpArr.push(optionHelp); - } - - return helpArr.join('\n'); - }; - - /** - Get the options. - @param {Array.} args An array, like ['-x', 'hello'] - @param {Object} [defaults={}] An optional collection of default values. - @returns {Object} The keys will be the longNames, or the shortName if - no longName is defined for that option. The values will be the values - provided, or `true` if the option accepts no value. - */ - exports.ArgParser.prototype.parse = function(args, defaults) { - var util = require('common/util'), - result = defaults && util.mixin({}, defaults) || {}; - - result._ = []; - for (var i = 0, leni = args.length; i < leni; i++) { - var arg = '' + args[i], - next = (i < leni-1)? '' + args[i+1] : null, - option, - shortName = null, - longName, - name, - value = null; - - // like -t - if (arg.charAt(0) === '-') { - - // like: --template - if (arg.charAt(1) === '-') { - name = longName = arg.slice(2); - option = this._getOptionByLongName(longName); - } - else { - name = shortName = arg.slice(1); - option = this._getOptionByShortName(shortName); - } - - if (option === null) { - throw new Error( 'Unknown command line option found: ' + name ); - } - - if (option.hasValue) { - value = next; - i++; - - if (value === null || value.charAt(0) === '-') { - throw new Error( 'Command line option requires a value: ' + name ); - } - } - else { - value = true; - } - - if (option.longName && shortName) { - name = option.longName; - } - - if (typeof option.coercer === 'function') { - value = option.coercer(value); - } - - // Allow for multiple options of the same type to be present - if (option.canHaveMultiple && hasOwnProp.call(result, name)) { - var val = result[name]; - - if (val instanceof Array) { - val.push(value); - } else { - result[name] = [val, value]; - } - } - else { - result[name] = value; - } - } - else { - result._.push(arg); - } - } - - return result; - }; -})(); \ No newline at end of file diff --git a/rhino_modules/jsdoc/opts/argparser.js b/rhino_modules/jsdoc/opts/argparser.js new file mode 100644 index 00000000..3124222a --- /dev/null +++ b/rhino_modules/jsdoc/opts/argparser.js @@ -0,0 +1,177 @@ +/** + Parse the command line arguments. + @module jsdoc/opts/argparser + @author Michael Mathews + @license Apache License 2.0 - See file 'LICENSE.md' in this project. + */ +var hasOwnProp = Object.prototype.hasOwnProperty; + +/** + Create an instance of the parser. + @classdesc A parser to interpret the key-value pairs entered on the command + line. + @constructor + */ +var ArgParser = function() { + this._options = []; + this._shortNameIndex = {}; + this._longNameIndex = {}; +}; + +ArgParser.prototype._getOptionByShortName = function(name) { + if (hasOwnProp.call(this._shortNameIndex, name)) { + return this._options[this._shortNameIndex[name]]; + } + return null; +}; + +ArgParser.prototype._getOptionByLongName = function(name) { + if (hasOwnProp.call(this._longNameIndex, name)) { + return this._options[this._longNameIndex[name]]; + } + return null; +}; + +/** + * Provide information about a legal option. + * @param {character} shortName The short name of the option, entered like: -T. + * @param {string} longName The equivalent long name of the option, entered like: --test. + * @param {boolean} hasValue Does this option require a value? Like: -t templatename + * @param {string} helpText A brief description of the option. + * @param {boolean} [canHaveMultiple=false] Set to `true` if the option can be provided more than once. + * @param {function} [coercer] A function to coerce the given value to a specific type. + * @example + * myParser.addOption('t', 'template', true, 'The path to the template.'); + * myParser.addOption('h', 'help', false, 'Show the help message.'); + */ +ArgParser.prototype.addOption = function(shortName, longName, hasValue, helpText, canHaveMultiple, coercer) { + this._options.push({ + shortName: shortName, + longName: longName, + hasValue: hasValue, + helpText: helpText, + canHaveMultiple: (canHaveMultiple || false), + coercer: coercer + }); + + if (shortName) { + this._shortNameIndex[shortName] = this._options.length - 1; + } + if (longName) { + this._longNameIndex[longName] = this._options.length - 1; + } +}; + +/** + Generate a summary of all the options with corresponding help text. + @returns {string} + */ +ArgParser.prototype.help = function() { + var helpArr = ['OPTIONS:'], + option, optionHelp; + + for (var i = 0, leni = this._options.length; i < leni; i++) { + option = this._options[i]; + optionHelp = '\t'; + + if (option.shortName) { + optionHelp += '-' + option.shortName + (option.longName ? ', ' : ''); + } + + if (option.longName) { + optionHelp += '--' + option.longName; + } + + if (option.hasValue) { + optionHelp += ' '; + } + + optionHelp += '\t\t' + option.helpText; + helpArr.push(optionHelp); + } + + return helpArr.join('\n'); +}; + +/** + Get the options. + @param {Array.} args An array, like ['-x', 'hello'] + @param {Object} [defaults={}] An optional collection of default values. + @returns {Object} The keys will be the longNames, or the shortName if + no longName is defined for that option. The values will be the values + provided, or `true` if the option accepts no value. + */ +ArgParser.prototype.parse = function(args, defaults) { + var util = require('common/util'), + result = defaults && util.mixin({}, defaults) || {}; + + result._ = []; + for (var i = 0, leni = args.length; i < leni; i++) { + var arg = '' + args[i], + next = (i < leni-1)? '' + args[i+1] : null, + option, + shortName = null, + longName, + name, + value = null; + + // like -t + if (arg.charAt(0) === '-') { + + // like --template + if (arg.charAt(1) === '-') { + name = longName = arg.slice(2); + option = this._getOptionByLongName(longName); + } + else { + name = shortName = arg.slice(1); + option = this._getOptionByShortName(shortName); + } + + if (option === null) { + throw new Error( 'Unknown command line option found: ' + name ); + } + + if (option.hasValue) { + value = next; + i++; + + if (value === null || value.charAt(0) === '-') { + throw new Error( 'Command line option requires a value: ' + name ); + } + } + else { + value = true; + } + + if (option.longName && shortName) { + name = option.longName; + } + + if (typeof option.coercer === 'function') { + value = option.coercer(value); + } + + // Allow for multiple options of the same type to be present + if (option.canHaveMultiple && hasOwnProp.call(result, name)) { + var val = result[name]; + + if (val instanceof Array) { + val.push(value); + } else { + result[name] = [val, value]; + } + } + else { + result[name] = value; + } + } + else { + result._.push(arg); + } + } + + return result; +}; + +module.exports = ArgParser; diff --git a/rhino_modules/jsdoc/opts/parser.js b/rhino_modules/jsdoc/opts/args.js similarity index 95% rename from rhino_modules/jsdoc/opts/parser.js rename to rhino_modules/jsdoc/opts/args.js index b4011438..42490b87 100644 --- a/rhino_modules/jsdoc/opts/parser.js +++ b/rhino_modules/jsdoc/opts/args.js @@ -1,15 +1,12 @@ /** - @module jsdoc/opts/parser - @requires common/args + @module jsdoc/opts/args + @requires jsdoc/opts/argparser @author Michael Mathews @license Apache License 2.0 - See file 'LICENSE.md' in this project. */ -var common = { - args: require('common/args') -}; - -var argParser = new common.args.ArgParser(), +var ArgParser = require('jsdoc/opts/argparser'), + argParser = new ArgParser(), ourOptions, defaults = { destination: './out/' diff --git a/test/specs/common/args.js b/test/specs/jsdoc/opts/argparser.js similarity index 69% rename from test/specs/common/args.js rename to test/specs/jsdoc/opts/argparser.js index 2dd564c4..5d4c1583 100644 --- a/test/specs/common/args.js +++ b/test/specs/jsdoc/opts/argparser.js @@ -1,6 +1,7 @@ -describe("common/args", function() { - var common = {args: require('common/args')}, - argParser = new common.args.ArgParser(), +/*global describe: true, expect: true, it: true */ +describe("jsdoc/opts/argparser", function() { + var ArgParser = require('jsdoc/opts/argparser'), + argParser = new ArgParser(), ourOptions; function trueFalse(v) { @@ -19,12 +20,12 @@ describe("common/args", function() { ourOptions = argParser.parse(['-s', 'true', '-n', 'true']); - it('should corece a true value if a coercer is provided', function() { + it('should coerce a true value if a coercer is provided', function() { expect(ourOptions.strict).toBeDefined(); expect(ourOptions.strict).toEqual(true); }); - it('should corece a string value if a no coercer is provided', function() { + it('should coerce a string value if no coercer is provided', function() { expect(ourOptions.name).toBeDefined(); expect(ourOptions.name).toEqual('true'); }); diff --git a/test/specs/jsdoc/opts/parser.js b/test/specs/jsdoc/opts/args.js similarity index 65% rename from test/specs/jsdoc/opts/parser.js rename to test/specs/jsdoc/opts/args.js index eeb08d0d..4100bf95 100644 --- a/test/specs/jsdoc/opts/parser.js +++ b/test/specs/jsdoc/opts/args.js @@ -1,212 +1,213 @@ -describe("jsdoc/opts/parser", function() { - var opts = require('jsdoc/opts/parser'); +/*global describe: true, expect: true, it: true */ +describe("jsdoc/opts/args", function() { + var args = require('jsdoc/opts/args'); it("should exist", function() { - expect(opts).toBeDefined(); - expect(typeof opts).toEqual("object"); + expect(args).toBeDefined(); + expect(typeof args).toEqual("object"); }); it("should export a 'parse' function", function() { - expect(opts.parse).toBeDefined(); - expect(typeof opts.parse).toEqual("function"); + expect(args.parse).toBeDefined(); + expect(typeof args.parse).toEqual("function"); }); it("should export a 'help' function", function() { - expect(opts.help).toBeDefined(); - expect(typeof opts.help).toEqual("function"); + expect(args.help).toBeDefined(); + expect(typeof args.help).toEqual("function"); }); it("should export a 'get' function", function() { - expect(opts.get).toBeDefined(); - expect(typeof opts.get).toEqual("function"); + expect(args.get).toBeDefined(); + expect(typeof args.get).toEqual("function"); }); describe("parse", function() { it("should accept a '-t' option and return an object with a 'template' property", function() { - opts.parse(['-t', 'mytemplate']); - var r = opts.get(); + args.parse(['-t', 'mytemplate']); + var r = args.get(); expect(r.template).toEqual('mytemplate'); }); it("should accept a '--template' option and return an object with a 'template' property", function() { - opts.parse(['--template', 'mytemplate']); - var r = opts.get(); + args.parse(['--template', 'mytemplate']); + var r = args.get(); expect(r.template).toEqual('mytemplate'); }); it("should accept a '-c' option and return an object with a 'configure' property", function() { - opts.parse(['-c', 'myconf.json']); - var r = opts.get(); + args.parse(['-c', 'myconf.json']); + var r = args.get(); expect(r.configure).toEqual('myconf.json'); }); it("should accept a '--configure' option and return an object with a 'configure' property", function() { - opts.parse(['--configure', 'myconf.json']); - var r = opts.get(); + args.parse(['--configure', 'myconf.json']); + var r = args.get(); expect(r.configure).toEqual('myconf.json'); }); it("should accept a '-e' option and return an object with a 'encoding' property", function() { - opts.parse(['-e', 'ascii']); - var r = opts.get(); + args.parse(['-e', 'ascii']); + var r = args.get(); expect(r.encoding).toEqual('ascii'); }); it("should accept a '--encoding' option and return an object with a 'encoding' property", function() { - opts.parse(['--encoding', 'ascii']); - var r = opts.get(); + args.parse(['--encoding', 'ascii']); + var r = args.get(); expect(r.encoding).toEqual('ascii'); }); it("should accept a '-T' option and return an object with a 'test' property", function() { - opts.parse(['-T']); - var r = opts.get(); + args.parse(['-T']); + var r = args.get(); expect(r.test).toEqual(true); }); it("should accept a '--test' option and return an object with a 'test' property", function() { - opts.parse(['--test']); - var r = opts.get(); + args.parse(['--test']); + var r = args.get(); expect(r.test).toEqual(true); }); it("should accept a '-d' option and return an object with a 'destination' property", function() { - opts.parse(['-d', 'mydestination']); - var r = opts.get(); + args.parse(['-d', 'mydestination']); + var r = args.get(); expect(r.destination).toEqual('mydestination'); }); it("should accept a '--destination' option and return an object with a 'destination' property", function() { - opts.parse(['--destination', 'mydestination']); - var r = opts.get(); + args.parse(['--destination', 'mydestination']); + var r = args.get(); expect(r.destination).toEqual('mydestination'); }); it("should accept a '-p' option and return an object with a 'private' property", function() { - opts.parse(['-p']); - var r = opts.get(); + args.parse(['-p']); + var r = args.get(); expect(r['private']).toEqual(true); }); it("should accept a '--private' option and return an object with a 'private' property", function() { - opts.parse(['--private']); - var r = opts.get(); + args.parse(['--private']); + var r = args.get(); expect(r['private']).toEqual(true); }); it("should accept a '-r' option and return an object with a 'recurse' property", function() { - opts.parse(['-r']); - var r = opts.get(); + args.parse(['-r']); + var r = args.get(); expect(r.recurse).toEqual(true); }); it("should accept a '--recurse' option and return an object with a 'recurse' property", function() { - opts.parse(['--recurse']); - var r = opts.get(); + args.parse(['--recurse']); + var r = args.get(); expect(r.recurse).toEqual(true); }); it("should accept a '-h' option and return an object with a 'help' property", function() { - opts.parse(['-h']); - var r = opts.get(); + args.parse(['-h']); + var r = args.get(); expect(r.help).toEqual(true); }); it("should accept a '--help' option and return an object with a 'help' property", function() { - opts.parse(['--help']); - var r = opts.get(); + args.parse(['--help']); + var r = args.get(); expect(r.help).toEqual(true); }); it("should accept a '-X' option and return an object with a 'explain' property", function() { - opts.parse(['-X']); - var r = opts.get(); + args.parse(['-X']); + var r = args.get(); expect(r.explain).toEqual(true); }); it("should accept a '--explain' option and return an object with a 'explain' property", function() { - opts.parse(['--explain']); - var r = opts.get(); + args.parse(['--explain']); + var r = args.get(); expect(r.explain).toEqual(true); }); it("should accept a '-q' option and return an object with a 'query' property", function() { - opts.parse(['-q', 'foo=bar&fab=baz']); - var r = opts.get(); + args.parse(['-q', 'foo=bar&fab=baz']); + var r = args.get(); expect(r.query).toEqual('foo=bar&fab=baz'); }); it("should accept a '--query' option and return an object with a 'query' property", function() { - opts.parse(['--query', 'foo=bar&fab=baz']); - var r = opts.get(); + args.parse(['--query', 'foo=bar&fab=baz']); + var r = args.get(); expect(r.query).toEqual('foo=bar&fab=baz'); }); it("should accept a '-t' option and return an object with a 'tutorials' property", function() { - opts.parse(['-d', 'mytutorials']); - var r = opts.get(); + args.parse(['-d', 'mytutorials']); + var r = args.get(); expect(r.destination).toEqual('mytutorials'); }); it("should accept a '--tutorials' option and return an object with a 'tutorials' property", function() { - opts.parse(['--tutorials', 'mytutorials']); - var r = opts.get(); + args.parse(['--tutorials', 'mytutorials']); + var r = args.get(); expect(r.tutorials).toEqual('mytutorials'); }); it("should accept a naked option (i.e. no '-') and return an object with a '_' property", function() { - opts.parse(['myfile1', 'myfile2']); - var r = opts.get(); + args.parse(['myfile1', 'myfile2']); + var r = args.get(); expect(r._).toEqual(['myfile1', 'myfile2']); }); it("should accept a '--verbose' option and return an object with a 'verbose' property", function() { - opts.parse(['--verbose']); - var r = opts.get(); + args.parse(['--verbose']); + var r = args.get(); expect(r.verbose).toEqual(true); }); it("should accept a '--nocolor' option and return an object with a 'nocolor' property", function() { - opts.parse(['--nocolor']); - var r = opts.get(); + args.parse(['--nocolor']); + var r = args.get(); expect(r.nocolor).toEqual(true); }); it("should accept a '--match' option and return an object with a 'match' property", function() { - opts.parse(['--match', '.*tag']); - var r = opts.get(); + args.parse(['--match', '.*tag']); + var r = args.get(); expect(r.match).toEqual('.*tag'); }); it("should accept a multiple '--match' options and return an object with a 'match' property", function() { - opts.parse(['--match', '.*tag', '--match', 'parser']); - var r = opts.get(); + args.parse(['--match', '.*tag', '--match', 'parser']); + var r = args.get(); expect(r.match).toEqual(['.*tag', 'parser']); });