Strict and fair parameter papa
npm install paparamStrict and fair parameter papa
```
npm install paparam
Use paparam to build a simple cli parser. Here is an example app invocation from the command line:
`bash`
> app -i uuid-284h43j -b peer1 -b peer2 --storage /tmp/file/place link-32832uifsdjsfda
To handle this invocation, here is the paparam code
`js`
import { header, summary, command, flag, arg } from 'paparam'
const cmd = command(
'run',
header('A simple example app'),
summary('Example app that uses a roomLink to join a room and do work.'),
arg('
flag('--uuid|-i [uuid]', 'The specific schema uuid to use'),
flag('--user|-u [user]', 'The user name associated with the entry'),
flag('--storage|-s [storage]', 'Path to storage directory'),
flag('--blind|-b [blind]', 'Blind peer keys (can be specified multiple times)').multiple()
)
const program = cmd.parse() // default args: process.argv.slice(2)
if (program === null) throw new Error('missing arg')
console.log('user', program.flags.user)
console.log('storagePath', program.flags.storage || '/tmp')
console.log('blindPeers', program.flags.blind || [])
console.log('roomLink', program.roomLink)
cmd.add(flag('--another', 'lazy added'))
cmd.add({
'--more': 'via description object',
'--modifiers': ['are defined with array [desc, opts]', { multiple: true }]
})
cmd.parse(['-h'])
Use paparam exports to compose commands together:
`js
const { header, footer, command, flag, arg, summary, description, rest } = require('./')
const run = command(
'run',
summary('Run an app from a link'),
description(
'Run an app from a file link (or path) or from a pear link.\nOptionally supply store for custom store path'
),
flag('--store|-s [path]', 'store path'),
arg('', 'link to run'),
rest('[...app-args]'),
() => console.log('ACTION ->', 'run', run.args.link, 'flags:', run.flags)
)
const cmd = command(
'pear',
summary('pear cli'),
{
// definition objects can also be used with form {[modifier
'flag --log': 'log',
header: 'Welcome to the IoP'
},
header('Welcome to the IoP'),
footer('holepunch.to | pears.com | keet.io'),
run
)
cmd.parse(['--help']) // print pear help
cmd.parse(['run', '-h']) // print run help
cmd.parse(['run', '-s', '/path/to/store', 'pear://link']) // exec run command
run.add(flag('--pre-io', 'Show stdout & stderr of pre scripts')) // update command
cmd.parse(['run', '-s', '/path/to/store', '--pre-io', 'pear://link']) // exec run command
`
This should output:
`
Welcome to the IoP
pear [flags] [command]
pear cli
Flags:
--log log
--help|-h Show help
Commands:
run Run an app from a link
holepunch.to | pears.com | keet.io
Welcome to the IoP
pear run [flags] [...app-args]
Run an app from a link
Run an app from a file link (or path) or from a pear link.
Optionally supply store for custom store path
Arguments:
link to run
[...app-args]
Flags:
--store|-s [path] store path
--help|-h Show help
holepunch.to | pears.com | keet.io
ACTION -> run pear://link flags: { store: '/path/to/store', s: '/path/to/store', help: false, h: false }
ACTION -> run pear://link flags: {
store: '/path/to/store',
s: '/path/to/store',
help: false,
h: false,
preIo: true
}
`
Defines a command with a specific behavior based on the supplied modifiers such as flags, arguments, and descriptions. This function is used to create the command object.
- Arguments:
- name : The name of the command....args
-
- Returns:
- cmd : The command object capable of parsing CLI arguments and executing associated actions.
#### cmd.add(...args)
Update command with additional modifiers & subcommands. A runner function may also be added, but only one runner is supported so will in that case replace the prior command runner function.
- Arguments:
- ...args : Supply modifiers and subcommands as arguments. Supply a single function argument as the command runner.
- Returns:
- cmd : The command object capable of parsing CLI arguments and executing associated actions.
#### cmd.parse(argv = process.argv.slice(2), opts)
Parses an array of command line arguments and executes the command based on the provided definition. Automatically handles '--help' or '-h' flags to display help information.
- Arguments:
- argv : An array of strings representing the command line arguments. Defaults to program arguments process.argv.slice(2) if unspecified. If the -h or --help flag is supplied help for the related command will be shown.opts
-
#### cmd.help(...subcommands)
Generates and returns help text for the command. Can take subcommand names as arguments to generate help for a specific subcommand path. When calling cmd.parse(argv), if the -h or --help flag is supplied, this method is automatically called and output.
#### cmd.usage(...subcommands)
Returns help text without header or footer. Can take subcommand names as arguments to generate help for a specific subcommand path.
#### cmd.overview({ full = false })
Returns a string with a command overview. Set full to true to include detailed usage for each command.
- Arguments:
- full : Whether to display a full overview that includes details of all defined sub-commands and flags.
#### cmd.running
Either null if the command is not running or a promise that resolves when the command has completed running.
#### cmd.bailed
Either null if the command did not bail or an object descibing the bail. The object can be { bail
#### cmd.flags
After cmd.parse has been called, contains parsed flag values.
#### cmd.args
After cmd.parse has been called, contains parsed arguments.
#### cmd.positionals
After cmd.parse has been called, contains original arguments in isolation.
#### cmd.rest
After cmd.parse has been called, contains rest arguments, if any, on cmd.rest.restName where restName is definedrest(spec)
by where spec is [..rest-name].
#### cmd.parent
Command parent
#### cmd.name
Command name
#### cmd.description
Command description
#### cmd.summary
Command summary
#### cmd.header
Command header
#### cmd.footer
Command footer
#### cmd.indices.flags
After cmd.parse has been called, contains the index of each flag in the original array.
#### cmd.indices.args
After cmd.parse has been called, contains the index of each parsed argument in the original array.
#### cmd.indices.positionals
After cmd.parse has been called, contains the indexes of each positional argument in the original array.
#### cmd.indices.rest
After cmd.parse has been called, contains the index of the first rest argument in the positional array.
Defines a flag for a command. Flags can be simple boolean switches or can expect a value.
- Arguments:
- spec : --long|-l ( , e.g., --boolean-flag|-b, --string-flag [optional-value], --string-flag description
- : A description of what the flag does.
- Returns:
- flag : A modifier that configures the command to recognize and handle the specified flag.flag.hide()
- to hide the flag from help.flag.multiple()
- to make this flag into an array of all passed values instead of the latest one only.
Defines a positional argument for a command.
- Arguments:
- spec : [arg] | where arg is the placeholder name for the argument, e.g. , (required) [dir] (optional)description
- : A description of what the argument is for.
- Returns:
- : A modifier that configures the command to accept and process the specified argument.
Defines rest arguments that are captured after all flags and named arguments.
- Arguments:
- spec : [...rest-name]. The name to collect rest arguments under, e.g. [...app-args] array will be stored at cmd.rest.appArgs.description
- : Description of what these rest arguments represent.
- Returns:
- : A modifier that configures the command to capture additional arguments not explicitly defined.
Defines a validation function for the command. This function is used to enforce custom validation logic on the command after parsing, such as checking the relationship of flags, arguments, rest arguments, etc.
- Arguments:
- validator : A function that takes the parsed command object and returns a boolean indicating whether the validation passed. If the validation fails, the function should throw an error or return a string describing the validation error.args
- Parameters:
-
- Returns:
- : A modifier that configures the command to use the specified validation function.
Defines a brief summary of the command's functionality.
- Arguments:
- text : Summary of the command's purpose.
- Returns:
- : A modifier containing the summary information.
Defines a detailed description of the command's functionality.
When used as a tagged template function, description automatically dedents the text.
- Arguments:
- text : Detailed information about the command.
- Returns:
- : A modifier containing the description information.
Define a header for the command's help output.
- Arguments:
- text : Text to display at the top of the output.
- Returns:
- : A modifier that configures the header text.
Define a footer for the command's help & overview output.
- Arguments:
- text | : Text to display at the bottom of the help and/or overview output.
- Returns:
- : A modifier that configures the footer text.
Set the bail handler to fn.
Configures the command to be non-strict when parsing unknown flags or arguments.
The command function can also accept plain objects with the following form:
``
{[modifier
modifier: names of exported functions designed to passed to command function such as flag(...), arg(...), summary(...) and so on.: first arg passed, e.g. flag('--some value') -> 'flag --some value', rest('[...args]') -> 'rest [...args]': second arg passed to modifier flag('--some value', 'some flag') -> {'flag --some value': 'some flag'}[': adjusters are methods on modifiers, such as flag.multiple(), flag.choices(...), flag.hide() and arg.hide(). For adjusters with args the value should be the arg eg {choices: ['a', 'b', 'c']}, otherwise set to true to enable { multiple: true }
Example:
`js``
import { command } from 'paparam'
const cmd = command({
name: 'pear',
summary: 'summary text',
description: 'description text',
header: 'header text',
footer: 'footer text',
'flag --define flag': 'describe flag',
'flag --define multiflag': ['describe flag', { multiple: true }],
'flag --define hidden-flag': ['describe flag', { hide: true }],
'flag --define choices': ['describe flag', { choices: ['a', 'b', 'c'] }],
'arg
'hidden [arg]': ['hidden optional arg', { hide: true }],
rest: '[...args]',
command: {
name: 'run',
summary: 'a subcommand'
}
})
cmd.parse(['-h'])
This is a useful format for supporting JSON-based definitions of commands.
Apache-2.0