CLI command-line generator for development & debugging tools. This module is used to execute command lines containing command line arguments. Command line strings are quoted similarly to shell quotes in Unix and Windows command lines. Unlike Unix, single quoting is supported. The command line string supports these environment variables:

• %PATH% - calling module in the Lua stack.
• %OS% - Lua version (5.1 for the foreseeable future). This module is supplied arguments in the Scribunto console. The general command synopsis (in man command format) is:

p "<command> [<arg>] [--flag [ <value>]]"

The help command will output a command synopsis in the man command format. This module supports the following syntax:

• Positional arguments (space-delimited): one two three
• Boolean command flags: -one, --one
• Variable command flags: --one "numero uno"
• Quoted arguments: one "numero dos"
• Variable assignments: one="one"
• Escapes: quotes as \\" or \\' and spaces as \\ The first positional argument is recognised as a command word and is executed within the command object. The command sends its output to the Scribunto console using mw.log. Note that command flags must be placed after positional arguments to work. The command API prints the CLI usage if the help command word or --help/-help flag is supplied. When a command is combined with --help or -help, or a command word is defined as a second positional argument, the help statement is tailored to the specific command, its usage and options.

Documentation

Package items

CommandLine:new(config) (function)

Command line function generator.

Parameters:

• config Command line configuration. (table)
  • config.description Interfaced module description. (string)
  • config.commands Object containing command methods. (table)
  • config.words Configuration object with command methods as keys. Each table contains the following configuration table fields:
    • description Description of command. (string)
    • options Dependent options for command. (table)
  • (table)
  • config.options Command line options configuration. This option is defined as an array with option configuration tables as elements. Each table contains the following configuration table fields:
    • name Name of option. Accepts number when the option is a positional argument. (string or number)
    • alias Alias for option. (string; optional)
    • description Description of option. (string)
    • type Type of option. Omitted for boolean flags. (optional)
    • required Whether the argument or flag is not optional. Default: false. (boolean; optional)
  • (table; optional)

Returns: Command line handler. Help commands will produce a command synopsis detailing usage, a list of commands and a list of options. Other commands will be executed if a corresponding method is present in config.commands. (function)

CommandLine:parse(command, config) (function)

Command line shell quote parser.

Parameters:

• command Command line to be parsed. (string)
• config Command line configuration. (table; optional)

Errors:

• "empty command line" (line 377)
• "unterminated quote in command line: $command" (line 382)
• "unconfigured argument or flag "$arg" in command line" (line 424)

Returns:

• Map of processed arguments. The array, or sequential keys in the map list positional arguments in the command line. The flags in the command line are converted into named arguments. Metadata fields:
  • 0 The CLI module name or context.
  • "PATH" The CLI module name or context.
  • -1 The Lua interpreter Scribunto uses.
  • -2 The Lua version Scribunto runs.
  • "OS" The Lua version Scribunto runs.
• (table)
• Array of processed arguments. Includes the metadata fields listed above. (table)
• Number of arguments passed by the user, counted like the C or C++ argc convention. (table)

See also

Original code (Go).