Module cartridge.argparse

Gather configuration options.

The module reads configuration options from multiple sources and then merges the options together according to source priority:

--<VARNAME> command line arguments.
TARANTOOL_<VARNAME> environment variables.
Configuration files.

To specify a configuration file, use the --cfg <CONFIG_FILE> option or the TARANTOOL_CFG=<CONFIG_FILE> environment variable.

Configuration files are .yaml files, divided into sections like the following:

default:
  memtx_memory: 10000000
  some_option: "default value"
myapp.router:
  memtx_memory: 1024000000
  some_option: "router-specific value"

Within the configuration file, argparse looks for multiple matching sections:

The section named <APP_NAME>.<INSTANCE_NAME> is parsed first. The application name is derived automatically from the rockspec filename in the project directory. Alternatively, you can specify it manually via the --app-name command line argument or the TARANTOOL_APP_NAME environment variable. The instance name can be specified the same way, either as --instance-name or TARANTOOL_INSTANCE_NAME .
The common <APP_NAME> section is parsed next.
Finally, the section [default] with the global configuration is parsed with the lowest priority.

An instance name may consist of multiple period-separated parts, for example, --app-name "myapp" --instance-name "router.1" . In this case, sections with names that include these parts are also parsed: first [myapp.router.1] , then [myapp.router] , then [myapp] .

Instead of a single configuration file, you can use a directory. In this case, all files in the directory are parsed. To avoid conflicts, the same section mustn’t repeat across different files.

Functions

parse ()

Parse command line arguments, environment variables, and configuration files.

For example, running an application as follows:

TARANTOOL_MY_CUSTOM_ARG='value' ./init.lua --alias router --memtx-memory 100

results in:

local argparse = require('cartridge.argparse')
argparse.parse()
---
- memtx_memory: '100'
  my_custom_arg: value
  alias: router
...

Returns:

({argname=value,…})

get_opts (filter)

Filter the results of parsing and cast variables to a given type.

From all the configuration options gathered by parse , select only those specified in the filter.

For example, running an application as follows:

TARANTOOL_ARG1='value' tarantool ./init.lua --arg2 100 --arg3 true

results in:

local opts, err = argparse.get_opts({
    arg1 = 'string',
    arg2 = 'number',
    arg3 = 'boolean'
    missing_arg = 'string', -- no such arg, argparse returns nothing for this arg
})
---
- arg1: value
  arg2: 100
  arg3: true
...

Each option have a type: string, boolean, number. There is an ability to set multiple types for one option. Types are split by separator | , e.g. string|number .

Parameters:

filter: ({argname=type,…})

Returns:

({argname=value,…})

get_box_opts ()

Shorthand for get_opts(box_opts) .

get_cluster_opts ()

Shorthand for get_opts(cluster_opts) .

Tables

cluster_opts

Common cartridge.cfg options.

Any options not listed below (like the roles option) can’t be modified with argparse and should be configured in code.

Fields:

alias: string
workdir: string
http_port: number
http_host: string
http_enabled: boolean
webui_enabled: boolean
webui_prefix: string
webui_enforce_root_redirect: boolean
advertise_uri: string
cluster_cookie: string
console_sock: string
auth_enabled: boolean
bucket_count: number
upgrade_schema: boolean
swim_broadcast: boolean
upload_prefix: string

box_opts

Common box.cfg tuning options.