Configuration Objects

Updated 1,196 Days AgoPublic

Actions

This document explains using examples how to use the basic features of the Configuraiton class. There are some things not covered here, such as the FunctionBinder support.

If you're already using Echo as a framework rather than just parts of it, you can use the Configuration class and pass in your FileSystem object from your application (via Application::GetFileSystem()). If you don't have a FileSystem object handy you can create a default one for the platform from the Platform namespace then load a config file. Keep in mind that you only need one FileSystem object around and it is advised to not create many FileSystem objects, especially not every time you need to access the file system.

shared_ptr<FileSystem> fileSystem = Platform::CreateDefaultFileSystem("");

Configuration configuration(fileSystem);
if(configuration.LoadFile("pathToFile"))
{
    //Get configuration parameters.
}else
{
    //File couldn't be loaded
}

The purpose of the FileSystem object may not seem obvious at first. But Echo is designed as a portable framework that can run on systems that may not have a standard file system accessible by the std::fstream classes.

When it comes to getting parameters, most basic Echo types (such as built in types and maths classes) will automatically convert from the string in the file.

// This will return the value from the configuration object or the default value (second parameter).
Vector3 parameterA = configuration.Get("parameter-a",Vector3(1,2,3));
bool isItOn = configuration.Get("it-is-on",false);
Scalar someScalar = configuration.Get("some-scalar",123.456f);
std::string name = configuration.Get("name","Echo");

If there isn't a reasonable default handy. You can use a different overload of Get() that takes the parameter to assign and returns a bool to indicate whether or not the value existed. Note there is still a default value passed in, but you can just use any value if you plan on not using the value anyway.

Vector3 parameterB;
if(!configuration.Get("parameter-b",parameterB,Vector3::ZERO))
{
    // Fail and complain to the user.
}

Multiple entries in the file do not overwrite the value and each can be read.

// Method 1
std::vector<Vector2> myPoints = configuration.GetAll("useful-point");
//Do something with myPoints

// Method 2
Size numberOfPoints = configuration.GetNumberOfOptionsNamed("useful-point");
for(Size i=0; i<numberOfPoints; ++i)
{
    Vector2 aPoint = configuration.GetAtIndex("useful-point",i);
    // Do something with the point
}

There is only one reserved key for configuration files at the moment and that is include, which allows you to include other configuration files as follows:

include=path/to/my/other/file/MoreSettings.config

The path can be relative to the parent config file.

Parsing

You can use substitution when accessing options as strings. For example:

description=Deliciously Portable
name=Echo
title=$name - $description

Would result in title as Echo - Deliciously Portable when acquired as a string.

Similarly there is basic calculation support included using the built in Parser::CalculatorWithVariables. The result should end up as a value that can be converted from a double. For example:

sum=1.21 + 2.32
part.cost=10
number.of.parts=3
total.cost=part.cost * number.of.parts

Scalar sum = Get("sum",Scalar(0));
Scalar totalCost = Get("total.cost",Scalar(0));

Numerical operators available: + - * / %