yargs 1.3.1 → 2.3.0

package/README.md

@@ -1,22 +1,21 @@
 yargs
 ========
 
-Yargs be a node.js library fer hearties tryin' ter parse optstrings against their will where even the boo box be not enough to coerce them. This here module is fer scallywags lookin' ter plunder all the sunken -shipz of their --treasures thru program usage but be tired of optstrings disincling to acquiesce to yer requests.
+Yargs be a node.js library fer hearties tryin' ter parse optstrings.
 
 With yargs, ye be havin' a map that leads straight to yer treasure! Treasure of course, being a simple option hash.
 
 [![Build Status](https://travis-ci.org/chevex/yargs.png)](https://travis-ci.org/chevex/yargs)
 [![Dependency Status](https://gemnasium.com/chevex/yargs.png)](https://gemnasium.com/chevex/yargs)
 [![NPM version](https://badge.fury.io/js/yargs.png)](http://badge.fury.io/js/yargs)
+[![Coverage Status](https://coveralls.io/repos/chevex/yargs/badge.svg?branch=)](https://coveralls.io/r/chevex/yargs?branch=)
 
-> ~~NOTE: Yargs is a fork of [optimist](https://github.com/substack/node-optimist) by [substack (James Halliday)](https://github.com/substack). It is obvious that substack is stretched pretty thin maintaining over 300 modules on npm at the time of this writing. So rather than complain in the project issue tracker I thought I'd just pick up the torch and maintain a proper fork. Currently the project is totally backward compatible with optimist but this may change in the future (if it does I will update this notice to inform you of this). For now though, enjoy optimist with about 5 months worth of fixes and updates rolled in, most of them pulled from optimist's own [stale pull requests](https://github.com/substack/node-optimist/pulls).~~
-
-> UPDATE: Yargs is now the official successor to optimist. Please feel free to submit issues and pull requests. While I personally don't have the time to pore over all the issues and fix all of them on a regular basis, I'm more than happy to look over pull requests, test them, and merge them in. If you'd like to contribute and don't know where to start, have a look at [the issue list](https://github.com/chevex/yargs/issues) :)
+> Yargs is the official successor to optimist. Please feel free to submit issues and pull requests. If you'd like to contribute and don't know where to start, have a look at [the issue list](https://github.com/chevex/yargs/issues) :)
 
 examples
 ========
 
-With yargs, the options be just a hash! No optstrings be attached.
+With yargs, the options be just a hash!
 -------------------------------------------------------------------
 
 xup.js:
@@ -37,15 +36,15 @@ else {
 
     $ ./xup.js --rif=55 --xup=9.52
     Plunder more riffiwobbles!
-    
+
     $ ./xup.js --rif 12 --xup 8.1
     Drop the xupptumblers!
 
 ![Joe was one optimistic pirate.](http://i.imgur.com/4WFGVJ9.png)
 
-But don' walk the plank jus' yet! Ther' be more! Ye can do short options:
+But don't walk the plank just yet! There be more! You can do short options:
 -------------------------------------------------
- 
+
 short.js:
 
 ````javascript
@@ -59,7 +58,7 @@ console.log('(%d,%d)', argv.x, argv.y);
     $ ./short.js -x 10 -y 21
     (10,21)
 
-And gold doubooleans, both long an' short (an' grouped!):
+And booleans, both long, short, and even grouped:
 ----------------------------------
 
 bool.js:
@@ -81,7 +80,7 @@ console.log(
 
     $ ./bool.js -s
     The parrot says: squawk
-    
+
     $ ./bool.js -sp
     The parrot says: squawk!
 
@@ -90,7 +89,7 @@ console.log(
 
 And non-hyphenated options too! Just use `argv._`!
 -------------------------------------------------
- 
+
 nonopt.js:
 
 ````javascript
@@ -105,12 +104,12 @@ console.log(argv._);
     $ ./nonopt.js -x 6.82 -y 3.35 rum
     (6.82,3.35)
     [ 'rum' ]
-    
+
     $ ./nonopt.js "me hearties" -x 0.54 yo -y 1.12 ho
     (0.54,1.12)
     [ 'me hearties', 'yo', 'ho' ]
 
-Yargs even counts yer gold doubooleans!
+Yargs even counts your booleans!
 ----------------------------------------------------------------------
 
 count.js
@@ -151,7 +150,7 @@ DEBUG("Extra chatty mode");
     Showing semi-important stuff too
     Extra chatty mode
 
-Tell yer friends how ter use yer options and make demands from yer enemies.
+Tell users how to use yer options and make demands.
 -------------------------------------------------
 
 divide.js:
@@ -167,10 +166,10 @@ console.log(argv.x / argv.y);
 ````
 
 ***
- 
+
     $ ./divide.js -x 55 -y 11
     5
-    
+
     $ node ./divide.js -x 4.91 -z 2.51
     Usage: node ./divide.js -x [num] -y [num]
 
@@ -238,7 +237,7 @@ console.log(argv.x + argv.y);
     $ ./default_hash.js -y 7
     17
 
-And if ye really want ter get all descriptive about it...
+And if you really want to get all descriptive about it...
 ---------------------------------------------------------
 
 boolean_single.js
@@ -258,7 +257,7 @@ console.dir(argv._);
     $ ./boolean_single.js -v "me hearties" yo ho
     true
     [ 'me hearties', 'yo', 'ho' ]
-    
+
 
 boolean_double.js
 
@@ -278,7 +277,7 @@ console.dir(argv._);
     [ true, false, true ]
     [ 'one', 'two', 'three' ]
 
-Yargs is here ter help ye...
+Yargs is here to help you...
 ---------------------------
 
 Ye can describe parameters fer help messages and set aliases. Yargs figures
@@ -324,10 +323,10 @@ s.on('end', function () {
 
     Missing required arguments: f
 
-    $ node line_count.js --file line_count.js 
+    $ node line_count.js --file line_count.js
     20
-    
-    $ node line_count.js -f line_count.js 
+
+    $ node line_count.js -f line_count.js
     20
 
 methods
@@ -403,6 +402,13 @@ usage information and exit.
 The default behaviour is to set the value of any key not followed by an
 option value to `true`.
 
+.implies(x, y)
+--------------
+
+Given the key `x` is set, it is required that the key `y` is set.
+
+implies can also accept an object specifying multiple implications.
+
 .describe(key, desc)
 --------------------
 
@@ -410,19 +416,24 @@ Describe a `key` for the generated usage information.
 
 Optionally `.describe()` can take an object that maps keys to descriptions.
 
+.option(key, opt)
+-----------------
 .options(key, opt)
 ------------------
 
-Instead of chaining together `.alias().demand().default()`, you can specify
+Instead of chaining together `.alias().demand().default().describe().string()`, you can specify
 keys in `opt` for each of the chainable methods.
 
 For example:
 
 ````javascript
 var argv = require('yargs')
-    .options('f', {
+    .option('f', {
         alias : 'file',
-        default : '/etc/passwd',
+        demand: true,
+        default: '/etc/passwd',
+        describe: 'x marks the spot',
+        type: 'string'
     })
     .argv
 ;
@@ -440,6 +451,21 @@ var argv = require('yargs')
 
 Optionally `.options()` can take an object that maps keys to `opt` parameters.
 
+````javascript
+var argv = require('yargs')
+    .options({
+      'f': {
+        alias: 'file',
+        demand: true,
+        default: '/etc/passwd',
+        describe: 'x marks the spot',
+        type: 'string'
+      }
+    })
+    .argv
+;
+````
+
 .usage(message, opts)
 ---------------------
 
@@ -467,14 +493,21 @@ Check that certain conditions are met in the provided arguments.
 If `fn` throws or returns `false`, show the thrown error, usage information, and
 exit.
 
+.fail(fn)
+---------
+
+Method to execute when a failure occurs, rather then printing the failure message.
+
+`fn` is called with the failure message that would have been printed.
+
 .boolean(key)
 -------------
 
 Interpret `key` as a boolean. If a non-flag option follows `key` in
 `process.argv`, that string won't get set as the value of `key`.
 
-If `key` never shows up as a flag in `process.arguments`, `argv[key]` will be
-`false`.
+`key` will default to `false`, unless an `default(key, undefined)` is
+explicitly set.
 
 If `key` is an Array, interpret all the elements as booleans.
 
@@ -486,6 +519,9 @@ This can be useful if you need to preserve leading zeros in an input.
 
 If `key` is an Array, interpret all the elements as strings.
 
+`.string('_')` will result in non-hyphenated arguments being interpreted as strings,
+regardless of whether they resemble numbers.
+
 .config(key)
 ------------
 
@@ -574,6 +610,11 @@ yargs.showHelp();
 
 Later on, ```argv``` can be retrived with ```yargs.argv```
 
+.exitProcess(enable)
+----------------------------------
+
+By default, yargs exits the process when the user passes a help flag, uses the `.version` functionality or when validation fails. Calling `.exitProcess(false)` disables this behavior, enabling further actions after yargs have been validated.
+
 .parse(args)
 ------------
 
@@ -664,17 +705,17 @@ installation
 With [npm](http://github.com/isaacs/npm), just do:
 
     npm install yargs
- 
+
 or clone this project on github:
 
     git clone http://github.com/chevex/yargs.git
 
 To run the tests with [expresso](http://github.com/visionmedia/expresso),
 just do:
-    
+
     expresso
 
-inspired By
+inspired by
 ===========
 
 This module is loosely inspired by Perl's

package/index.js

@@ -1,6 +1,6 @@
 var path = require('path');
-var minimist = require('./lib/minimist');
-var wordwrap = require('./lib/wordwrap');
+var parser = require('./lib/parser');
+var wordwrap = require('wordwrap');
 
 /*  Hack an instance of Argv with process.argv into Argv
     so people can do
@@ -21,7 +21,7 @@ var exports = module.exports = Argv;
 function Argv (processArgs, cwd) {
     var self = {};
     if (!cwd) cwd = process.cwd();
-    
+
     self.$0 = process.argv
         .slice(0,2)
         .map(function (x) {
@@ -31,7 +31,7 @@ function Argv (processArgs, cwd) {
         })
         .join(' ')
     ;
-    
+
     if (process.env._ != undefined && process.argv[1] == process.env._) {
         self.$0 = process.env._.replace(
             path.dirname(process.execPath) + '/', ''
@@ -44,7 +44,7 @@ function Argv (processArgs, cwd) {
             boolean: [],
             string: [],
             alias: {},
-            default: [],
+            default: {},
             requiresArg: [],
             count: [],
             normalize: [],
@@ -53,7 +53,7 @@ function Argv (processArgs, cwd) {
         return self;
     };
     self.resetOptions();
-    
+
     self.boolean = function (bools) {
         options.boolean.push.apply(options.boolean, [].concat(bools));
         return self;
@@ -74,12 +74,12 @@ function Argv (processArgs, cwd) {
         examples.push([cmd, description]);
         return self;
     };
-    
+
     self.string = function (strings) {
         options.string.push.apply(options.string, [].concat(strings));
         return self;
     };
-    
+
     self.default = function (key, value) {
         if (typeof key === 'object') {
             Object.keys(key).forEach(function (k) {
@@ -91,7 +91,7 @@ function Argv (processArgs, cwd) {
         }
         return self;
     };
-    
+
     self.alias = function (x, y) {
         if (typeof x === 'object') {
             Object.keys(x).forEach(function (key) {
@@ -108,7 +108,7 @@ function Argv (processArgs, cwd) {
         options.count.push.apply(options.count, [].concat(counts));
         return self;
     };
-    
+
     var demanded = {};
     self.demand = self.required = self.require = function (keys, msg) {
         if (typeof keys == 'number') {
@@ -129,7 +129,7 @@ function Argv (processArgs, cwd) {
                 demanded[keys] = { msg: null };
             }
         }
-        
+
         return self;
     };
 
@@ -156,11 +156,11 @@ function Argv (processArgs, cwd) {
             opts = msg;
             msg = null;
         }
-        
+
         usage = msg;
-        
+
         if (opts) self.options(opts);
-        
+
         return self;
     };
 
@@ -186,10 +186,14 @@ function Argv (processArgs, cwd) {
                 }
                 console.error(failMessage);
             }
-            process.exit(1);
+            if (exitProcess){
+                process.exit(1);
+            }else{
+                throw new Error(msg);
+            }
         }
     }
-    
+
     var checks = [];
     self.check = function (f) {
         checks.push(f);
@@ -210,11 +214,11 @@ function Argv (processArgs, cwd) {
         }
         return self;
     };
-    
+
     self.parse = function (args) {
         return parseArgs(args);
     };
-    
+
     self.option = self.options = function (key, opt) {
         if (typeof key === 'object') {
             Object.keys(key).forEach(function (k) {
@@ -229,10 +233,10 @@ function Argv (processArgs, cwd) {
                 self.demand(key, demand);
             }
 
-            if (typeof opt.default !== 'undefined') {
+            if ('default' in opt) {
                 self.default(key, opt.default);
             }
-            
+
             if (opt.boolean || opt.type === 'boolean') {
                 self.boolean(key);
                 if (opt.alias) self.boolean(opt.alias);
@@ -269,7 +273,7 @@ function Argv (processArgs, cwd) {
         strict = true;
         return self;
     };
-    
+
     self.showHelp = function (fn) {
         if (!fn) fn = console.error.bind(console);
         fn(self.help());
@@ -296,8 +300,8 @@ function Argv (processArgs, cwd) {
     var showHelpOnFail = true;
     self.showHelpOnFail = function (enabled, message) {
         if (typeof enabled === 'string') {
-            enabled = true;
             message = enabled;
+            enabled = true;
         }
         else if (typeof enabled === 'undefined') {
             enabled = true;
@@ -307,8 +311,18 @@ function Argv (processArgs, cwd) {
         return self;
     };
 
+    var exitProcess = true;
+    self.exitProcess = function (enabled) {
+        if (typeof enabled !== 'boolean') {
+            enabled = true;
+        }
+        exitProcess = enabled;
+        return self;
+    };
 
     self.help = function () {
+        if (!self.parsed) parseArgs(processArgs); // run parser, if it has not already been executed.
+
         if (arguments.length > 0) {
             return self.addHelpOpt.apply(self, arguments);
         }
@@ -322,7 +336,7 @@ function Argv (processArgs, cwd) {
                 return acc;
             }, {})
         );
-        
+
         var help = keys.length ? [ 'Options:' ] : [];
 
         if (examples.length) {
@@ -351,9 +365,12 @@ function Argv (processArgs, cwd) {
             help.unshift(usage.replace(/\$0/g, self.$0), '');
         }
 
+        var aliasKeys = (Object.keys(options.alias) || [])
+            .concat(Object.keys(self.parsed.newAliases) || []);
+
         keys = keys.filter(function(key) {
-            return Object.keys(options.alias).every(function(alias) {
-                return -1 == options.alias[alias].indexOf(key);
+            return !self.parsed.newAliases[key] && aliasKeys.every(function(alias) {
+                return -1 == (options.alias[alias] || []).indexOf(key);
             });
         });
         var switches = keys.reduce(function (acc, key) {
@@ -369,40 +386,40 @@ function Argv (processArgs, cwd) {
         var switchlen = longest(Object.keys(switches).map(function (s) {
             return switches[s] || '';
         }));
-        
-        var desclen = longest(Object.keys(descriptions).map(function (d) { 
+
+        var desclen = longest(Object.keys(descriptions).map(function (d) {
             return descriptions[d] || '';
         }));
-        
+
         keys.forEach(function (key) {
             var kswitch = switches[key];
             var desc = descriptions[key] || '';
-            
+
             if (wrap) {
                 desc = wordwrap(switchlen + 4, wrap)(desc)
                     .slice(switchlen + 4)
                 ;
             }
-            
+
             var spadding = new Array(
                 Math.max(switchlen - kswitch.length + 3, 0)
             ).join(' ');
-            
+
             var dpadding = new Array(
                 Math.max(desclen - desc.length + 1, 0)
             ).join(' ');
-            
+
             var type = null;
-            
+
             if (options.boolean[key]) type = '[boolean]';
             if (options.count[key]) type = '[count]';
             if (options.string[key]) type = '[string]';
             if (options.normalize[key]) type = '[string]';
-            
+
             if (!wrap && dpadding.length > 0) {
                 desc += dpadding;
             }
-            
+
             var prelude = '  ' + kswitch + spadding;
             var extra = [
                 type,
@@ -415,50 +432,70 @@ function Argv (processArgs, cwd) {
                     JSON.stringify : String)(options.default[key]) + ']'
                     : null
             ].filter(Boolean).join('  ');
-            
+
             var body = [ desc, extra ].filter(Boolean).join('  ');
-            
+
             if (wrap) {
                 var dlines = desc.split('\n');
                 var dlen = dlines.slice(-1)[0].length
                     + (dlines.length === 1 ? prelude.length : 0)
-                
-                body = desc + (dlen + extra.length > wrap - 2
-                    ? '\n'
-                        + new Array(wrap - extra.length + 1).join(' ')
-                        + extra
-                    : new Array(wrap - extra.length - dlen + 1).join(' ')
-                        + extra
-                );
+
+                if (extra.length > wrap) {
+                    body = desc + '\n' + wordwrap(switchlen + 4, wrap)(extra)
+                } else {
+                    body = desc + (dlen + extra.length > wrap - 2
+                        ? '\n'
+                            + new Array(wrap - extra.length + 1).join(' ')
+                            + extra
+                        : new Array(wrap - extra.length - dlen + 1).join(' ')
+                            + extra
+                    );
+                }
             }
-            
+
             help.push(prelude + body);
         });
-        
+
         if (keys.length) help.push('');
         return help.join('\n');
     };
-    
+
     Object.defineProperty(self, 'argv', {
-        get : function () { return parseArgs(processArgs) },
+        get : function () {
+          var args = null;
+
+          try {
+            args = parseArgs(processArgs);
+          } catch (err) {
+            fail(err.message);
+          }
+
+          return args;
+        },
         enumerable : true
     });
-    
+
     function parseArgs (args) {
-        var parsed = minimist(args, options),
+        var parsed = parser(args, options),
             argv = parsed.argv,
             aliases = parsed.aliases;
 
         argv.$0 = self.$0;
 
+        self.parsed = parsed;
+
         Object.keys(argv).forEach(function(key) {
             if (key === helpOpt) {
                 self.showHelp(console.log);
-                process.exit(0);
+                if (exitProcess){
+                    process.exit(0);
+                }
             }
             else if (key === versionOpt) {
-                console.log(version);
-                process.exit(0);
+                process.stdout.write(version);
+                if (exitProcess){
+                    process.exit(0);
+                }
             }
         });
 
@@ -478,7 +515,7 @@ function Argv (processArgs, cwd) {
             options.requiresArg.forEach(function(key) {
                 var value = argv[key];
 
-                // minimist sets --foo value to true / --no-foo to false
+                // parser sets --foo value to true / --no-foo to false
                 if (value === true || value === false) {
                     missingRequiredArgs.push(key);
                 }
@@ -488,11 +525,11 @@ function Argv (processArgs, cwd) {
                 fail("Missing argument value: " + missingRequiredArgs[0]);
             }
             else if (missingRequiredArgs.length > 1) {
-                message = "Missing argument values: " + missingRequiredArgs.join(", ");
+                var message = "Missing argument values: " + missingRequiredArgs.join(", ");
                 fail(message);
             }
         }
-        
+
         var missing = null;
         Object.keys(demanded).forEach(function (key) {
             if (!argv.hasOwnProperty(key)) {
@@ -500,7 +537,7 @@ function Argv (processArgs, cwd) {
                 missing[key] = demanded[key];
             }
         });
-        
+
         if (missing) {
             var customMsgs = [];
             Object.keys(missing).forEach(function(key) {
@@ -602,17 +639,17 @@ function Argv (processArgs, cwd) {
 
             fail(msg);
         }
-        
+
         return argv;
     }
-    
+
     function longest (xs) {
         return Math.max.apply(
             null,
             xs.map(function (x) { return x.length })
         );
     }
-    
+
     return self;
 };
 
@@ -620,14 +657,5 @@ function Argv (processArgs, cwd) {
 // exported for tests
 exports.rebase = rebase;
 function rebase (base, dir) {
-    var ds = path.normalize(dir).split('/').slice(1);
-    var bs = path.normalize(base).split('/').slice(1);
-    
-    for (var i = 0; ds[i] && ds[i] == bs[i]; i++);
-    ds.splice(0, i); bs.splice(0, i);
-    
-    var p = path.normalize(
-        bs.map(function () { return '..' }).concat(ds).join('/')
-    ).replace(/\/$/,'').replace(/^$/, '.');
-    return p.match(/^[.\/]/) ? p : './' + p;
+  return path.relative(base, dir);
 };