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. Because this class manages a system resource (a file), it has been made 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. However, it is moveable.

Setup functions

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

config_file(cosnt std::string& filename, const int mode, const char separator = ' ')

Initializes and opens a new config_file. Will throw an scl::could_not_open_error if the file could not be opened.

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)
• separator - the character that separates the values in put vectors in the file.

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.

T get(const std::string& name, const 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(const std::string& name, const 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

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(const 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(const 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