Crate amethyst_config

Loading configuration (.yaml/.yml) files into a structure for easy usage

Basic usage:

#[macro_use]
extern crate amethyst;

use amethyst::config::Element;
use std::path::Path;

config!(struct Config {
    pub amount: i32 = 50,
});

fn main() {
    let config = Config::default();
    assert_eq!(config.amount, 50);
}

Config is the name of the rust struct that will be generated by the macro. It can be anything as long as it would be a valid struct in its context. e.g. no other structs by the same name.

The inner fields of Config can be summed up as:

name: type = default,

The field name will be looked up when attempting to load from a .yml/.yaml file. If it is found then the value will be converted from a yaml type to a rust type and assigned to the field.

In the case that the value is either the wrong type from the field's or simply cannot be found in the file, the field will be defaulted to default.

In addition to basic types, any struct created through the config! macro will automatically implement the Element trait. Meaning you can nest configuration structs inside of eachother as such:

config!(struct NestedConfig {
    pub some_field: [i64; 3] = [1, 2, 3],
});

config!(struct Config {
    pub nested: NestedConfig = NestedConfig::default(),
});

External .yml/.yaml files

In the event that a config is getting too long, you can define it in the .yml/.yaml file as "extern"

example:

display: "extern"

This works similarly to rust's module system. It will first search for "\display\config.yml" in the current context. If it cannot find it, then it will look for "\display.yml". If it cannot find either of these, then the value will be defaulted in addition to display being overwritten if you called write_file().

Enums

When config! is used on an enum type, it automatically implements the Element trait. However, it does not provide possibilities for data holding enums, only a simple options list enum.

config!(enum EnumName {
    Option1,
    Option2,
});

config!(struct Config {
    pub field: EnumName = EnumName::Option2,
});

fn main() {
    let config = Config::default();
    assert_eq!(config.field, EnumName::Option2);
}

Documentation/Commenting

Normally when constructing a config you would want to have a small description as to what the fields will be used for. And possibly defaults.

config!(
    struct Config {
        /// Width and height of the window on initialization. Defaults to 1024x768.
        pub dimensions: [u16; 2] = [1024, 768],
    }
);

If the macro has problems expanding, then you may want to check whether you have the documentation on the line before the field and that you have te pub identifier before the field name.

Macros

config!

Automatically generates a struct/enums for loading in yaml files.

Structs

Config
ConfigMeta	Metadata for a configuration structure
DisplayConfig
LoggingConfig

Enums

ConfigError	Configuration error
Yaml	A YAML node is stored as this Yaml enumeration, which provides an easy way to access your YAML document.

Traits

Element

Trait for fields inside of a configuration struct.

Functions

to_string

Converts a Yaml object into a .yml/.yaml format