# 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