feat: yargs is now passed as the third-argument to fail handler (yarg…

…s#613)

README.md

@@ -1150,15 +1150,17 @@ yargs have been validated.
 
 Method to execute when a failure occurs, rather than printing the failure message.
 
-`fn` is called with the failure message that would have been printed and the
-`Error` instance originally thrown, if any.
+`fn` is called with the failure message that would have been printed, the
+`Error` instance originally thrown and yargs state when the failure
+occured. 
 
 ```js
 var argv = require('yargs')
-  .fail(function (msg, err) {
+  .fail(function (msg, err, yargs) {
     if (err) throw err // preserve stack
     console.error('You broke it!')
     console.error(msg)
+    console.error('You should be doing', yargs.help())
     process.exit(1)
   })
   .argv

lib/usage.js

@@ -34,7 +34,7 @@ module.exports = function (yargs, y18n) {
 
     if (fails.length) {
       for (var i = fails.length - 1; i >= 0; --i) {
-        fails[i](msg, err)
+        fails[i](msg, err, self)
       }
     } else {
       if (yargs.getExitProcess()) setBlocking(true)

test/usage.js

@@ -473,6 +473,28 @@ describe('usage tests', function () {
         r.logs.should.deep.equal(['foo'])
         r.should.have.property('exit').and.be.false
       })
+
+      it('gives the ability to log a per-command error message if failure occurs in a command', function () {
+        var r = checkUsage(function () {
+          return yargs('foo')
+            .command('foo', 'desc', {
+              bar: {
+                describe: 'bar command'
+              }
+            }, function (argv) {
+              throw new Error('blah')
+            })
+            .fail(function (message, error, yargs) {
+              yargs.showHelp()
+            })
+            .exitProcess(false)
+            .wrap(null)
+            .argv
+        })
+
+        r.errors[0].should.contain('bar command')
+      })
+
       describe('when check() throws error', function () {
         it('fail() is called with the original error object as the second parameter', function () {
           var r = checkUsage(function () {