Caporal

# 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

← Action →