Crate aldrin_macros

Source

Expand description

§Aldrin macros

The macros in this crate are not generally meant to be used directly, but through re-exports in other crates.

§Procedural macros

generate: Re-exported in crate aldrin
service: Re-exported in crate aldrin

§Derive macros

All derive macros are re-exported in both aldrin and aldrin-core.

§Attributes

All derive macros support various attributes and some apply to multiple macros.

§Container attributes

§`crate`

Applies to: all derive macros

The attribute #[aldrin(crate = "...") can be used to override the path of the aldrin_core crate. This is useful when aldrin_core is not a direct dependency, but only reexported somewhere. The default value depends on from where the macro is invoked, it’s either ::aldrin::core or ::aldrin_core.

mod my_reexports {
    pub use aldrin_core as my_aldrin_core;
}

#[derive(
    my_reexports::my_aldrin_core::Serialize,
    my_reexports::my_aldrin_core::Deserialize,
)]
#[aldrin(crate = "my_reexports::my_aldrin_core")]
struct Person {
    name: String,
}

§`{ser,de,intro,ser_key,de_key,key_ty}_bounds`

Applies to:

ser_bounds: Serialize, AsSerializeArg
de_bounds: Deserialize
intro_bounds: Introspectable
ser_key_bounds: SerializeKey
de_key_bounds: DeserializeKey
key_ty_bounds: KeyTypeOf

These attributes specify the generic bounds added to where clauses The default is to add T: Trait bounds for each type parameter T and the respective trait.

The values of these attributes must be a string of comma-separated bounds, just like they would appear in a where clause.

#[derive(Serialize, Deserialize)]
#[aldrin(ser_bounds = "T: aldrin::core::Serialize")]
#[aldrin(de_bounds = "T: aldrin::core::Deserialize")]
struct Person<T> {
    pets: Vec<T>,
}

§`schema`

Applies to: Introspectable

Deriving Introspectable requires specifying a schema name. It is an error if this attribute is missing.

#[derive(Introspectable)]
#[aldrin(schema = "contacts")]
struct Person {
    name: String,
}

§Field and variant attributes

§`id`

Applies to: Serialize, Deserialize and Introspectable

Use #[aldrin(id = ...)] to override the automatically defined id for a field or variant.

Default ids start at 0 for the first field or variant and then increment by 1 for each subsequent field or variant.

#[derive(Serialize, Deserialize, Introspectable)]
#[aldrin(schema = "family_tree")]
struct Person {
    age: u8, // id = 0

    #[aldrin(id = 5)]
    name: String, // id = 5

    siblings: Vec<Self>, // id = 6
}

#[derive(Serialize, Deserialize, Introspectable)]
#[aldrin(schema = "pets")]
enum Pet {
    Dog, // id = 0

    #[aldrin(id = 5)]
    Cat, // id = 5

    Alpaca, // id = 6
}

§`optional`

Applies to: Serialize, Deserialize and Introspectable

Use #[aldrin(optional)] to mark fields of a struct as optional. They must be of an Option<T> type.

Optional fields are not serialized if None and are allowed to be missing when deserializing a value.

#[derive(Serialize, Deserialize)]
struct MyStruct {
    required_field_1: i32,
    required_field_2: Option<i32>,

    #[aldrin(optional)]
    optional_field: Option<i32>,
}

Both fields required_field_1 and required_field_2 will always be serialized and deserialization will fail if either is missing. Serialization of optional_field is skipped if it is None. If it’s missing during deserialization, then it will be set to None.

§`fallback`

Applies to: Serialize, Deserialize and Introspectable

The last field of a struct and the last variant of an enum can optionally be marked with #[aldrin(fallback)]. This will enable successful serialization and deserialization of unknown fields and variants. For structs, the field type must be aldrin_core::UnknownFields. For enums, the variant must have a single field of type aldrin_core::UnknownVariant.

This attribute cannot be combined with #[aldrin(optional)].

Example of a struct with a fallback field:

#[derive(Serialize, Deserialize, Introspectable)]
#[aldrin(schema = "contacts")]
struct Person {
    name: String,
    age: u8,

    #[aldrin(fallback)]
    unknown_fields: UnknownFields,
}

Example of an enum with a fallback variant:

#[derive(Serialize, Deserialize, Introspectable)]
#[aldrin(schema = "zoo")]
enum AnimalType {
    Alpaca,
    Pig,

    #[aldrin(fallback)]
    Unkown(UnknownVariant),
}

Macros§

generate: Generates code from an Aldrin schema.
service: Defines a service and proxy type.

Derive Macros§

AsSerializeArg: Derive macro for the AsSerializeArg trait.
Deserialize: Derive macro for the Deserialize trait.
DeserializeKey: Derive macro for the DeserializeKey trait.
Introspectable: Derive macro for the Introspectable trait.
KeyTypeOf: Derive macro for the KeyTypeOf trait.
Serialize: Derive macro for the Serialize trait.
SerializeKey: Derive macro for the SerializeKey trait.