archive-gh-me/jsdoc
1
0
Fork 0
mirror of https://github.com/jsdoc/jsdoc.git synced 2025-12-08 19:46:11 +00:00
Code Issues Projects Releases Wiki Activity

reorganize/rename option-parsing files, plus some minor cleanup

Browse Source
This commit is contained in:
Jeff Williams 2012-11-06 05:15:22 -08:00
parent 42711b3cf8
commit 7cd2737306
6 changed files with 254 additions and 248 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
jsdoc.js
View File

@ -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();

170
rhino_modules/common/args.js
View File

@ -1,170 +0,0 @@
/**
Parse the command line arguments.
@module common/args
@author Michael Mathews <micmath@gmail.com>
@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 += ' <value>';
}
optionHelp += '\t\t' + option.helpText;
helpArr.push(optionHelp);
}
return helpArr.join('\n');
};
/**
Get the options.
@param {Array.<string>} 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;
};
})();

177
rhino_modules/jsdoc/opts/argparser.js Normal file
View File

@ -0,0 +1,177 @@
/**
Parse the command line arguments.
@module jsdoc/opts/argparser
@author Michael Mathews <micmath@gmail.com>
@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 += ' <value>';
}
optionHelp += '\t\t' + option.helpText;
helpArr.push(optionHelp);
}
return helpArr.join('\n');
};
/**
Get the options.
@param {Array.<string>} 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;

11
rhino_modules/jsdoc/opts/parser.js → rhino_modules/jsdoc/opts/args.js
View File

@ -1,15 +1,12 @@
/**
@module jsdoc/opts/parser
@requires common/args
@module jsdoc/opts/args
@requires jsdoc/opts/argparser
@author Michael Mathews <micmath@gmail.com>
@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/'

11
test/specs/common/args.js → test/specs/jsdoc/opts/argparser.js
View File

@ -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');
});

129
test/specs/jsdoc/opts/parser.js → test/specs/jsdoc/opts/args.js
View File

@ -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']);
});