#static #config-toml #constant #toml

no-std build toml_const

Compile-time constants from TOML

4 releases (2 stable)

new 1.0.1 Apr 18, 2025
1.0.0 Apr 16, 2025
0.1.1 Nov 28, 2023
0.1.0 Nov 27, 2023

#227 in Build Utils

Download history 1/week @ 2025-02-28 102/week @ 2025-04-11

102 downloads per month
Used in toml_const_cli

MIT license

11KB
151 lines

toml_const

TOML compile-time constants

no std crate docs build status

Getting started

use toml_const::{toml_const, toml_const_ws};

// workspace root
// ├── example.toml
// ├── toml_const       <---- you are here
// │   ├── Cargo.toml
// │   └── src
// └── toml_const_macros
//     ├── Cargo.toml
//     └── src

// include a TOML file in your project relative to your manifest directory
toml_const! {
    pub const EXAMPLE_TOML: "../example.toml";
    // multiple definitions are supported
    static CARGO_TOML: "Cargo.toml";
}

// include a file relative to your workspace root
toml_const_ws! {static EXAMPLE_TOML_WS: "example.toml";}

// table keys are capitalized struct fields
const TITLE: &str = EXAMPLE_TOML.TITLE;
assert_eq!(EXAMPLE_TOML.TITLE, EXAMPLE_TOML_WS.TITLE);

Table substitution

File substitution is supported. The first path that exists and satisfies the following conditions will be used. These conditions are, in order of precedence:

  • if a substitute path has the use keyword prefixed
  • iif a toml file contains use = true at the root level

Multiple substitute files can be specified in the macro expression. The first file containing a use = true key will be merged into the parent file.

These files may contain secrets or other sensitive information that you don't want to check into version control.

use toml_const::toml_const;

toml_const! {
    // example.toml is the template/parent file (must exist)
    pub static EXAMPLE_TOML: "../example.toml" {
        // if Cargo.toml exists, it will be substituted
        use "../Cargo.toml";
        // if Cargo.toml does not exist and example.toml contains
        // `use = true`, it will be substituted
        "../example.toml";
        // files that do not exist are ignored
        "non_existent.toml";
        // .. and so on
    }
}

Limitations

This library does not support the full TOML specification.

It will fail to:

  • generate arrays with distinct types (arrays containing different types, arrays of tables with different keys)
  • create a struct from a table with a blank key "" = true

It will modify:

  • table keys that begin with numbers
  • table keys that contain invalid characters for identifiers

TOML data types

All TOML data types are supported. Datetime related structs are re-exported from toml.

data type rust type
boolean bool
integer i64
float f64
string &'static str
date toml::value::Datetime
array toml_const::Array<T>
table auto-generated struct

Dependencies

~0.5–1MB
~23K SLoC