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.
```
lang=c++
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.
```
lang=c++
// 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.
```
lang=c++
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.
```
lang=c++
// 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:
```
name=Echo
description=Deliciously Portable
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
```
```
Scalar sum = Get("sum",Scalar(0));
```