Skip to content

Commit

Permalink
feat: added option to specify example flag value in docopts (#1091)
Browse files Browse the repository at this point in the history
* feat: added option to specify example flag value in docopts

* feat: combined extra flag property with helpValue
  • Loading branch information
kemley76 authored Jun 4, 2024
1 parent 7eac5a4 commit 2cb180a
Show file tree
Hide file tree
Showing 5 changed files with 90 additions and 13 deletions.
11 changes: 5 additions & 6 deletions src/help/command.ts
Original file line number Diff line number Diff line change
Expand Up @@ -166,12 +166,11 @@ export class CommandHelp extends HelpFormatter {
}

if (flag.type === 'option') {
let value = flag.helpValue || (this.opts.showFlagNameInTitle ? flag.name : '<value>')
if (!flag.helpValue && flag.options) {
value = showOptions || this.opts.showFlagOptionsInTitle ? `${flag.options.join('|')}` : '<option>'
}

if (flag.multiple) value += '...'
let value = DocOpts.formatUsageType(
flag,
this.opts.showFlagNameInTitle ?? false,
this.opts.showFlagOptionsInTitle ?? showOptions,
)
if (!value.includes('|')) value = chalk.underline(value)
label += `=${value}`
}
Expand Down
24 changes: 22 additions & 2 deletions src/help/docopts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,26 @@ export class DocOpts {
})
}

public static formatUsageType(flag: Command.Flag.Any, showFlagName: boolean, showOptions: boolean): string {
if (flag.type !== 'option') return ''

let helpValues: string[]
if (flag.helpValue) {
// if there is a given helpValue, use it
helpValues = typeof flag.helpValue === 'string' ? [flag.helpValue] : flag.helpValue
} else if (flag.options) {
// if there are options, show them if wanted
helpValues = [showOptions ? flag.options.join('|') : '<option>']
} else if (showFlagName) {
helpValues = [flag.name]
} else {
// default to <value>
helpValues = ['<value>']
}

return helpValues.map((v) => `${v}${flag.multiple ? '...' : ''}`).join(' ')
}

public static generate(cmd: Command.Loadable): string {
return new DocOpts(cmd).toString()
}
Expand All @@ -96,7 +116,7 @@ export class DocOpts {
...this.flagList.map((flag) => {
const name = flag.char ? `-${flag.char}` : `--${flag.name}`
if (flag.type === 'boolean') return name
return `${name}=<value>`
return `${name}=${DocOpts.formatUsageType(flag, false, true)}`
}),
)
}
Expand Down Expand Up @@ -142,7 +162,7 @@ export class DocOpts {
// not all flags have short names
const flagName = flag.char ? `-${flag.char}` : `--${flag.name}`
if (flag.type === 'option') {
type = flag.options ? ` ${flag.options.join('|')}` : ' <value>'
type = ` ${DocOpts.formatUsageType(flag, false, true)}`
}

const element = `${flagName}${type}`
Expand Down
10 changes: 5 additions & 5 deletions src/interfaces/parser.ts
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ export type BooleanFlagProps = FlagProps & {

export type OptionFlagProps = FlagProps & {
type: 'option'
helpValue?: string
helpValue?: string | string[]
options?: readonly string[]
multiple?: boolean
/**
Expand Down Expand Up @@ -295,10 +295,10 @@ type FlagReturnType<T, R extends ReturnTypeSwitches> = R['requiredOrDefaulted']
: T[]
: T
: R['multiple'] extends true
? [T] extends [Array<unknown>]
? T | undefined
: T[] | undefined
: T | undefined
? [T] extends [Array<unknown>]
? T | undefined
: T[] | undefined
: T | undefined

/**
* FlagDefinition types a function that takes `options` and returns an OptionFlag<T>.
Expand Down
37 changes: 37 additions & 0 deletions test/help/docopts.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -265,4 +265,41 @@ describe('doc opts', () => {
} as any)
expect(usage).to.contain(' (-s <value> -f <value>)')
})

it('is uses helpValues as expected', () => {
const usage = DocOpts.generate({
flags: {
testFlag: Flags.url({
name: 'testFlag',
description: 'test',
char: 's',
required: true,
helpValue: ['<test1>', '<test2>'],
multiple: true,
}),
testFlag2: Flags.string({
name: 'testFlag2',
description: 'test',
char: 'f',
required: true,
helpValue: '<test3>',
}),
testFlag3: Flags.string({
name: 'testFlag3',
description: 'test',
char: 'g',
required: true,
multiple: true,
}),
testFlag4: Flags.string({
name: 'testFlag4',
description: 'test',
char: 'p',
required: true,
options: ['option1', 'option2'],
}),
},
} as any)
expect(usage).to.contain('-s <test1>... <test2>... -f <test3> -g <value>... -p option1|option2')
})
})
21 changes: 21 additions & 0 deletions test/help/format-command.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,27 @@ FLAGS
--myenum=a|b|c`)
})

it('should output helpValue in usage string', async () => {
const cmd = await makeLoadable(
makeCommandClass({
id: 'apps:create',
flags: {
files: flags.string({
helpValue: ['<input-json>', '<input-xml>'],
multiple: true,
}),
},
}),
)

const output = help.formatCommand(cmd)
expect(output).to.equal(`USAGE
$ oclif apps:create [--files <input-json>... <input-xml>...]
FLAGS
--files=<input-json>... <input-xml>...`)
})

it('should output with default flag options', async () => {
const cmd = await makeLoadable(
makeCommandClass({
Expand Down

0 comments on commit 2cb180a

Please sign in to comment.