Extension Attributes

Extension attributes allow format crates to define custom #[facet(...)] attributes with compile-time validation and helpful error messages.

For the full guide on creating extension attributes, see Extend → Extension Attributes.

Quick reference

Using extension attributes

use facet::Facet;
use facet_kdl as kdl;

#[derive(Facet)]
struct Config {
    #[facet(kdl::child)]
    server: Server,

    #[facet(kdl::property)]
    name: String,
}

The namespace (kdl) comes from how you import the crate:

use facet_kdl as kdl;  // Enables kdl:: prefix
use facet_args as args;  // Enables args:: prefix

Available namespaces

Creating your own

Use define_attr_grammar! in your crate:

facet::define_attr_grammar! {
    ns "myformat";
    crate_path ::my_format_crate;

    pub enum Attr {
        /// Description shown in error messages
        MyAttribute,
        /// Attribute with a value
        WithValue(&'static str),
    }
}

Typos produce helpful compile errors:

error: unknown attribute `chld`, did you mean `child`?
       available attributes: child, children, property, argument

See Extend for the complete guide on declaring attributes and querying them at runtime.