@wcauchois/program-builder > ProgramBuilder

ProgramBuilder class

Entry point to the library and the way to start constructing a Program to be executed.

Signature:

export default class ProgramBuilder<T> extends ProgramBase

Remarks

Create a new ProgramBuilder with ProgramBuilder.newBuilder(), then define flags using the instance methods. Finally, call ProgramBuilder.build() to get an executable Program.

There are a few categories to configure:

Positional arguments

Use arg or optionalArg to define positional arguments.

Example:

const program = ProgramBuilder.newBuilder()
  .arg('filename', { description: 'The filename to use' })
  .optionalArg('extraFilename')
  .build();

Invoked as:

$ my-program foo.txt bar.txt

Boolean flags

Use flag to define a boolean flag that is set by its presence.

Valued flags

Use methods like stringFlag and intFlag to define "valued" flags, known as options in other CLI libraries. For these, the user must specify a value immediately following the flag, like "--count 42". The value is converted to a type indicated by the name of the method.

Getting the Arguments type

You can use the Arguments type helper to get the type of the arguments for a program. This is helpful if you want to define your main function separately.

const program = ProgramBuilder.newBuilder().build();
function main(args: Arguments<typeof program>) {
  // Do things with args.
}
program.exec(main);

Methods

Method	Modifiers	Description
apply(fn)		Apply a function to this program builder. This can be used to factor out common argument patterns.
arg(dest, options)		Add a positional argument to the program.
bind(action)		Bind the ProgramBuilder to an action and return a ProgramWithAction suitable for use constructing subcommands.
build()		Build and return a Program.
buildWithSubcommands(subcommandMap, metadata)	static	Build a ProgramWithSubcommands using a map of ProgramWithActions as created by calling ProgramBuilder.bind .
customFlag(name, options, converter)		Add an optional custom valued flag to the program.
customFlag(name, options, converter)		Add a required custom valued flag to the program.
description(newDescription)		Set the program description.
flag(name, options)		Add a boolean-valued flag to the program (sometimes known as a "switch").
floatFlag(name, options)		Add an optional valued flag to the program.
floatFlag(name, options)		Add a required valued flag to the program.
intFlag(name, options)		Add an optional valued flag to the program.
intFlag(name, options)		Add a required valued flag to the program.
newBuilder()	static	Create a new ProgramBuilder instance.
optionalArg(dest, options)		Add an optional positional argument to the program.
stringFlag(name, options)		Add an optional valued flag to the program.
stringFlag(name, options)		Add a required valued flag to the program.