# Program
Program class
# Hierarchy
EventEmitter
↳ Program
# Properties
# Readonly
ARRAY
• ARRAY: ARRAY = CaporalValidator.ARRAY
Array validator. Convert any provided value to an array. If a string is provided, this validator will try to split it by commas.
# Readonly
BOOLEAN
• BOOLEAN: BOOLEAN = CaporalValidator.BOOLEAN
Boolean validator. Check that the value looks like a boolean.
It accepts values like true
, false
, yes
, no
, 0
, and 1
and will auto-cast those values to true
or false
.
# Readonly
NUMBER
• NUMBER: NUMBER = CaporalValidator.NUMBER
Number validator. Check that the value looks like a numeric one
and cast the provided value to a javascript Number
.
# Readonly
STRING
• STRING: STRING = CaporalValidator.STRING
String validator. Mainly used to make sure the value is a string,
and prevent Caporal auto-casting of numerical values and boolean
strings like true
or false
.
# Methods
# action
▸ action(action
: Action): Program
Sets a unique action for the entire program.
Parameters:
Name | Type | Description |
---|---|---|
action | Action | Action to run |
Returns: Program
# argument
▸ argument(synopsis
: string, description
: string, options
: CreateArgumentOpts): Command
Add an argument to the unique command of the program.
Parameters:
Name | Type | Default |
---|---|---|
synopsis | string | - |
description | string | - |
options | CreateArgumentOpts | {} |
Returns: Command
# bin
▸ bin(name
: string): Program
Sets the executable name. By default, it's auto-detected from the filename of your program.
example
program.bin('myprog')
Parameters:
Name | Type | Description |
---|---|---|
name | string | Executable name |
Returns: Program
# cast
▸ cast(enabled
: boolean): Program
Enable or disable auto casting of arguments & options at the program level.
Parameters:
Name | Type | Description |
---|---|---|
enabled | boolean |
Returns: Program
# command
▸ command(name
: string, description
: string, config
: Partial‹CommandConfig›): Command
Add a command to the program.
example
program.command('order', 'Order some food')
Parameters:
Name | Type | Default | Description |
---|---|---|---|
name | string | - | Command name |
description | string | - | Command description |
config | Partial‹CommandConfig› | {} | - |
Returns: Command
# configure
▸ configure(props
: Partial‹ProgramConfig›): Program
Configure some behavioral properties.
Parameters:
Name | Type | Description |
---|---|---|
props | Partial‹ProgramConfig› | properties to set/update |
Returns: Program
# description
▸ description(desc
: string): Program
Set the program description displayed in help.
Parameters:
Name | Type |
---|---|
desc | string |
Returns: Program
# disableGlobalOption
▸ disableGlobalOption(name
: string): Program
Disable a global option. Will warn if the global option does not exist of has already been disabled.
Parameters:
Name | Type | Description |
---|---|---|
name | string | Name, short, or long notation of the option to disable. |
Returns: Program
# discover
▸ discover(dirPath
: string): Program
Discover commands from a specified path.
Commands must be organized into files (one command per file) in a file tree like:
└── commands
├── config
│ ├── set.ts
│ └── unset.ts
├── create
│ ├── job.ts
│ └── service.ts
├── create.ts
├── describe.ts
└── get.ts
The code above shows a short example of kubectl
commands and subcommands.
In this case, Caporal will generate the following commands:
- kubectl get [args...] [options...]
- kubectl config set [args...] [options...]
- kubectl config unset [args...] [options...]
- kubectl create [args...] [options...]
- kubectl create job [args...] [options...]
- kubectl create service [args...] [options...]
- kubectl describe [args...] [options...]
- kubectl get [args...] [options...]
Notice how the config
command has a mandatory subcommand associated,
hence cannot be called without a subcommand, contrary to the create
command.
This is why there is no config.ts
in the tree.
Parameters:
Name | Type |
---|---|
dirPath | string |
Returns: Program
# exec
▸ exec(args
: string[], options
: Record‹string, ParserTypes›, ddash
: string[]): Promise‹unknown›
Programmatic usage. Execute input command with given arguments & options
Not ideal regarding type casting etc.
Parameters:
Name | Type | Default | Description |
---|---|---|---|
args | string[] | - | argv array |
options | Record‹string, ParserTypes› | {} | options object |
ddash | string[] | [] | double dash array |
Returns: Promise‹unknown›
# help
▸ help(text
: string, options
: Partial‹CustomizedHelpOpts›): Program
Customize program help. Can be called multiple times to add more paragraphs and/or sections.
Parameters:
Name | Type | Default | Description |
---|---|---|---|
text | string | - | Help contents |
options | Partial‹CustomizedHelpOpts› | {} | Display options |
Returns: Program
# logger
▸ logger(logger
: Logger): Program
Set a custom logger for your program. Your logger should implement the Logger interface.
Parameters:
Name | Type |
---|---|
logger | Logger |
Returns: Program
# name
▸ name(name
: string): Program
Set the program name. If not set, the filename minus the extension will be used.
Parameters:
Name | Type |
---|---|
name | string |
Returns: Program
# option
▸ option(synopsis
: string, description
: string, options
: CreateOptionProgramOpts): Program
Add an option to the unique command of the program,
or add a global option to the program when options.global
is set to true
.
Parameters:
Name | Type | Default | Description |
---|---|---|---|
synopsis | string | - | Option synopsis like '-f, --force', or '-f, --file <file>', or '--with-openssl [path]' |
description | string | - | Option description |
options | CreateOptionProgramOpts | {} | Additional parameters |
Returns: Program
# run
▸ run(argv?
: string[]): Promise‹unknown›
Run the program by parsing command line arguments.
Caporal will automatically detect command line arguments from process.argv
values,
but it can be overridden by providing the argv
parameter. It returns a Promise
of the value returned by the Action triggered.
Be careful
This method returns a Promise
. You'll usually ignore the returned promise and call run() like this:
[...]
program.action(...)
program.run()
If you do add some .catch()
handler to it, Caporal won't display any potential errors
that the promise could reject, and will let you the responsibility to do it.
Parameters:
Name | Type | Description |
---|---|---|
argv? | string[] | Command line arguments to parse, default to process.argv.slice(2) . |
Returns: Promise‹unknown›
# strict
▸ strict(strict
: boolean): Program
Toggle strict mode.
Shortcut to calling: .configure({ strictArgsCount: strict, strictOptions: strict })
.
By default, the program is strict, so if you want to disable strict checking,
just call .strict(false)
. This setting can be overridden at the command level.
Parameters:
Name | Type | Default | Description |
---|---|---|---|
strict | boolean | true | boolean enabled flag |
Returns: Program
# version
▸ version(ver
: string): Program
Set the version fo your program. You won't likely use this method as Caporal tries to guess it from your package.json
Parameters:
Name | Type |
---|---|
ver | string |
Returns: Program