config.cpp File Reference

Reading and writing configuration files. More...

import cli11:app;
import std;

Functions
auto	cli::detail::convert_arg_for_ini (const std::string &arg, char string_quote='"', char literal_quote = '\'', bool disable_multi_line = false) -> std::string
	Quotes and escapes one value for writing to a configuration file.
auto	cli::detail::ini_join (const std::vector< std::string > &args, char sep_char=',', char array_start='[', char array_end=']', char string_quote='"', char literal_quote = '\'') -> std::string
	Joins values into one configuration entry, quoting as needed.
auto	cli::detail::generate_parents (const std::string &section, std::string &name, char parent_separator) -> std::vector< std::string >
	Splits a section path and a name into a list of parent sections.
auto	cli::detail::check_parent_segments (std::vector< config_item_t > &output, const std::string &current_section, char parent_separator) -> void
	Emits the section transitions needed before a new section.
auto	cli::detail::is_printable (const std::string &test_string) -> bool
	Reports whether a string is safe to write unescaped.
auto	cli::detail::has_ml_string (const std::string &full_string, char check) -> bool
	Reports whether a line ends with a triple-quote delimiter.
auto	cli::detail::find_matching_config (std::vector< config_item_t > &items, const std::vector< std::string > &parents, const std::string &name, bool full_search) -> std::vector< config_item_t >::iterator
	Finds an entry with a given section path and name.
auto	cli::clean_name_string (std::string &name, const std::string &key_chars) -> std::string &
	Quotes a name for writing when it contains anything structural.

Variables
constexpr std::string_view	cli::multiline_literal_quote = R"(''')"
	Opening and closing delimiter for a multi-line literal string.
constexpr std::string_view	cli::multiline_string_quote = R"(""")"
	Opening and closing delimiter for a multi-line escaped string.

Detailed Description

Reading and writing configuration files.

Implements cli::config_base_t, declared in the config_fwd partition. Writing walks an cli::app_t and emits one entry per configurable option, quoting values as needed; reading parses entries back into cli::config_item_t values that app_t then applies as if they had been given on the command line.

The format is TOML-shaped but every piece of punctuation is configurable, so the same code handles INI. Section nesting maps to subcommands, with [a.b] addressing subcommand b of subcommand a.

Function Documentation

check_parent_segments()

auto cli::detail::check_parent_segments ( std::vector< config_item_t > & output, const std::string & current_section, char parent_separator ) -> void

export

Emits the section transitions needed before a new section.

Compares the section being opened against the one already open and appends the closing and opening markers required to get from one to the other.

Parameters

[in,out]	output	The entries built so far.
[in]	current_section	The section being opened.
[in]	parent_separator	The character separating nested names.

clean_name_string()

auto cli::clean_name_string ( std::string & name, const std::string & key_chars ) -> std::string &

export

Quotes a name for writing when it contains anything structural.

Prefers the literal form; falls back to the escaped form when the name already contains an apostrophe.

Parameters

[in,out]	name	The name to quote in place.
[in]	key_chars	The characters that force quoting.

Returns

A reference to name.

convert_arg_for_ini()

auto cli::detail::convert_arg_for_ini ( const std::string & arg, char string_quote = '"', char literal_quote = '\'', bool disable_multi_line = false ) -> std::string

export

Quotes and escapes one value for writing to a configuration file.

Parameters

arg	The value to convert.
string_quote	The character used around escaped strings.
literal_quote	The character used around literal strings.
disable_multi_line	Never use the triple-quoted multi-line form.

Returns

The value, quoted if it needs to be.

find_matching_config()

auto cli::detail::find_matching_config ( std::vector< config_item_t > & items, const std::vector< std::string > & parents, const std::string & name, bool full_search ) -> std::vector< config_item_t >::iterator

export

Finds an entry with a given section path and name.

Searches backwards, since a repeated field is normally adjacent to its earlier occurrence.

Parameters

items	The entries to search.
parents	The section path to match.
name	The entry name to match.
full_search	Search the whole list rather than only the last entry.

Returns

An iterator to the match, or items.end().

generate_parents()

auto cli::detail::generate_parents ( const std::string & section, std::string & name, char parent_separator ) -> std::vector< std::string >

export

Splits a section path and a name into a list of parent sections.

Parameters

[in]	section	The section the entry was found in.
[in,out]	name	The entry name; reduced to its last component.
[in]	parent_separator	The character separating nested names.

Returns

The parent sections, outermost first.

has_ml_string()

auto cli::detail::has_ml_string ( const std::string & full_string, char check ) -> bool

export

Reports whether a line ends with a triple-quote delimiter.

Parameters

full_string	The line to inspect.
check	The quote character to look for.

Returns

true if the line ends with three of check.

ini_join()

auto cli::detail::ini_join ( const std::vector< std::string > & args, char sep_char = ',', char array_start = '[', char array_end = ']', char string_quote = '"', char literal_quote = '\'' ) -> std::string

export

Joins values into one configuration entry, quoting as needed.

Parameters

args	The values to join.
sep_char	The character placed between values.
array_start	The character opening an array; '\0' disables arrays.
array_end	The character closing an array; '\0' disables arrays.
string_quote	The character used around escaped strings.
literal_quote	The character used around literal strings.

Returns

The joined entry.

is_printable()

auto cli::detail::is_printable ( const std::string & test_string ) -> bool

export

Reports whether a string is safe to write unescaped.

Newlines and tabs count as printable, since the multi-line form can carry them.

Parameters

test_string

The string to test.

Returns

true if every character is printable.