yargs - npm Package Compare versions

Comparing version 1.2.6 to 1.3.0

index.js

@@ -174,4 +174,12 @@ var path = require('path');
         } else {
-            self.showHelp();
+            if (showHelpOnFail) {
+                self.showHelp();
+            }
             if (msg) console.error(msg);
+            if (failMessage) {
+                if (msg) {
+                    console.error("");
+                }
+                console.error(failMessage);
+            }
             process.exit(1);
@@ -230,3 +238,3 @@ }
             }
-            
+
             var desc = opt.describe || opt.description || opt.desc;
@@ -241,6 +249,6 @@ if (desc) {
         }
-        
+
         return self;
     };
-    
+
     var wrap = null;
@@ -263,4 +271,40 @@ self.wrap = function (cols) {
     };
-    
+
+    var version = null;
+    var versionOpt = null;
+    self.version = function (ver, opt, msg) {
+        version = ver;
+        versionOpt = opt;
+        self.describe(opt, msg || 'Show version number');
+        return self;
+    };
+
+    var helpOpt = null;
+    self.addHelpOpt = function (opt, msg) {
+        helpOpt = opt;
+        self.describe(opt, msg || 'Show help');
+        return self;
+    };
+
+    var failMessage = null;
+    var showHelpOnFail = true;
+    self.showHelpOnFail = function (enabled, message) {
+        if (typeof enabled === 'string') {
+            enabled = true;
+            message = enabled;
+        }
+        else if (typeof enabled === 'undefined') {
+            enabled = true;
+        }
+        failMessage = message;
+        showHelpOnFail = enabled;
+        return self;
+    };
+
+
     self.help = function () {
+        if (arguments.length > 0) {
+            return self.addHelpOpt.apply(self, arguments);
+        }
+
         var keys = Object.keys(
@@ -404,2 +448,13 @@ Object.keys(descriptions)
 
+        Object.keys(argv).forEach(function(key) {
+            if (key === helpOpt) {
+                self.showHelp(console.log);
+                process.exit(0);
+            }
+            else if (key === versionOpt) {
+                console.log(version);
+                process.exit(0);
+            }
+        });
+
         if (demanded._ && argv._.length < demanded._.count) {
@@ -462,4 +517,4 @@ if (demanded._.msg) {
 
-            Object.keys(options.alias).forEach(function (key) {
-                options.alias[key].forEach(function (alias) {
+            Object.keys(parsed.aliases).forEach(function (key) {
+                parsed.aliases[key].forEach(function (alias) {
                     aliases[alias] = key;
@@ -466,0 +521,0 @@ });

package.json

 {
   "name": "yargs",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "Light-weight option parsing with an argv hash. No optstrings attached.",
   "main": "./index.js",
   "dependencies": {
-    "minimist": "^0.1.0"
+    "minimist": "^0.2.0"
   },
@@ -9,0 +9,0 @@ "devDependencies": {

README.md

@@ -14,3 +14,3 @@ yargs
 
-> 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 pour 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) :)
+> 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) :)
 
@@ -500,7 +500,11 @@ examples
 
-.help()
--------
+.help([option, [description]])
+------------------------------
 
-Return the generated usage string.
+Add an option (e.g., `--help`) that displays the usage string and exits the
+process. If present, the `description` parameter customises the description of
+the help option in the usage string.
 
+If invoked without parameters, `.help` returns the generated usage string.
+
 Example:
@@ -516,2 +520,39 @@
 
+.version(version, option, [description])
+----------------------------------------
+
+Add an option (e.g., `--version`) that displays the version number (given by the
+`version` parameter) and exits the process. If present, the `description`
+parameter customises the description of the version option in the usage string.
+
+.showHelpOnFail(enable, [message])
+----------------------------------
+
+By default, yargs outputs a usage string if any error is detected. Use the
+`.showHelpOnFail` method to customize this behaviour. if `enable` is `false`,
+the usage string is not output. If the `message` parameter is present, this
+message is output after the error message.
+
+line_count.js
+
+````javascript
+#!/usr/bin/env node
+var argv = require('yargs')
+    .usage('Count the lines in a file.\nUsage: $0')
+    .demand('f')
+    .alias('f', 'file')
+    .describe('f', 'Load a file')
+    .showHelpOnFail(false, "Specify --help for available options")
+    .argv;
+
+// etc.
+````
+
+***
+
+    $ node line_count.js --file
+    Missing argument value: f
+
+    Specify --help for available options
+
 .showHelp(fn=console.error)
@@ -518,0 +559,0 @@ ---------------------------

test/parse_camelCase.js

@@ -6,10 +6,14 @@ var should = require('chai').should(),
 
-    describe('dashes and camelCase', function () {
+    function runTests (yargs, strict) {
 
-        it('should provide options with dashes as camelCase properties', function () {
-            var result = yargs()
-                .parse([ '--some-option' ]);
+        if (!strict) {
+            // Skip this test in strict mode because this option is not specified
+            it('should provide options with dashes as camelCase properties', function () {
+                var result = yargs()
+                    .parse([ '--some-option' ]);
 
-            result.should.have.property('someOption').that.is.a('boolean').and.is.true;
-        });
+                result.should.have.property('some-option').that.is.a('boolean').and.is.true;
+                result.should.have.property('someOption' ).that.is.a('boolean').and.is.true;
+            });
+        }
 
@@ -24,3 +28,4 @@ it('should provide count options with dashes as camelCase properties', function () {
 
-            result.should.have.property('someOption', 3);
+            result.should.have.property('some-option', 3);
+            result.should.have.property('someOption' , 3);
         });
@@ -36,3 +41,4 @@
 
-            result.should.have.property('someOption').that.is.a('boolean').and.is.true;
+            result.should.have.property('some-option').that.is.a('boolean').and.is.true;
+            result.should.have.property('someOption' ).that.is.a('boolean').and.is.true;
         });
@@ -48,3 +54,4 @@
 
-            result.should.have.property('someOption', 'asdf');
+            result.should.have.property('some-option', 'asdf');
+            result.should.have.property('someOption' , 'asdf');
         });
@@ -62,2 +69,4 @@
             result.should.have.property('o', 'asdf');
+            result.should.have.property('some-option', 'asdf');
+            result.should.have.property('someOption' , 'asdf');
         });
@@ -74,3 +83,5 @@
 
-            result.should.have.property('someOption', 'asdf');
+            result.should.have.property('o', 'asdf');
+            result.should.have.property('some-option', 'asdf');
+            result.should.have.property('someOption' , 'asdf');
         });
@@ -86,6 +97,40 @@
 
-            result.should.have.property('someOption').that.is.a('string').and.equals('val');
+            result.should.have.property('o'          ).that.is.a('string').and.equals('val');
+            result.should.have.property('some-option').that.is.a('string').and.equals('val');
+            result.should.have.property('someOption' ).that.is.a('string').and.equals('val');
         });
+
+    }
+
+    describe('dashes and camelCase', function () {
+        runTests(function() {
+            return yargs();
+        });
     });
 
+    describe('dashes and camelCase (strict)', function () {
+        runTests(function() {
+            // Special handling for failure messages, because normally a
+            // failure calls process.exit(1);
+            return yargs().strict().fail(function(msg) {
+                throw new Error(msg);
+            });
+        }, true);
+
+        // See https://github.com/chevex/yargs/issues/31
+
+        it('should not fail when options with defaults are missing', function () {
+            var result = yargs()
+                .fail(function(msg) {
+                    throw new Error(msg);
+                })
+                .option('some-option', {
+                    describe : 'some option',
+                    default  : 80
+                })
+                .strict()
+                .parse([ ]);
+        });
+    });
+
 });

test/usage.js

@@ -535,2 +535,70 @@ var should = require('chai').should(),
 
+    describe('help option', function () {
+        it('should display usage', function () {
+            var r = checkUsage(function () {
+                return yargs(['--help'])
+                    .demand(['y'])
+                    .help('help')
+                    .argv;
+            });
+            r.should.have.property('result');
+            r.result.should.have.property('_').with.length(0);
+            r.should.have.property('errors');
+            r.should.have.property('logs').with.length(1);
+            r.should.have.property('exit').and.be.ok;
+            r.logs.join('\n').split(/\n+/).should.deep.equal([
+                'Options:',
+                '  --help  Show help',
+                '  -y                 [required]',
+                ''
+            ]);
+        });
+    });
+
+    describe('version option', function () {
+        it('should display version', function () {
+            var r = checkUsage(function () {
+                return yargs(['--version'])
+                    .version('1.0.1', 'version', 'Show version number')
+                    .argv;
+            });
+            r.should.have.property('result');
+            r.result.should.have.property('_').with.length(0);
+            r.should.have.property('errors');
+            r.should.have.property('logs').with.length(1);
+            r.should.have.property('exit').and.be.ok;
+            r.logs.join('\n').split(/\n+/).should.deep.equal([
+                '1.0.1'
+            ]);
+        });
+    });
+
+    describe('showHelpOnFail', function () {
+        it('should display user supplied message', function () {
+            var opts = {
+                foo: { desc: 'foo option', alias: 'f' },
+                bar: { desc: 'bar option', alias: 'b' }
+            };
+
+            var r = checkUsage(function () {
+                return yargs(['--foo'])
+                    .usage('Usage: $0 [options]')
+                    .options(opts)
+                    .demand(['foo', 'bar'])
+                    .showHelpOnFail(false, "Specify --help for available options")
+                    .argv;
+            });
+            r.should.have.property('result');
+            r.result.should.have.property('_').with.length(0);
+            r.should.have.property('errors');
+            r.should.have.property('logs').with.length(0);
+            r.should.have.property('exit').and.be.ok;
+            r.errors.join('\n').split(/\n/).should.deep.equal([
+                'Missing required arguments: bar',
+                '',
+                'Specify --help for available options'
+            ]);
+        });
+    });
+
     it('should succeed when rebase', function () {
@@ -537,0 +605,0 @@ yargs.rebase('/home/chevex', '/home/chevex/foo/bar/baz').should.equal('./foo/bar/baz');

No alert changes

Improved metrics

Total package byte prevSize

106958

increased by7.89%

Number of package files

42

increased by2.44%

Lines of code

2279

increased by8.42%

Number of lines in readme file

675

increased by6.47%

Dependency changes

• + Addedminimist@0.2.4(transitive)

• - Removedminimist@0.1.0(transitive)

• Updatedminimist@^0.2.0