Internals

Commander.js Internals

Overview

Commander.js is a complete solution for node.js command-line interfaces. It provides a simple and intuitive way to define and parse command-line options and arguments.

Command Class

The Command class is the core of Commander.js. It provides methods for defining options, arguments, and commands. The Command class also provides methods for parsing the command-line arguments and options.

Options

Options are defined using the .option() method. Each option can have a short flag (single character) and a long name, separated by a comma, a space, or a vertical bar (|). To allow a wider range of short-ish flags than just single characters, you may also have two long options.

program
  .option('--first')
  .option('-s, --separator <char>')

Arguments

Arguments are defined using the .argument() method. Each argument can have a name and a description.

program
  .argument('<string>', 'string to split')

Commands

Commands are defined using the .command() method. Each command can have a name, a description, and options.

program
  .command('split')
  .description('Split a string into substrings and display as an array')
  .argument('<string>', 'string to split')
  .option('--first', 'display just the first substring')
  .option('-s, --separator <char>', 'separator character', ',')
  .action((str, options) => {
    const limit = options.first ? 1 : undefined;
    console.log(str.split(options.separator, limit));
  });

Help Class

The Help class is used to generate help messages for the command-line interface. It provides methods for generating help messages for the command, its options, and its arguments.

Command Usage

The commandUsage() method generates a help message for the command.

const helper = new commander.Help();
assert.equal(helper.commandUsage(program), 'program [options]');

Visible Commands

The visibleCommands() method generates a list of visible commands for the command.

const helper = program.createHelp();
const visibleCommandNames = helper
  .visibleCommands(program)
  .map((cmd) => cmd.name());
assert.deepEqual(visibleCommandNames, ['ccc', 'aaa', 'bbb', 'help']);

Error Handling

Commander.js provides a way to handle errors that occur during the parsing of the command-line arguments and options. The CommanderError class is used to represent errors that occur during the parsing of the command-line arguments and options.

const error = new commander.CommanderError(1, 'code', 'failed');

Parsing Configuration

Commander.js provides a way to configure the parsing of the command-line arguments and options. The configureHelp() method is used to configure the parsing of the command-line arguments and options.

program
  .configureHelp({ sortSubcommands: true })
  .command('ccc', 'desc')
  .command('aaa', 'desc')
  .command('bbb', 'desc');

Mermaid Diagram

graph TD
  A[Command] -->|defines|> B[Options]
  A -->|defines|> C[Arguments]
  A -->|defines|> D[Commands]
  B -->|has|> E[Short Flags]
  B -->|has|> F[Long Names]
  C -->|has|> G[Names]
  C -->|has|> H[Descriptions]
  D -->|has|> I[Names]
  D -->|has|> J[Descriptions]
  E -->|separated by|> K[Comma, Space, or Vertical Bar]
  F -->|separated by|> K
  G -->|has|> L[Values]
  H -->|has|> L
  I -->|has|> L
  J -->|has|> L

Sources:

• lib/error.js
• lib/suggestSimilar.js
• tests/testHelpers.js
• tests/command.description.test.js
• tests/command.onCommand.test.js
• tests/imports.test.cjs
• tests/help.commandUsage.test.js
• tests/help.sortCommands.test.js
• tests/command.summary.test.js