Skip to content

Commit ea862ae

Browse files
laggingreflexbcoe
laggingreflex
authored and
bcoe
committed
feat: allow hidden options to be displayed with --show-hidden (#1061)
1 parent fb62d88 commit ea862ae

5 files changed

Lines changed: 187 additions & 13 deletions

File tree

‎docs/api.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -576,6 +576,11 @@ Describe a `key` for the generated usage information.
576576

577577
Optionally `.describe()` can take an object that maps keys to descriptions.
578578

579+
<a name="hide"></a>.hide(key)
580+
--------------------
581+
582+
Hides a `key` from the generated usage information. Unless a `--show-hidden` option is also passed with `--help` (see [`showHidden()`](#showHidden)).
583+
579584
.detectLocale(boolean)
580585
-----------
581586

@@ -798,6 +803,29 @@ var yargs = require("yargs")(['--info'])
798803
.argv
799804
```
800805

806+
<a name="showHidden"></a>.showHidden()
807+
-----------------------------------------
808+
.showHidden([option | boolean])
809+
-----------------------------------------
810+
.showHidden([option, [description]])
811+
-----------------------------------------
812+
813+
Configure the `--show-hidden` option that displays the hidden keys (see [`hide()`](#hide)).
814+
815+
If the first argument is a boolean, it enables/disables this option altogether. I.e. hidden keys will be permanently hidden if first argument is `false`.
816+
817+
If the first argument is a string it changes the key name ("--show-hidden").
818+
819+
Second argument changes the default description ("Show hidden options")
820+
821+
Example:
822+
823+
```js
824+
var yargs = require("yargs")(['--help'])
825+
.showHidden('show-hidden', 'Show hidden options')
826+
.argv
827+
```
828+
801829
<a name="implies"></a>.implies(x, y)
802830
--------------
803831

‎lib/usage.js‎

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -152,16 +152,23 @@ module.exports = function usage (yargs, y18n) {
152152
const demandedCommands = yargs.getDemandedCommands()
153153
const groups = yargs.getGroups()
154154
const options = yargs.getOptions()
155-
let keys = Object.keys(
156-
Object.keys(descriptions)
157-
.concat(Object.keys(demandedOptions))
158-
.concat(Object.keys(demandedCommands))
159-
.concat(Object.keys(options.default))
160-
.reduce((acc, key) => {
161-
if (key !== '_') acc[key] = true
162-
return acc
163-
}, {})
164-
)
155+
156+
let keys = []
157+
keys = keys.concat(Object.keys(descriptions))
158+
keys = keys.concat(Object.keys(demandedOptions))
159+
keys = keys.concat(Object.keys(demandedCommands))
160+
keys = keys.concat(Object.keys(options.default))
161+
keys = keys.filter(key => {
162+
if (options.hiddenOptions.indexOf(key) < 0) {
163+
return true
164+
} else if (yargs.parsed.argv[options.showHiddenOpt]) {
165+
return true
166+
}
167+
})
168+
keys = Object.keys(keys.reduce((acc, key) => {
169+
if (key !== '_') acc[key] = true
170+
return acc
171+
}, {}))
165172

166173
const theWrap = getWrap()
167174
const ui = require('cliui')({

‎test/usage.js‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2887,5 +2887,83 @@ describe('usage tests', () => {
28872887
''
28882888
])
28892889
})
2890+
it('--help should display all options (including hidden ones) with --show-hidden', () => {
2891+
const r = checkUsage(() => yargs('--help --show-hidden --mama ama')
2892+
.options({
2893+
foo: {
2894+
describe: 'FOO'
2895+
},
2896+
bar: {},
2897+
baz: {
2898+
describe: 'BAZ',
2899+
hidden: true
2900+
}
2901+
})
2902+
.argv
2903+
)
2904+
2905+
r.logs[0].split('\n').should.deep.equal([
2906+
'Options:',
2907+
' --help Show help [boolean]',
2908+
' --version Show version number [boolean]',
2909+
' --foo FOO',
2910+
' --bar',
2911+
' --baz BAZ',
2912+
''
2913+
])
2914+
})
2915+
it('--help should display --custom-show-hidden', () => {
2916+
const r = checkUsage(() => yargs('--help')
2917+
.options({
2918+
foo: {
2919+
describe: 'FOO'
2920+
},
2921+
bar: {},
2922+
baz: {
2923+
describe: 'BAZ',
2924+
hidden: true
2925+
}
2926+
})
2927+
.showHidden('custom-show-hidden')
2928+
.argv
2929+
)
2930+
2931+
r.logs[0].split('\n').should.deep.equal([
2932+
'Options:',
2933+
' --help Show help [boolean]',
2934+
' --version Show version number [boolean]',
2935+
' --foo FOO',
2936+
' --bar',
2937+
' --custom-show-hidden Show hidden options [boolean]',
2938+
''
2939+
])
2940+
})
2941+
it('--help should display all options with --custom-show-hidden', () => {
2942+
const r = checkUsage(() => yargs('--help --custom-show-hidden')
2943+
.options({
2944+
foo: {
2945+
describe: 'FOO'
2946+
},
2947+
bar: {},
2948+
baz: {
2949+
describe: 'BAZ',
2950+
hidden: true
2951+
}
2952+
})
2953+
.showHidden('custom-show-hidden')
2954+
.argv
2955+
)
2956+
2957+
r.logs[0].split('\n').should.deep.equal([
2958+
'Options:',
2959+
' --help Show help [boolean]',
2960+
' --version Show version number [boolean]',
2961+
' --foo FOO',
2962+
' --bar',
2963+
' --baz BAZ',
2964+
' --custom-show-hidden Show hidden options [boolean]',
2965+
''
2966+
])
2967+
})
28902968
})
28912969
})

‎test/yargs.js‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,42 @@ describe('yargs dsl tests', () => {
129129
expect(r.errors).to.deep.equal([])
130130
})
131131

132+
describe('hide', () => {
133+
it('should add the key to hiddenOptions', () => {
134+
const options = yargs('')
135+
.hide('someKey')
136+
.getOptions()
137+
options.should.have.property('hiddenOptions')
138+
options.hiddenOptions.should.include('someKey')
139+
})
140+
})
141+
142+
describe('showHidden', () => {
143+
it('should have a default show-hidden private option pre-configured', () => {
144+
const options = yargs('').getOptions()
145+
options.should.have.property('showHiddenOpt')
146+
options.showHiddenOpt.should.eql('show-hidden')
147+
})
148+
it('should not have show-hidden as an actual option described by default', () => {
149+
const options = yargs('').getOptions()
150+
options.key.should.not.have.property('show-hidden')
151+
})
152+
it('should set show-hidden option', () => {
153+
const options = yargs('')
154+
.showHidden()
155+
.getOptions()
156+
options.key.should.have.property('show-hidden')
157+
})
158+
it('should set custom-show-hidden option', () => {
159+
const options = yargs('')
160+
.showHidden('custom-show-hidden')
161+
.getOptions()
162+
options.key.should.have.property('custom-show-hidden')
163+
options.should.have.property('showHiddenOpt')
164+
options.showHiddenOpt.should.eql('custom-show-hidden')
165+
})
166+
})
167+
132168
describe('showHelpOnFail', () => {
133169
it('should display custom failure message, if string is provided as first argument', () => {
134170
const r = checkOutput(() => yargs([])
@@ -233,6 +269,7 @@ describe('yargs dsl tests', () => {
233269
config: {},
234270
configObjects: [],
235271
envPrefix: 'YARGS', // preserved as global
272+
hiddenOptions: [],
236273
demandedCommands: {},
237274
demandedOptions: {},
238275
local: [

‎yargs.js‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,8 @@ function Yargs (processArgs, cwd, parentRequire) {
9393

9494
const arrayOptions = [
9595
'array', 'boolean', 'string', 'skipValidation',
96-
'count', 'normalize', 'number'
96+
'count', 'normalize', 'number',
97+
'hiddenOptions'
9798
]
9899

99100
const objectOptions = [
@@ -657,8 +658,9 @@ function Yargs (processArgs, cwd, parentRequire) {
657658
}
658659

659660
const desc = opt.describe || opt.description || opt.desc
660-
if (!opt.hidden) {
661-
self.describe(key, desc)
661+
self.describe(key, desc)
662+
if (opt.hidden) {
663+
self.hide(key)
662664
}
663665

664666
if (opt.requiresArg) {
@@ -824,6 +826,28 @@ function Yargs (processArgs, cwd, parentRequire) {
824826
return self
825827
}
826828

829+
const defaultShowHiddenOpt = 'show-hidden'
830+
options.showHiddenOpt = defaultShowHiddenOpt
831+
self.addShowHiddenOpt = self.showHidden = function addShowHiddenOpt (opt, msg) {
832+
argsert('[string|boolean] [string]', [opt, msg], arguments.length)
833+
834+
if (arguments.length === 1) {
835+
if (opt === false) return self
836+
}
837+
838+
const showHiddenOpt = typeof opt === 'string' ? opt : defaultShowHiddenOpt
839+
self.boolean(showHiddenOpt)
840+
self.describe(showHiddenOpt, msg || usage.deferY18nLookup('Show hidden options'))
841+
options.showHiddenOpt = showHiddenOpt
842+
return self
843+
}
844+
845+
self.hide = function hide (key) {
846+
argsert('<string|object>', [key], arguments.length)
847+
options.hiddenOptions.push(key)
848+
return self
849+
}
850+
827851
self.showHelpOnFail = function showHelpOnFail (enabled, message) {
828852
argsert('[boolean|string] [string]', [enabled, message], arguments.length)
829853
usage.showHelpOnFail(enabled, message)

0 commit comments

Comments
 (0)