Derive Macro config_it::Template

source · 
#[derive(Template)]
{
    // Attributes available to this derive:
    #[config_it]
    #[config]
    #[non_config_default_expr]
}
Expand description

Primary macro for defining configuration group template.

Usage

ⓘ
#[derive(config_it::Template, Clone)]
struct MyConfig {
    /// Documentation comments are retrieved and used as descriptions in the editor.
    #[config(default = 154)]
    pub any_number: i32,

    #[non_config_default_expr = r#"1.try_into().unwrap()"#]
    pub non_config_number: std::num::NonZeroUsize,

    pub non_config_boolean: bool,
}

let storage = config_it::create_storage();
let mut config = storage.find_or_create::<MyConfig>(["my", "config", "path"]).unwrap();

// Initial update always reports dirty.
assert_eq!(config.update(), true);
assert_eq!(config.consume_update(&config.any_number), true);
assert_eq!(config.consume_update(&config.non_config_number), true);
assert_eq!(config.consume_update(&config.non_config_boolean), true);

Attributes

Attributes are encapsulated within #[config(...)] or #[config_it(...)].

  • alias = "<name>": Assign an alias to the field.

  • default = <expr> or default_expr = "<expr>": Define a default value for the field.

  • admin | admin_write | admin_read: Restrict access to the field for non-admin users.

  • min = <expr>, max = <expr>, one_of = [<expr>...]: Apply constraints to the field.

  • validate_with = "<function_name>": Specify a validation function for the field with the signature fn(&mut T) -> Result<Validation, impl Into<Cow<'static, str>>>.

  • readonly | writeonly: Designate an element as read-only or write-only.

  • secret: Flag an element as confidential (e.g., passwords). The value will be archived as a encrypted base64 string, which is becomes readable when imported back by storage.

  • env = "<literal>" or env_once = "<literal>": Set the default value from an environment variable.

  • transient | no_export | no_import: Prevent field export/import.

  • editor = <ident>: Define an editor hint for the field. See config_it::shared::meta::MetadataEditorHint

    • e.g. Specify expression as editor = ColorRgba255, editor = Code("rust".into()), etc.

  • hidden or hidden_non_admin: Make a field invisible in the editor or only to non-admin users, respectively.

Interacting with non-config-it Types

For non-configuration types that lack a Default trait, the #[non_config_default_expr = "<expr>"] attribute can be used to specify default values.