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"); ``` 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.

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",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.

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",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.