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.

Argparse logs if there were some ignored sections in configuration files. All sections should be key-value pairs as in example, otherwise you’ll get an error.

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 33554432

results in:

local argparse = require('cartridge.argparse')
argparse.parse()
---
- memtx_memory: 33554432
  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
rebalancer_mode: string
upgrade_schema: boolean
swim_broadcast: boolean
upload_prefix: string
transport: string
ssl_ciphers: string
ssl_server_ca_file: string
ssl_server_cert_file: string
ssl_server_key_file: string
ssl_server_password: string
ssl_client_ca_file: string
ssl_client_cert_file: string
ssl_client_key_file: string
ssl_client_password: string
disable_errstack: boolean
enable_synchro_mode: boolean
disable_raft_on_small_clusters: boolean
enable_failover_suppressing: boolean
twophase_netbox_call_timeout: number
twophase_upload_config_timeout: number
twophase_validate_config_timeout: number
twophase_apply_config_timeout: number

box_opts

Common box.cfg tuning options.