feat: Add .parserConfiguration() method, deprecating package.json config (#1262)

BREAKING CHANGE: we now warn if the yargs stanza package.json is used.

Author: jean-emmanuel

docs/api.md

@@ -1149,6 +1149,10 @@ If the arguments have been parsed, this contain detailed parsed arguments. See
 the documentation in [yargs-parser `.detailed()`][https://github.com/yargs/yargs-parser/blob/master/README.md#requireyargs-parserdetailedargs-opts]
 for details of this object
 
+<a name="parserConfiguration"></a>.parserConfiguration(obj)
+------------
+`parserConfiguration()` allows you to configure yargs-parser, see [yargs-parser's configuration](https://github.com/yargs/yargs-parser#configuration).
+
 <a name="pkg-conf"></a>
 .pkgConf(key, [cwd])
 ------------

test/fixtures/configured-bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+var argv = require('./yargs/index.js')
+  .parserConfiguration({'dot-notation': true})
+  .help('help')
+  .version()
+  .argv
+console.log(argv)

test/integration.js

@@ -191,6 +191,18 @@ describe('integration tests', () => {
             return done()
           })
         })
+
+        it('is overridden by yargs.parserConfiguration', (done) => {
+          testCmd('./configured-bin.js', [ '--foo.bar', '--no-baz' ], (code, stdout) => {
+            if (code) {
+              return done(new Error(`cmd exited with code ${code}`))
+            }
+
+            stdout.should.not.match(/foo\.bar/)
+            stdout.should.match(/noBaz/)
+            return done()
+          })
+        })
       })
 
       after(() => {

test/yargs.js

@@ -1612,6 +1612,16 @@ describe('yargs dsl tests', () => {
     })
   })
 
+  describe('parserConfiguration', () => {
+    it('overrides the default parser configuration ', () => {
+      const argv = yargs('--foo.bar 1 --no-baz 2')
+        .parserConfiguration({'boolean-negation': false, 'dot-notation': false})
+        .parse()
+      expect(argv['foo.bar']).to.equal(1)
+      argv.noBaz.should.equal(2)
+    })
+  })
+
   describe('skipValidation', () => {
     it('skips validation if an option with skipValidation is present', () => {
       const argv = yargs(['--koala', '--skip'])

yargs.js

@@ -765,6 +765,14 @@ function Yargs (processArgs, cwd, parentRequire) {
   }
   self.getStrict = () => strict
 
+  let parserConfig = {}
+  self.parserConfiguration = function parserConfiguration (config) {
+    argsert('<object>', [config], arguments.length)
+    parserConfig = config
+    return self
+  }
+  self.getParserConfiguration = () => parserConfig
+
   self.showHelp = function (level) {
     argsert('[string|function]', [level], arguments.length)
     if (!self.parsed) self._parseArgs(processArgs) // run parser, if it has not already been executed.
@@ -1010,7 +1018,14 @@ function Yargs (processArgs, cwd, parentRequire) {
     args = args || processArgs
 
     options.__ = y18n.__
-    options.configuration = pkgUp()['yargs'] || {}
+    options.configuration = self.getParserConfiguration()
+
+    // Deprecated
+    let pkgConfig = pkgUp()['yargs']
+    if (pkgConfig) {
+      console.warn('Configuring yargs through package.json is deprecated and will be removed in the next major release, please use the JS API instead.')
+      options.configuration = Object.assign({}, pkgConfig, options.configuration)
+    }
 
     const parsed = Parser.detailed(args, options)
     let argv = parsed.argv