cliargs

# `cliargs`

### `cli:set_name(name)`

Assigns the name of the program which will be used for logging.

### `cli:add_arg(key, desc)`

Defines a required argument. Required arguments have no special notation and are order-sensitive. Note: the value will be stored in `args[@key]`. Aliases: `add_argument`

### Parameters

1. key: the argument’s “name” that will be displayed to the user
2. desc: a description of the argument

### Usage example

The following will parse the argument (if specified) and set its value in `args["root"]`: `cli:add_arg("root", "path to where root scripts can be found")`

### `cli:optarg(key, desc, default, maxcount)`

Defines an optional argument (or more than one). There can be only 1 optional argument, and is has to be the last one on the argumentlist. Note: the value will be stored in `args[@key]`. The value will be a ‘string’ if ‘maxcount == 1’, or a table if ‘maxcount > 1’

### Parameters

1. key: the argument’s “name” that will be displayed to the user
2. desc: a description of the argument
3. default: optional; specify a default value (the default is "")
4. maxcount: optional; specify the maximum number of occurences allowed (default is 1)

### Usage example

The following will parse the argument (if specified) and set its value in `args["root"]`: `cli:add_arg("root", "path to where root scripts can be found", "", 2)` The value returned will be a table with at least 1 entry and a maximum of 2 entries

### `cli:add_opt(key, desc, default)`

Defines an option. Optional arguments can use 3 different notations, and can accept a value. Aliases: `add_option`

### Parameters

1. key: the argument identifier, can be either `-key`, or `-key, --expanded-key`: if the first notation is used then a value can be defined after a space (`'-key VALUE'`), if the 2nd notation is used then a value can be defined after an `=` (`'-key, --expanded-key=VALUE'`). As a final option it is possible to only use the expanded key (eg. `'--expanded-key'`) both with and without a value specified.
2. desc: a description for the argument to be shown in –help
3. default: optional; specify a default value (the default is "")

### Usage example

The following option will be stored in `args["i"]` and `args["input"]` with a default value of `my_file.txt`: `cli:add_option("-i, --input=FILE", "path to the input file", "my_file.txt")`

### `cli:add_flag(key, desc)`

Define a flag argument (on/off). This is a convenience helper for cli.addopt(). See cli.addopt() for more information.

### Parameters

1. key: the argument’s key
2. desc: a description of the argument to be displayed in the help listing

### `cli:parse(noprint, dump)`

Parses the arguments found in #arg and returns a table with the populated values. (NOTE: after succesful parsing, the module will delete itself to free resources) Aliases: `parse_args`

### Parameters

1. noprint: set this flag to prevent any information (error or help info) from being printed
2. dump: set this flag to dump the parsed variables for debugging purposes, alternatively set the first option to –DEBUG (option with 2 trailing and leading underscores) to dump at runtime.

### Returns

1. a table containing the keys specified when the arguments were defined along with the parsed values, or nil + error message (–help option is considered an error and returns nil + help message)

### `cli:print_usage(noprint)`

Prints the USAGE heading.

### Parameters

1. noprint: set this flag to prevent the line from being printed

### Returns

1. a string with the USAGE message.

### `cli:print_help(noprint)`

Prints the HELP information.

### Parameters

1. noprint: set this flag to prevent the information from being printed

### Returns

1. a string with the HELP message.

### `cli:set_colsz(key_cols, desc_cols)`

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: the number of columns assigned to the argument keys, set to 0 to auto detect (default: 0)
2. desc_cols: the number of columns assigned to the argument descriptions, set to 0 to auto set the total width to 72 (default: 0)

cliargs