scl::config_file Documentation

scl::config_file

This page provides documentation for the scl::config_file class of SCL. This is the primary class for the library and serves as an interface to a configuration file. To avoid memory leaks, this class is currently non-copyable. That means that you can't compose a new config_file from another one. It also means that you can only pass a config_file to a function as a reference.

Setup functions

Functions necessary to begin writing or reading to/from a file and to clean up afterward.

config_file(std::string filename, int mode)

Initializes and opens a new config_file.

Arguments:

• filename - the name of the file to read or write to/from
• mode - the mode to open the file in (either config_file::READ or config_file::WRITE)

bool is_open()

Check if the file is open. Note that this function may return false if the file does not already exist, so checking is not necessary in config_file::WRITE mode. Returns true if the file is open, and false if it is not.

void close()

Close the handle to the file, and clear out the data buffer. This method is called in the destructor for this class, so calling it isn't strictly necessary unless you need/want to free memory before the object goes out of scope.

Reading Functions

Functions that can only be used in config_file::READmode.

bool load()

Attempts to load the data from the file into the internal buffer for access. Must be run before using any of the get_* functions. Returns true if the data was loaded successfully and false if it was not.

T get(std::string name, T def = {})

Generic function to retrieve a value from the data buffer. You must specify the type to retrieve in the template (like this file.get<int>("blah blah")). Please note that the default value is initialized using braced initialization. If you are trying to get a custom class with a constructor that accepts an std::initializer_list, this may be problematic. Therefore, it is highly recommended that you pass a value for def when using a custom class with SCL. Returns the value under name from the buffer if it can be found, and def if it could not.

Arguments:

• name - the name of the value to retrieve
• def - the value to return if name is not in the buffer, defaults to the default initialization (T var ={};). For most primitive types, this is some form of 0. For most classes, this is the default constructor(ex: std::string s;).

std::vector<T> gets(std::string name, vector<T> def = {})

Generic function to retrieve a series of values from the data buffer. You must specify the type to retrieve in the template arguments (like this file.gets<char>("blah blah")). Returns a vector of the series of values if they could be found, and def if they could not.

Arguments:

• name - the name of the series of values to retrieve
• def - the vector to return if name is not in the buffer, defaults to an empty vector

Note: The remaining read functions are DEPRECATED and subject to removal in a future version of SCL.

bool get_bool(std::string name, bool def = false)

Retrieve a boolean value from the data buffer. Returns the value in the buffer if it could be retrieved, and def if it could not.

Arguments:

• name - the name of the boolean to retrieve
• def - the value to return if name is not in the buffer, defaults to false

vector<bool> get_bools(std::string name, std::vector<bool> def = {})

Retrieve a series of boolean values from the data buffer. Returns a vector of values if they could be retrieved, and def if it could not.

Arguments:

• name - the name of the vector of booleans to retrieve
• def - the value to return if name is not in the buffer. Defaults to an empty vector

int get_int(std::string name, int def = 0)

Retrieve an integer value from the data buffer. Returns the value in the buffer if it could be retrieved, and def if it could not.

Arguments:

• name - the name of the integer to retrieve
• def - the value to return if name is not in the buffer, defaults to 0

vector<int> get_ints(std::string name, std::vector<int> def = {})

Retrieve a series of integer values from the data buffer. Returns a vector of values if they could be retrieved, and def if it could not.

Arguments:

• name - the name of the vector of integers to retrieve
• def - the value to return if name is not in the buffer. Defaults to an empty vector

float get_float(std::string name, float def = 0.0f)

Retrieve a floating point value from the data buffer. Returns the value in the buffer if it could be retrieved, and def if it could not.

Arguments:

• name - the name of the float to retrieve
• def - the value to return if name is not in the buffer, defaults to 0.0f

vector<float> get_floats(std::string name, std::vector<float> def = {})

Retrieve a series of float values from the data buffer. Returns a vector of values if they could be retrieved, and def if it could not.

Arguments:

• name - the name of the vector of floats to retrieve
• def - the value to return if name is not in the buffer. Defaults to an empty vector

double get_double(std::string name, double def = 0.0)

Retrieve a double value from the data buffer. Returns the value in the buffer if it could be retrieved, and def if it could not.

Arguments:

• name - the name of the double to retrieve
• def - the value to return if name is not in the buffer, defaults to 0.0

vector<double> get_doubles(std::string name, std::vector<double> def = {})

Retrieve a series of double values from the data buffer. Returns a vector of values if they could be retrieved, and def if it could not.

Arguments:

• name - the name of the vector of doubles to retrieve
• def - the value to return if name is not in the buffer. Defaults to an empty vector

char get_char(std::string name, char def = ' ')

Retrieve a single character value from the data buffer. Returns the value in the buffer if it could be retrieved, and def if it could not.

Arguments:

• name - the name of the character to retrieve
• def - the value to return if name is not in the buffer, defaults to (a single space)

vector<char> get_chars(std::string name, std::vector<char> def = {})

Retrieve a series of characters from the data buffer. Returns a vector of values if they could be retrieved, and def if it could not.

Arguments:

• name - the name of the vector of characters to retrieve
• def - the value to return if name is not in the buffer. Defaults to an empty vector

std::string get_string(std::string name, std::string def = "")

Retrieve a string value from the data buffer. Returns the value in the buffer if it could be retrieved, and def if it could not.

Arguments:

• name - the name of the string to retrieve
• def - the value to return if name is not in the buffer, defaults to "" (an empty string)

vector<std::string> get_strings(std::string name, std::vector<std::string> def = {})

Retrieve a series of string values from the data buffer. It is important to note that strings containing spaces will be split up into component words. This is because spaces are used by the library as seperators between values when reading/writing vectors. Returns a vector of values if they could be retrieved, and def if it could not.

Arguments:

• name - the name of the vector of strings to retrieve
• def - the value to return if name is not in the buffer. Defaults to an empty vector

Writing Functions

Functions that can only be used in config_file::WRITE mode

bool write_changes()

Attempts to write data put into the buffer to filename. Returns true if writing was successful, and false, if it was not.

bool put(std::string name, const T& val)

Template function that puts a value into the data buffer (which will be written to the file when write_changes is called). If a value under name already exists in the buffer, it will be overwritten. Accepts any value which can be converted by an std::stringstream into an std::string. Returns true if insertion was successful, and false if it was not.

Arguements:

• name - the name of the value to put
• val - the value to insert into the data buffer under name

bool put(const std::pair<std::string, T>& val)

Template function to add a value to the data buffer (which is written to the file when write_changes is called) using an std::pair. The first value of the pair will be the name of the value, and the second will be the value to insert. If the name already exists in the buffer Returns true if insertion was successful, and false if it was not.

Arguments:

• val - the pair to insert into the data buffer

bool put(std::string name, const vector<T>& val)

Template function that puts a vector of values into the data buffer (which is written to the file when write_changes is called). Accepts any series of values which can be converted by an std::stringstream int an std::string. Returns true if insertion was successful, and false if it was not.

Arguements:

• name - the name of the value to put
• val - the series of values to put

bool put(const std::pair<std::string, vector<T>>& val)

Template function to add a series of values to the data buffer (which is written to the file when write_changes is called) using an std::pair. The first value of the pair will be the name of the value, and the second will be the vector of values to insert. Returns true if insertion was successful, and false if it was not.

Arguments:

• val - the pair to insert into the data buffer

bool put(const comment& c)

Puts a comment (#blah blah blah) into the data buffer (which is written to the file when write_changes is called). The value of the text field of the comment will be inserted. Returns true if insertion was successful, and false if it was not.

Arguments:

• c - the comment object to insert

bool put(const empty_lines& lines)

Insert a number of empty lines into the data buffer (which is written to the file when write_changes is called). Used for readability purposes. The number of lines inserted is equal to the value of the num_lines field in the empty_lines object. Returns true if insertion was successful and false if it was not.

Arguments:

• lines - the empty_lines object to insert