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("image-pipeline.parameter-a",Vector3(1,2,3)); bool isItOn = configuration.Get("image-pipeline.it-is-on",false); Scalar someScalar = configuration.Get("image-pipeline.some-scalar",123.456f); std::string name = configuration.Get("image-pipeline.name","Hamish"); ``` 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("image-pipeline.useful-point"); //Do something with myPoints // Method 2 Size numberOfPoints = configuration.GetNumberOfOptionsNamed("image-pipeline.useful-point"); for(Size i=0; i<numberOfPoints; ++i) { Vector2 aPoint = configuration.GetAtIndex("image-pipeline.useful-point",i); // Do something with the point } ```

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: ``` 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:** `+` `-` `*` `/` `%`

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("image-pipeline.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; bool isItOn = if(!configuration.Get("image-pipeline.it-is-on",false);parameter-b",parameterB,Vector3::ZERO)) Scalar someScalar = configuration.Get("image-pipeline.some-scalar",123.456f);{ // Fail and complain to the user. std::string name = configuration.Get("image-pipeline.name","Hamish");} ``` 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("image-pipeline.useful-point"); //Do something with myPoints // Method 2 Size numberOfPoints = configuration.GetNumberOfOptionsNamed("image-pipeline.useful-point"); for(Size i=0; i<numberOfPoints; ++i) { Vector2 aPoint = configuration.GetAtIndex("image-pipeline.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:** `+` `-` `*` `/` `%`