beamander v3.5.2

beamander

Parser for user input commands.

Usage example

Add a command using the .command() method:

import { commander, Parsed } from 'beamander';

// command specification
commander
  .command("skip", "clear")
  .option("-r, --reverse")
  .option("-a, --all")
  .option("-s, --self")
  .argument("songs...");

Then use .parse() to parse input strings:

const input = "clear 1 2 4 11 5..9 --reverse";
const output = commander.parse(input);

The parser will then return an object with the Parsed.Command type. In this example, the output will be:

// the `output` object
{
  aliases: ["skip", "clear"],
  arguments: {
    songs: {
      value: ["1", "2", "4", "11", "5..9"],
      variadic: true,
    },
  },
  invokedName: "clear",
  name: "skip",
  options: {
    all: false,
    help: false,
    reverse: true,
    self: false,
  },
  optionsUsedCorrectly: true,
}

Details

Parsed.Command explained

This is an object that always has a fixed number of fields: aliases, arguments, invokedName, name, options, and optionsUsedCorrectly.

aliases

An array of strings that holds all the known names for the command (including the original name).

arguments

When you use the .argument() method, the name that you provided will be used as the property's name to arguments while the corresponding value will be an object containing the following fields:

  value: string[];
  variadic: boolean;

invokedName

The name used to trigger the command to be run.

name

The original name for the command.

options

An object with boolean valued properties. Always contains a help property by default. Additional boolean properties will be added to it when you use the .option() method and the new property name will be the same as the long option name you have provided.

optionsUsedCorrectly

A boolean value indicating whether the options are used correctly or not. E.g. some unknown options were accidentally added, option name typo, etc.

Creating a command

When you create a command using .command(), you can provide aliases for your command after the first argument, like so:

.command("originalName", "alias1", "alias2", "alias3")

Then the parsed output will contain an array named aliases that has all the names (including the original name) for your command:

aliases: ["originalName", "alias1", "alias2", "alias3"]

Creating an option

You can create an option for a command using the .option() method. It accepts a string that contains a short name and a long name like so:

"-f, --foo"

The short name should be followed after - while the long name should be followed after --. The option name will defaults to the long name if it exists.

Creating an argument

You can specify an argument for a command using the .argument() method. You give it a name by providing a string. By default, it will only try to take one value. However, you can make it to take all of the provided values from the input by marking it variadic by appending ... after its name like so:

// marking this argument variadic (take as many values as it can)
.argument("songs...")