Crate amethyst_config [−] [src]
Loads YAML configuration files (.yaml/.yml) into a structure for easy usage.
Basic usage:
#[macro_use] extern crate amethyst_config; use amethyst_config::Element; use std::path::Path; config! { struct MyConfig { pub amount: i32 = 50, } } fn main() { let config = MyConfig::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.
If a field is missing from the config file or has a value of a wrong type,
the Rust field will fall back to the default
value.
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 each other like so:
config! { struct NestedConfig { pub some_field: [i64; 3] = [1, 2, 3], } } config! { struct Config { pub nested: NestedConfig = NestedConfig::default(), } }
External YAML files
In the event that a config file is getting too long, you may define it in the YAML file as an "extern" field. For 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 simple options list enums.
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 and commenting
Normally when constructing a config, you might add a small description as to what the fields will be used for and possibly their default values, if they have any.
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 the
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 |
Traits
Element |
Trait for fields inside of a configuration struct. |
Functions
to_string |
Converts a Yaml object into a .yml/.yaml format |