advgetopt::conf_file_setup Class Reference

#include <conf_file.h>

Public Types
typedef std::shared_ptr< conf_file_setup >	pointer_t

Public Member Functions
	conf_file_setup (std::string const &filename, conf_file_setup const &original)
	conf_file_setup (std::string const &filename, line_continuation_t line_continuation=line_continuation_t::line_continuation_unix, assignment_operator_t assignment_operator=ASSIGNMENT_OPERATOR_EQUAL, comment_t comment=COMMENT_INI|COMMENT_SHELL, section_operator_t section_operator=SECTION_OPERATOR_INI_FILE, name_separator_t name_separator=NAME_SEPARATOR_UNDERSCORES)
	Initialize the file setup object.
assignment_operator_t	get_assignment_operator () const
	Get the accepted assignment operators.
comment_t	get_comment () const
std::string	get_config_url () const
	Transform the setup in a URL.
std::string const &	get_filename () const
	Get the filename.
line_continuation_t	get_line_continuation () const
	Get the line continuation setting.
name_separator_t	get_name_separator () const
	Retrieve the separator to use within names.
std::string const &	get_original_filename () const
	Get the original filename.
section_operator_t	get_section_operator () const
	Get the accepted section operators.
std::string const &	get_section_to_ignore () const
	Retrieve the name to be ignore.
bool	is_valid () const
	Check whether the setup is considered valid.
void	set_section_to_ignore (std::string const &section_name)
	Set a section name to ignore.

Private Member Functions
void	initialize ()

Private Attributes
assignment_operator_t	f_assignment_operator = ASSIGNMENT_OPERATOR_EQUAL
comment_t	f_comment = COMMENT_INI | COMMENT_SHELL
std::string	f_filename = std::string()
line_continuation_t	f_line_continuation = line_continuation_t::line_continuation_unix
name_separator_t	f_name_separator = NAME_SEPARATOR_UNDERSCORES
std::string	f_original_filename = std::string()
section_operator_t	f_section_operator = SECTION_OPERATOR_INI_FILE
std::string	f_section_to_ignore = std::string()
std::string	f_url = std::string()

Detailed Description

Definition at line 110 of file conf_file.h.

Member Typedef Documentation

pointer_t

typedef std::shared_ptr<conf_file_setup> advgetopt::conf_file_setup::pointer_t

Definition at line 113 of file conf_file.h.

Constructor & Destructor Documentation

conf_file_setup() [1/2]

advgetopt::conf_file_setup::conf_file_setup	(	std::string const &	filename,
		line_continuation_t	line_continuation = line_continuation_t::line_continuation_unix,
		assignment_operator_t	assignment_operator = ASSIGNMENT_OPERATOR_EQUAL,
		comment_t	comment = COMMENT_INI | COMMENT_SHELL,
		section_operator_t	section_operator = SECTION_OPERATOR_INI_FILE,
		name_separator_t	name_separator = NAME_SEPARATOR_UNDERSCORES
	)

This constructor initializes the setup object which can later be used to search for an existing conf_file or creating a new conf_file.

The setup holds the various parameters used to know how to load a configuration file in memory. The parameters include

• filename – the name of the file to read as a configuration file.
• line_continuation – how lines in the files are being read; in most cases a line in a text file ends when a newline character (\\n) is found; this parameter allows for lines that span (continue) on multiple text lines. Only one type of continuation or no continue (a.k.a. "single line") can be used per file.
• assignment_operator – the character(s) accepted between the name of a variable and its value; by default this is the equal sign (=). Multiple operators can be accepted.
• comment – how comments are introduced when supported. Multiple introducers can be accepted within one file. By default we accept the Unix Shell (#) and INI file (;) comment introducers.
• section_operator – the set of characters accepted as section separator. By default we accept the INI file syntax (the [section] syntax.)

Note

If the filename represent an existing file, then the name is going to get canonicalized before it gets saved in the structure. Otherwise it gets saved as is.

Parameters

[in]	filename	A valid filename.
[in]	line_continue	One of the line_continuation_t values.
[in]	assignment_operator	A set of assignment operator flags.
[in]	comment	A set of comment flags.
[in]	section_operator	A set of section operator flags.

Definition at line 177 of file conf_file.cpp.

References initialize().

conf_file_setup() [2/2]

advgetopt::conf_file_setup::conf_file_setup	(	std::string const &	filename,
		conf_file_setup const &	original
	)

Definition at line 197 of file conf_file.cpp.

References initialize().

Member Function Documentation

get_assignment_operator()

assignment_operator_t advgetopt::conf_file_setup::get_assignment_operator

(

)

const

This function returns the set of flags describing the list of accepted operators one can use to do assignments.

Right now we support the follow:

• ASSIGNMENT_OPERATOR_EQUAL – the equal (=) character, like in most Unix configuration files and shell scripts.
• ASSIGNMENT_OPERATOR_COLON – the colon (:) character, like in email and HTTP headers.
• ASSIGNMENT_OPERATOR_SPACE – the space () character; this is less used, but many Unix configuration files still use this scheme.
• ASSIGNMENT_OPERATOR_EXTENDED – the += (append) and ?= (optional) operators; this is used to add to an existing parameter and to set a parameter only if not already set.

Returns

The set of accepted assignment operators.

See also

is_assignment_operator()

Definition at line 345 of file conf_file.cpp.

References f_assignment_operator.

Referenced by advgetopt::conf_file::is_assignment_operator(), advgetopt::conf_file::read_configuration(), and advgetopt::conf_file::save_configuration().

get_comment()

comment_t advgetopt::conf_file_setup::get_comment

(

)

const

Get the comment flags.

This function returns the comment flags. These describe which type of comments are supported in this configuration file.

Currently we support:

• COMMENT_INI – INI file like comments, these are introduced with a semi-colon (;) and end with a newline.
• COMMENT_SHELL – Unix shell like comments, these are introduced with a hash (#) and end with a newline.
• COMMENT_CPP – C++ like comments, these are introduced with two slashes (//) and end with a newline.

Right now we only support line comments. Configuration entries cannot include comments. A comment character can be preceeded by spaces and tabs.

Line continuation is taken in account with comments. So the following when the line continuation is set to Unix is one long comment:

# line continuation works with comments \
just like with any other line... because the \
continuation character and the newline characters \
just get removed before the get_line() function \
returns...

Returns

The comment flags.

See also

is_comment()

Definition at line 384 of file conf_file.cpp.

References f_comment.

Referenced by advgetopt::conf_file::is_comment(), and advgetopt::conf_file::read_configuration().

get_config_url()

std::string advgetopt::conf_file_setup::get_config_url

(

)

const

This function transforms the configuration file setup in a unique URL. This URL allows us to verify that two setup are the same so when attempting to reload the same configuration file, we can make sure you are attempting to do so with the same URL.

This is because trying to read the same file with, for example, line continuation set to Unix the first time and then set to MS-DOS the second time would not load the same thing is either line continuation was used.

Todo:

We should look into have a set_config_url() or have a constructor which accepts a URL.

Returns

The URL representing this setup.

Definition at line 452 of file conf_file.cpp.

References advgetopt::ASSIGNMENT_OPERATOR_COLON, advgetopt::ASSIGNMENT_OPERATOR_EQUAL, advgetopt::ASSIGNMENT_OPERATOR_EXTENDED, advgetopt::ASSIGNMENT_OPERATOR_SPACE, advgetopt::COMMENT_CPP, advgetopt::COMMENT_INI, advgetopt::COMMENT_SAVE, advgetopt::COMMENT_SHELL, f_assignment_operator, f_comment, f_filename, f_line_continuation, f_section_operator, f_url, advgetopt::line_continuation_fortran, advgetopt::line_continuation_msdos, advgetopt::line_continuation_rfc_822, advgetopt::line_continuation_semicolon, advgetopt::line_continuation_single_line, advgetopt::line_continuation_unix, advgetopt::SECTION_OPERATOR_BLOCK, advgetopt::SECTION_OPERATOR_C, advgetopt::SECTION_OPERATOR_CPP, and advgetopt::SECTION_OPERATOR_INI_FILE.

Referenced by advgetopt::conf_file::get_conf_file().

get_filename()

std::string const & advgetopt::conf_file_setup::get_filename

(

)

const

When creating a new conf_file_setup, you have to specify a filename. This function returns that filename after it was canonicalized by the constructor.

The canonicalization process computes the full path to the real file. If such does not exist then no filename is defined, so this function may return an empty string.

Returns

The canonicalized filename or the original filename if realpath() failed.

See also

get_original_filename()

Definition at line 286 of file conf_file.cpp.

References f_filename.

Referenced by advgetopt::conf_file::get_conf_file(), advgetopt::conf_file::read_configuration(), advgetopt::conf_file::save_configuration(), and advgetopt::conf_file::set_parameter().

get_line_continuation()

line_continuation_t advgetopt::conf_file_setup::get_line_continuation

(

)

const

This function returns the line continuation for this setup.

This parameter is not a set of flags. We only support one type of line continuation per file. Many continuations could be contradictory if used simultaneously.

The continuation setting is one of the following:

• line_continuation_t::single_line – no continuation support; any definition must be on one single line.
• line_continuation_t::rfc_822 – like email/HTTP, whitespace at the start of the next line means that the current line continues there; those whitespaces get removed from the value so if you want a space between two lines, make sure to finish the current line with a space.
• line_continuation_t::msdos – & at end of the line.
• line_continuation_t::unix – \ at end of the line.
• line_continuation_t::fortran – & at the start of the next line; there cannot be any spaces, the & has to be the very first character.
• line_continuation_t::semicolon – ; ends the line; when reading a line with this continuation mode, the reader stops only when it finds the ; or EOF (also if a comment is found.)

Returns

a line continuation mode.

Definition at line 318 of file conf_file.cpp.

References f_line_continuation.

Referenced by advgetopt::conf_file::get_line().

get_name_separator()

name_separator_t advgetopt::conf_file_setup::get_name_separator

(

)

const

A parameter name can include dashes or underscores. The advgetopt supports either one and internally, it saves the names with dashes. Most other tools, though will only expect one or the other, most likely underscores, which is the default here.

You can specify either one when building the conf_file_setup. At the moment, there is no option to keep the dashes and underscores as found in the input.

Returns

Whether to save the names with underscores or dashes.

Definition at line 608 of file conf_file.cpp.

References f_name_separator.

Referenced by advgetopt::conf_file::save_configuration().

get_original_filename()

std::string const & advgetopt::conf_file_setup::get_original_filename

(

)

const

When creating a new conf_file_setup, you have to specify a filename. This function returns that string exactly, without canonicalization.

Returns

The filename as specified at the time of construction.

See also

get_filename()

Definition at line 265 of file conf_file.cpp.

References f_original_filename.

get_section_operator()

section_operator_t advgetopt::conf_file_setup::get_section_operator

(

)

const

This function returns the flags representing which of the section operators are accepted.

We currently support the following types of sections:

• SECTION_OPERATOR_NONE – no sections are accepted.
• SECTION_OPERATOR_C – the period (.) is viewed as a section/name separator as when you access a variable member in a structure.
• SECTION_OPERATOR_CPP – the scope operator (::) is viewed as a section/name separator; if used at the very beginning, it is viewed as "global scope" and whatever other section is currently active is ignored.
• SECTION_OPERATOR_BLOCK – the configuration files can include opening ({) and closing (}) curvly brackets to group parameters together; a name must preceed the opening bracket, it represents the section name.
• SECTION_OPERATOR_INI_FILE – like in the MS-DOS .ini files, the configuration file can include square brackets to mark sections; this method limits the number of section names to one level.

Bug:

The INI file support does not verify that a section name does not itself include more sub-sections. For example, the following would be three section names:

[a::b::c]
var=123

Bug:

So in effect, the variable named var ends up in section a, sub-section b, and sub-sub-section c (or section a::b::c.) Before saving the results in the parameters, all section operators get transformed to the C++ scope (::) operator, which is why that operator used in any name ends up looking like a section separator.

Definition at line 428 of file conf_file.cpp.

References f_section_operator.

Referenced by advgetopt::conf_file::read_configuration(), and advgetopt::conf_file::set_parameter().

get_section_to_ignore()

std::string const & advgetopt::conf_file_setup::get_section_to_ignore

(

)

const

This function returns a reference to the name of the section to ignore.

For additional information, see the set_section_to_ignore() function.

Returns

The name of the section to ignore.

Definition at line 638 of file conf_file.cpp.

References f_section_to_ignore.

Referenced by advgetopt::conf_file::set_parameter().

initialize()

void advgetopt::conf_file_setup::initialize ( )

private

Definition at line 213 of file conf_file.cpp.

References f_filename, and f_original_filename.

Referenced by conf_file_setup(), and conf_file_setup().

is_valid()

bool advgetopt::conf_file_setup::is_valid

(

)

const

This function is used to check whether the conf_file_setup is valid or not. It is valid when everything is in order, which at this point means the filename is not empty.

All the other parameters are always viewed as being valid.

Warning

The is_valid() always returns true at this time. We always save the filename. I'm not totally sure why I wanted to not have a way to get a valid configuration file by viewing a non-existing file as the same as an empty file. Now that's what happens.

Returns

true if the conf_file_setup is considered valid.

Definition at line 250 of file conf_file.cpp.

References f_filename.

Referenced by advgetopt::getopt::parse_options_from_file().

set_section_to_ignore()

void advgetopt::conf_file_setup::set_section_to_ignore

(

std::string const &

section_name

)

If the number of sections is exactly 2 when only 1 should be used, then the first name is checked against this name. If equal, it gets removed.

This is done so fluid-settings files can be loaded and we do not have to duplicate the data (since that's bad practice).

Parameters

[in]

section_name

The name of the section to ignore.

Definition at line 624 of file conf_file.cpp.

References f_section_to_ignore.

Referenced by advgetopt::getopt::parse_options_from_file().

Member Data Documentation

f_assignment_operator

assignment_operator_t advgetopt::conf_file_setup::f_assignment_operator = ASSIGNMENT_OPERATOR_EQUAL

private

Definition at line 145 of file conf_file.h.

Referenced by get_assignment_operator(), and get_config_url().

f_comment

comment_t advgetopt::conf_file_setup::f_comment = COMMENT_INI | COMMENT_SHELL

private

Definition at line 146 of file conf_file.h.

Referenced by get_comment(), and get_config_url().

f_filename

std::string advgetopt::conf_file_setup::f_filename = std::string()

private

Definition at line 142 of file conf_file.h.

Referenced by get_config_url(), get_filename(), initialize(), and is_valid().

f_line_continuation

line_continuation_t advgetopt::conf_file_setup::f_line_continuation = line_continuation_t::line_continuation_unix

private

Definition at line 144 of file conf_file.h.

Referenced by get_config_url(), and get_line_continuation().

f_name_separator

name_separator_t advgetopt::conf_file_setup::f_name_separator = NAME_SEPARATOR_UNDERSCORES

private

Definition at line 149 of file conf_file.h.

Referenced by get_name_separator().

f_original_filename

std::string advgetopt::conf_file_setup::f_original_filename = std::string()

private

Definition at line 141 of file conf_file.h.

Referenced by get_original_filename(), and initialize().

f_section_operator

section_operator_t advgetopt::conf_file_setup::f_section_operator = SECTION_OPERATOR_INI_FILE

private

Definition at line 147 of file conf_file.h.

Referenced by get_config_url(), and get_section_operator().

f_section_to_ignore

std::string advgetopt::conf_file_setup::f_section_to_ignore = std::string()

private

Definition at line 143 of file conf_file.h.

Referenced by get_section_to_ignore(), and set_section_to_ignore().

f_url

std::string advgetopt::conf_file_setup::f_url = std::string()

mutableprivate

Definition at line 148 of file conf_file.h.

Referenced by get_config_url().

---

The documentation for this class was generated from the following files:

• /home/alexis/snapwebsites/snapcpp/contrib/advgetopt/advgetopt/conf_file.h
• /home/alexis/snapwebsites/snapcpp/contrib/advgetopt/advgetopt/conf_file.cpp