[][src]Crate config_struct

This crate is a library for generating structs and enums based on a config file at build time. It is intended for use in a build.rs file so should be included in your [build-dependencies].

[build-dependencies.config_struct]
version = "~0.4.0"
features = ["toml-parsing"]

By default, config_struct is markup-language-agnostic, so include the relevant feature for whatever language your config file is written in. Choices are:

  1. json-parsing
  2. ron-parsing
  3. toml-parsing
  4. yaml-parsing

Only toml-parsing is included by default, so be sure to specify the features you need in your Cargo.toml file.

Examples

Structs

// build.rs
use config_struct::{Error, StructOptions};

fn main() -> Result<(), Error> {
    config_struct::create_struct(
        "config.toml",
        "src/config.rs",
        &StructOptions::default())
}

The above build script will take the following config.toml file and generate a config.rs like the following:

# config.toml
name = "Application"
version = 5
features = [
    "one",
    "two",
    "three"
]
// config.rs
// ...
use std::borrow::Cow;

#[derive(Debug, Clone)]
#[allow(non_camel_case_types)]
pub struct Config {
    pub features: Cow<'static, [Cow<'static, str>]>,
    pub name: Cow<'static, str>,
    pub version: i64,
}

pub const CONFIG: Config = Config {
    features: Cow::Borrowed(&[Cow::Borrowed("one"), Cow::Borrowed("two"), Cow::Borrowed("three")]),
    name: Cow::Borrowed("Application"),
    version: 5,
};

Strings and arrays are represented by Cow types, which allows the entire Config struct to be either heap allocated at runtime, or a compile time constant, as shown above.

Enums

// build.rs
use config_struct::{Error, EnumOptions};

fn main() -> Result<(), Error> {
    config_struct::create_enum(
        "items.yaml",
        "src/items.rs",
        &EnumOptions::default())
}

The above build script will take the following items.yaml file and generate a (not-formatted) items.rs like the following:

# items.yaml
ItemOne:
    - data
ItemTwo:
    - more
    - data
// items.rs
// ...
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Key {
    ItemOne,
    ItemTwo,
}
impl Key {
    pub const ALL: &'static [Key] = &[Key::ItemOne, Key::ItemTwo];
}
impl Default for Key {
    fn default() -> Self {
        Self::ItemOne
    }
}
impl std::fmt::Display for Key {
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(f, "{:?}", self)
    }
}
impl std::str::FromStr for Key {
    type Err = ();
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        const STRINGS: &'static [&'static str] = &["ItemOne", "ItemTwo"];
        for (index, &key) in STRINGS.iter().enumerate() {
            if key == s {
                return Ok(Key::ALL[index]);
            }
        }
        Err(())
    }
}

As you can see, this provides more functionality out-of-the-box - most of which could be disabled in the EnumOptions. The intended purpose of this is to have a small efficient type to use as a key into the data stored in the initial config file.

Structs

EnumOptions

Options for configuring the generation of a struct.

StructOptions

Options for configuring the generation of a struct.

Enums

DynamicLoading

When to perform dynamic loading from the config file itself.

Error

An error type for errors while generating config struct modules.

FloatSize

Represents a floating-point type.

Format

Represents an input markup format for a config file.

GenerationError

An error occurring during code generation.

IntSize

Represents an integer type.

OptionsError

An error type for when a StructOptions value failed validation.

SerdeSupport

Options for serde support.

Functions

create_enum

Generate a Rust module containing an enum definition based on a given config file containing a map-like structure. The variants of the enum are based on the keys of the map.

create_enum_from_source

Generate a Rust module containing an enum definition based on a config string containing a map-like structure. The variants of the enum are based on the keys of the map.

create_struct

Generate a Rust module containing struct definitions based on a given config file.

create_struct_from_source

Generate a Rust module containing struct definitions from a config string in a format specified by the provided options.

generate_enum

Generate Rust source code defining an enum based on a map-like config file.

generate_enum_from_source

Generate Rust source code defining an enum from a config string containing a map-like structure. The variants of the enum are based on the keys of the map.

generate_struct

Generate Rust source code defining structs based on a config file.

generate_struct_from_source

Generate Rust source code defining structs from a config string in a format specified in the provided options.