Skip to content
Browse files

Better docs and help

  • Loading branch information...
1 parent ab99528 commit d0b92ba72cc25e71d9d36d6030194453fb88be82 @dpup committed Mar 25, 2011
Showing with 90 additions and 3 deletions.
  1. +5 −2 examples/example.js
  2. +85 −1 lib/flags.js
View
7 examples/example.js
@@ -13,8 +13,8 @@ var flags = require('flags');
flags.defineString('name', 'Billy Noone', 'Your name');
flags.defineInteger('age', 21, 'Your age in whole years');
flags.defineNumber('height', 1.80, 'Your height in meters');
-flags.defineStringList('pets', []);
-flags.defineMultiString('hobby', []);
+flags.defineStringList('pets', [], 'Comma separated list of your pets');
+flags.defineMultiString('hobby', [], 'A hobby');
flags.parse();
@@ -28,3 +28,6 @@ info.push('Pets : ' + flags.get('pets').join(', '));
info.push('Hobbies : \n ' + flags.get('hobby').join('\n '));
console.log(info.join('\n'));
+
+console.log('\nHelp Text:');
+flags.help();
View
86 lib/flags.js
@@ -6,49 +6,129 @@
var util = require('util');
+
+/**
+ * An object containing a map of flag objects.
+ * @type {!Object}
+ */
var FLAGS = exports.FLAGS = {};
+
+/**
+ * Defines a string flag. e.g. --servername=bob
+ * @param {string} name The flag name, should be [a-zA-Z0-9]+.
+ * @param {string} defaultValue The default value, should the flag not be
+ * explicitly specified.
+ * @param {string=} opt_description Optional description to use in help text.
+ * @param {function(string)=} opt_validator Optional validator function that
+ * will be called when parsing flags. Should throw if the input is not
+ * valid.
+ */
exports.defineString = function(name, defaultValue, opt_description, opt_validator) {
addFlag(name, new Flag(name, defaultValue, opt_description, opt_validator));
};
+/**
+ * Defines a boolean flag. e.g. --turnonlights
+ * @param {string} name The flag name, should be [a-zA-Z0-9]+.
+ * @param {boolean} defaultValue The default value, should the flag not be
+ * explicitly specified.
+ * @param {string=} opt_description Optional description to use in help text.
+ * @param {function(string)=} opt_validator Optional validator function that
+ * will be called when parsing flags. Should throw if the input is not
+ * valid.
+ */
exports.defineBoolean = function(name, defaultValue, opt_description, opt_validator) {
addFlag(name, new BooleanFlag(name, defaultValue, opt_description, opt_validator));
};
+/**
+ * Defines an integer flag. e.g. --age=12
+ * @param {string} name The flag name, should be [a-zA-Z0-9]+.
+ * @param {number} defaultValue The default value, should the flag not be
+ * explicitly specified.
+ * @param {string=} opt_description Optional description to use in help text.
+ * @param {function(string)=} opt_validator Optional validator function that
+ * will be called when parsing flags. Should throw if the input is not
+ * valid.
+ */
exports.defineInteger = function(name, defaultValue, opt_description, opt_validator) {
addFlag(name, new IntegerFlag(name, defaultValue, opt_description, opt_validator));
};
+/**
+ * Defines a number flag. e.g. --number=1.345
+ * @param {string} name The flag name, should be [a-zA-Z0-9]+.
+ * @param {number} defaultValue The default value, should the flag not be
+ * explicitly specified.
+ * @param {string=} opt_description Optional description to use in help text.
+ * @param {function(string)=} opt_validator Optional validator function that
+ * will be called when parsing flags. Should throw if the input is not
+ * valid.
+ */
exports.defineNumber = function(name, defaultValue, opt_description, opt_validator) {
addFlag(name, new NumberFlag(name, defaultValue, opt_description, opt_validator));
};
+/**
+ * Defines a string list flag. e.g. --anmial=frog,bat,chicken
+ * @param {string} name The flag name, should be [a-zA-Z0-9]+.
+ * @param {!Array.<string>} defaultValue The default value, should the flag not be
+ * explicitly specified.
+ * @param {string=} opt_description Optional description to use in help text.
+ * @param {function(string)=} opt_validator Optional validator function that
+ * will be called when parsing flags. Should throw if the input is not
+ * valid.
+ */
exports.defineStringList = function(name, defaultValue, opt_description, opt_validator) {
addFlag(name, new StringListFlag(name, defaultValue, opt_description, opt_validator));
};
+/**
+ * Defines a multi string flag. e.g. --allowedip=127.0.0.1 --allowedip=127.0.0.2
+ * @param {string} name The flag name, should be [a-zA-Z0-9]+.
+ * @param {!Array.<string>} defaultValue The default value, should the flag not be
+ * explicitly specified.
+ * @param {string=} opt_description Optional description to use in help text.
+ * @param {function(string)=} opt_validator Optional validator function that
+ * will be called when parsing flags. Should throw if the input is not
+ * valid.
+ */
exports.defineMultiString = function(name, defaultValue, opt_description, opt_validator) {
addFlag(name, new MultiStringFlag(name, defaultValue, opt_description, opt_validator));
};
+/**
+ * Dumps the help text to the console.
+ */
exports.help = function() {
- console.log(util.inspect(FLAGS));
+ // TODO: make this suck less and automatically hook up to --help
+ for (var flag in FLAGS) {
+ console.log('--' + flag + ' : ' + FLAGS[flag].description);
+ }
};
+/**
+ * Resets the flag values.
+ */
exports.reset = function() {
parseCalled = false;
FLAGS = exports.FLAGS = {};
};
+/**
+ * Gets the current value of the given flag.
+ * @param {string} name The flag name.
+ * @return {*}
+ */
exports.get = function(name) {
if (!FLAGS[name]) throw Error('Unknown flag "' + name + '"');
return FLAGS[name].get(name);
@@ -57,6 +137,8 @@ exports.get = function(name) {
/**
* Parses process.argv for flags. Idempotent if called multiple times.
+ * @param {Array.<string>=} opt_args Optional arguments array to use instead of
+ * process.argv.
*/
exports.parse = function(opt_args) {
var args = opt_args || process.argv.slice(2);
@@ -102,6 +184,8 @@ exports.parse = function(opt_args) {
parseCalled = true;
};
+
+
// Private helpers
//==================

0 comments on commit d0b92ba

Please sign in to comment.
Something went wrong with that request. Please try again.