class mrpt::config::CConfigFile

Overview

This class allows loading and storing values and vectors of different types from “.ini” files easily.

The contents of the file will be modified by “write” operations in memory, and will be saved back to the file at the destructor, and only if at least one write operation has been applied.

Use base class CConfigFileBase ‘s methods read_{int,float,double,string,...}() and write() to actually read and write values.

See: Configuration file format in MRPT

#include <mrpt/config/CConfigFile.h>

class CConfigFile: public mrpt::config::CConfigFileBase
{
public:
    // structs

    struct Impl;

    // construction

    CConfigFile(const std::string& fileName);
    CConfigFile();

    // methods

    std::string read_string_first_word(
        const std::string& section,
        const std::string& name,
        const std::string& defaultValue,
        bool failIfNotFound = false
        ) const;

    template <class VECTOR_TYPE>
    void read_vector(
        const std::string& section,
        const std::string& name,
        const VECTOR_TYPE& defaultValue,
        VECTOR_TYPE& outValues,
        bool failIfNotFound = false
        ) const;

    template <class MATRIX_TYPE>
    void read_matrix(
        const std::string& section,
        const std::string& name,
        MATRIX_TYPE& outMatrix,
        const MATRIX_TYPE& defaultMatrix = MATRIX_TYPE(),
        bool failIfNotFound = false
        ) const;

    template <typename ENUMTYPE>
    ENUMTYPE read_enum(
        const std::string& section,
        const std::string& name,
        const ENUMTYPE& defaultValue,
        bool failIfNotFound = false
        ) const;

    void setFileName(const std::string& fil_path);
    void writeNow();
    void discardSavingChanges();
    std::string getAssociatedFile() const;
    virtual void getAllSections(std::vector<std::string>& sections) const;
    virtual void clear();
    virtual void getAllKeys(const std::string& section, std::vector<std::string>& keys) const;
    std::vector<std::string> sections() const;
    std::vector<std::string> keys(const std::string& section) const;
    bool sectionExists(const std::string& section_name) const;
    bool keyExists(const std::string& section, const std::string& key) const;
    void setContentFromYAML(const std::string& yaml_block);
    std::string getContentAsYAML() const;
};

Inherited Members

public:
    // methods

    virtual void getAllSections(std::vector<std::string>& sections) const = 0;
    virtual void getAllKeys(const std::string& section, std::vector<std::string>& keys) const = 0;
    virtual void clear() = 0;

Construction

CConfigFile(const std::string& fileName)

Constructor associating with a given configuration filename.

If the file exists, it loads and parses its contents; otherwise, it silently just start with an empty configuration file in memory. The file will be written upon destruction, or at any time using writeNow()

CConfigFile()

Constructor, does not open any file.

You should call “setFileName” before reading or writing or otherwise nothing will be read and write operations will be eventually lost. However, it’s perfectly right to use this object without an associated file, in which case it will behave as an “in-memory” file.

Methods

std::string read_string_first_word(
    const std::string& section,
    const std::string& name,
    const std::string& defaultValue,
    bool failIfNotFound = false
    ) const

Reads a configuration parameter of type “string”, and keeps only the first word (this can be used to eliminate possible comments at the end of the line)

template <class VECTOR_TYPE>
void read_vector(
    const std::string& section,
    const std::string& name,
    const VECTOR_TYPE& defaultValue,
    VECTOR_TYPE& outValues,
    bool failIfNotFound = false
    ) const

Reads a configuration parameter of type vector, stored in the file as a string: “[v1 v2 v3 … ]”, where spaces could also be commas.

Parameters:

std::exception

If the key name is not found and “failIfNotFound” is true. Otherwise the “defaultValue” is returned.

template <class MATRIX_TYPE>
void read_matrix(
    const std::string& section,
    const std::string& name,
    MATRIX_TYPE& outMatrix,
    const MATRIX_TYPE& defaultMatrix = MATRIX_TYPE(),
    bool failIfNotFound = false
    ) const

Reads a configuration parameter as a matrix written in a matlab-like format - for example: “[2 3 4 ; 7 8 9]”.

This template method can be instantiated for matrices of the types: int, long, unsinged int, unsigned long, float, double, long double

Parameters:

std::exception

If the key name is not found and “failIfNotFound” is true. Otherwise the “defaultValue” is returned.

template <typename ENUMTYPE>
ENUMTYPE read_enum(
    const std::string& section,
    const std::string& name,
    const ENUMTYPE& defaultValue,
    bool failIfNotFound = false
    ) const

Reads an “enum” value, where the value in the config file can be either a numerical value or the symbolic name, for example: In the code:

enum my_type_t { type_foo=0, type_bar };

In the config file:

   [section]
   type   = type_bar   // Use the symbolic name, or
   type   = 1          // use the numerical value (both lines will be
equivalent)

Which can be loaded with:

cfgfile.read_enum<my_type_t>("section","type", type_foo );

For an enum type to work with this template it is required that it defines a specialization of mrpt::typemeta::TEnumType

void setFileName(const std::string& fil_path)

Associate this object with the given file, reading its contents right now.

Upon destruction, the updated contents will be written to that file.

void writeNow()

Dumps the changes to the physical configuration file now, not waiting until destruction.

Parameters:

std::runtime_error

Upon error writing.

void discardSavingChanges()

Discard saving (current) changes to physical file upon destruction.

std::string getAssociatedFile() const

Returns the file currently open by this object.

virtual void getAllSections(std::vector<std::string>& sections) const

Returns a list with all the section names.

virtual void clear()

Empties the “config file”.

virtual void getAllKeys(
    const std::string& section,
    std::vector<std::string>& keys
    ) const

Returs a list with all the keys into a section.

std::vector<std::string> sections() const

Returns, by value, a list with all the section names.

std::vector<std::string> keys(const std::string& section) const

Returs, by value, a list with all the keys into a section.

bool sectionExists(const std::string& section_name) const

Checks if a given section exists (name is case insensitive)

See also:

keyExists()

bool keyExists(const std::string& section, const std::string& key) const

Checks if a given key exists inside a section (case insensitive)

See also:

sectionExists()

void setContentFromYAML(const std::string& yaml_block)

Changes the contents of the virtual “config file” from a text block containing a YAML configuration text.

Refer to unit test yaml2config_unittest.cpp for examples of use.

See also:

getContentAsYAML()

std::string getContentAsYAML() const

Returns a text block representing the contents of the config file in YAML format.

See also:

setContentFromYAML()