aldrin-macros 0.10.0

Aldrin macros.
Documentation

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

  • [Serialize]
  • [Deserialize]
  • [Introspectable]
  • [SerializeKey]
  • [DeserializeKey]
  • [KeyTypeOf]
  • [AsSerializeArg]

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

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.

# use aldrin_core::{Deserialize, Serialize};
#[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.

# use aldrin_core::Introspectable;
#[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.

# use aldrin_core::{Deserialize, Introspectable, Serialize};
#[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
}

# use aldrin_core::{Deserialize, Introspectable, Serialize};
#[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.

# use aldrin_core::{Deserialize, Serialize};
#[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.