cli Object

The primary export you receive when you require the library. For example:

local cli = require 'cliargs'

cli:set_description Function

Write down a brief, 1-liner description of what the program does.

cli:set_colsz Function

Sets the amount of space allocated to the argument keys and descriptions in the help listing.

The sizes are used for wrapping long argument keys and descriptions.

Parameters

  1. key_cols: number

    The number of columns assigned to the argument keys, set to 0 to auto detect.

  2. desc_cols: number

    The number of columns assigned to the argument descriptions, set to 0 to auto set the total width to 72.

cli:load_defaults Function

Load default values from a table.

Parameters

  1. config: table

    Your new set of defaults. The keys could either point to the short or expanded option keys, and their values are the new defaults.

  2. strict: boolean

    Turn this on to return nil and an error message if a key in the config table could not be mapped to any CLI option.

Return Values

  1. true

    When the new defaults were loaded successfully, or strict was not set.

  2. union.<nil, string>

    When strict was set and there was an error.

cli:read_defaults Function

Read config values from a configuration file.

Parameters

  1. path: string

    Absolute file path.

  2. format: string

    The config file format, which has to be one of: "lua", "json", "ini", or "yaml". When this is left blank, we try to auto-detect the format from the file extension.

  3. strict: boolean

    Forwarded to #load_defaults. See that method for the parameter description.

Return Values

  1. true|union.<nil, string>

    Returns true on successful load. Otherwise, nil and an error message are returned instead.

cli:argument Function

Define a required argument.

Required arguments do not take a symbol like - or --, may not have a default value, and are parsed in the order they are defined.

For example:

cli:argument('INPUT', 'path to the input file')
cli:argument('OUTPUT', 'path to the output file')

At run-time, the arguments have to be specified using the following notation:

$ ./script.lua ./main.c ./a.out

If the user does not pass a value to every argument, the parser will raise an error.

Parameters

  1. key: string

    The argument identifier that will be displayed to the user and be used to reference the run-time value.

  2. desc: string

    A description for this argument to display in usage help.

  3. callback: function

    Callback to invoke when this argument is parsed.

cli:splat Function

Defines a "splat" (or catch-all) argument.

This is a special kind of argument that may be specified 0 or more times, the values being appended to a list.

For example, let's assume our program takes a single output file and works on multiple source files:

cli:argument('OUTPUT', 'path to the output file')
cli:splat('INPUTS', 'the sources to compile', nil, 10) -- up to 10 source files

At run-time, it could be invoked as such:

$ ./script.lua ./a.out file1.c file2.c main.c

If you want to make the output optional, you could do something like this:

cli:option('-o, --output=FILE', 'path to the output file', './a.out')
cli:splat('INPUTS', 'the sources to compile', nil, 10)

And now we may omit the output file path:

$ ./script.lua file1.c file2.c main.c

Parameters

  1. key: string

    The argument's "name" that will be displayed to the user.

  2. desc: string

    A description of the argument.

  3. default:

    A default value.

  4. maxcount: number

    The maximum number of occurences allowed.

  5. callback: function

    A function to call everytime a value for this argument is parsed.

cli:option Function

Defines an optional argument.

Optional arguments can use 3 different notations, and can accept a value.

Parameters

  1. key: string

    The argument identifier. This can either be -key, or -key, --expanded-key. Values can be specified either by appending a space after the identifier (e.g. -key value or --expanded-key value) or by separating them with a = (e.g. -key=value or --expanded-key=value).

  2. desc: string

    A description for the argument to be shown in --help.

  3. default: bool

    A default value to use in case the option was not specified at run-time (the default value is nil if you leave this blank.)

  4. callback: function

    A callback to invoke when this option is parsed.

Example

The following option will be stored in args["i"] and args["input"] with a default value of file.txt:

cli:option("-i, --input=FILE", "path to the input file", "file.txt")

cli:flag Function

Define an optional "flag" argument.

Flags are a special subset of options that can either be true or false.

For example:

cli:flag('-q, --quiet', 'Suppress output.', true)

At run-time:

$ ./script.lua --quiet
$ ./script.lua -q

Passing a value to a flag raises an error:

$ ./script.lua --quiet=foo
$ echo $? # => 1

Flags may be negatable by prepending [no-] to their key:

cli:flag('-c, --[no-]compress', 'whether to compress or not', true)

Now the user gets to pass --no-compress if they want to skip compression, or either specify --compress explicitly or leave it unspecified to use compression.

Parameters

  1. key: string

  2. desc: string

  3. default:

  4. callback: function

cli:command Function

Define a command argument.

Parameters

  1. name: string

    The name of the command and the argument that the user has to supply to invoke it.

  2. desc: string

    An optional string to show in the help listing which should describe what the command does. It will be displayed if --help was run on the main program.

Return Values

  1. cmd

    Another instance of the CLI library which is scoped to that command.

cli:parse Function

Parse the process arguments table.

Parameters

  1. arguments: table.<string>

    The list of arguments to parse. Defaults to the global arg table which contains the arguments the process was started with.

Return Values

  1. table

    A table containing all the arguments, options, flags, and splat arguments that were specified or had a default (where applicable).

  2. array.<nil, string>

    If a parsing error has occured, note that the --help option is also considered an error.

cli:print_usage Function

Prints the USAGE message.

Return Values

  1. string

    The USAGE message.

cli:print_help Function

Prints the HELP information.

Return Values

  1. string

    The HELP message.

cmd Object

This is a special instance of the cli module that you receive when you define a new command using cli#command.

cmd:file Function

Specify a file that the command should run. The rest of the arguments are forward to that file to process, which is free to use or not use lua_cliargs in turn.

Parameters

  1. file_path: string

    Absolute file-path to a lua script to execute.

cmd:action Function

Define a command handler. This callback will be invoked if the command argument was supplied by the user at runtime. What you return from this callback will be returned to the parent CLI library's parse routine and it will return that in turn!

Parameters

  1. callback: function

Made with ♥ using tinydoc.