/opt/batocera-emulationstation/node_modules/cmdline/api.js

Overview

This file contains a generic utility to define command line actions + arguments for them, as well as the parser to map the input array into a more convenient structure.
It is also capable of some basic verifications to make sure required arguments were and - optionally - that they are of a certain type.
The idea of this utility was to separate handling the logic of argument parsing and validation from their definition to keep the command definitions as short and concise as possible. But it should also allow extended configuration when needed (rarely).

Basic flow:

1. Define the action with action(optionSpec, handler).
   This will return a function mapping handler which takes care of the pre-processing.
2. Call the mapper function with a raw array of arguments as coming from process.argv.
3. The mapper uses processOptionConfig(optionSpec) to evaluate which options and arguments are expected.
   This yields an instance of [OptionConfig].
4. The instance of OptionConfig will be passed to parseCmdLine(config, argv) to apply the configuration against the the actually passed console arguments. The resulting [ParsedOptionDict] and the list of transformed/filtered positional arguments are passed to the handler function.

See also

• processOptionConfig
• parseCmdLine

Index

• class ParsedOptionDict
• class ParsedCmdLine
• parseCmdLine
• VALIDATORS
  • argsRemaining
• _pseudoBind
• processOptionConfig

class ParsedOptionDict

Any handler passed to api.action(optionSpec, handler) receives an instance of this class as first argument.
It’s mostly just a simple object, with a few convenience helpers for easier processing.

The keys used correspond to those of all named (=none-integer) options contained in optionSpec, but the values are converted according the the validators used (if any).

Example

 Input: api.action({ '--flag': 0 }, ...)
Output: { '--flag' : true|false }

class ParsedCmdLine

This is the main return value of parseCmdLine().
It is used internally in api.action() as intermediate class to transport the results of command line parsing.
Handler functions will get the contents of ParsedCmdLine.options as first argument and the entries of ParsedCmdLine.arguments unpacked into separate varArgs.

• options is [ParsedOptionDict]
• arguments is a mixed-type arry

parseCmdLine

This function uses the preprocessed [OptionConfig] to parse and transform the actual command line.
Argument values are transformed according to the Validators specified in the initial optionSpec.

See also

• processOptionConfig
• VALIDATORS

VALIDATORS

This is a dictionary containing all known command line argument validators. These validators serve 2 purposes:

• They check if a given argument value matches a specific criteria
• (Optionally) Convert the raw argument to another type of structure, depending on the concrete validator

How to use:

• All inbuild validators can be used by specifying a certain value for an argument in optionSpec.
• But there is also the option of importing and directly assigning them. This only works for simple validators that do not require additional configuration
• The validator names can also be used. But this does also not work with validators requiring more arguments.
• Full rules explaining how optionSpec works in the section [processOptionConfig]

But for most use cases, there is no need to use, touch or look at this dictionary.

Internally, validators can run in 2 different ‘modes’.

1. ‘Name’ mode - The validator does not perform any action, but returns a string representation of its expectation/format.
   This is used in case of errors and when btc-config --help is used to print commands and their arguments.
2. ‘Validation’ mode - Regular operation when command line arguments are evaluated.

The object VALIDATORS itself is a {Proxy} with an implementation of get() which returns bound functions. That way, argument configuration is attached to validators and the bound/pre-configured validators are used when parsing the command line.

argsRemaining

Check that the given number of arguments is still available to be parsed.
Configuration for optionSpec to use this is:

//simple variant - one argument
action({ optionName: # }, (options) => {})
//complex variant, allows to pass custom name prefix for the help function in addition to number of args
{ optionName: { argsRemaining: #, (#offset), string|function} }

• # must be an integer number >= 0.
• #offset defines where to start numbering arguments in the generated help.
  0 for # itself only works for string-named options, not for positional arguments. Such options will be considered as boolean true/false flags.

_pseudoBind

Bind does not allow to change this, but the resulting validator must be able to receive another this.

processOptionConfig

This function unpacks and inteprets the optionSpec given to [action]. It receives the first argument passed to [action] and expects this to be a dictionary with a certain format.

{
<optionName> : validatorConfig|validatorName|typeSpec,
<#posInt>: validatorConfig|validatorName|typeSpec
#POS: int
}

Rules for keys:

• <optionName>: any literal string, none-number string.
  ‘-‘ or ‘–’ must be part of the string if desired. This is used for named options.
• <#posInt>: Numbers, or strings parsing as numbers. These are positional arguments, starting with 1.
• #POS: special type. Allows to enforce a minimum number of positional arguments.
• Any <optionName> or <#posInt> can be prefixed with ‘*’ to mark the given argument as required.
  When such an argument is not given, or the configured validation fails, the action aborts with an error.

Values:

• {number} > 0: [argsRemaining] with given number of arguments

• 0: [argsRemaining] - for string-named options: true

  false flags

• {RegEx}: [regExp] - argument given at position or as value must match expression
• ‘file’: [file] - argument given at position or as value must be an existing file
• ‘csv’: [commaList] - argument at position or as value will be interpreted as csv.
  Must have at least one entry (must not be empty)
• {Array}: [includesFirst] - Useful for enum-like string argument lists.
  Argument on command line must be a string matching one entry of the array.
• {validatorName: validatorConfig} - Provides a way to pass extended validator configuration.
  Only applicable to [argsRemaining] for now, or - more generically - to validators taking more then one
  argument in “factory mode”.

_{Generated with shdoc from /opt/batocera-emulationstation/node_modules/cmdline/api.js}