A Rust procedural macro attribute parser.
This crate offers attribute parsing closer to the design of attributes in C#. It has an interface similar to serde. Attributes are written as plain Rust structs or enums, and then parsers for them are generated automatically. They can contain arbitrary expressions and can inherit from other attributes using a flattening mechanism.
The parsers in this crate directly parse token streams using
syn. As a result, most built-in Rust types and syn
types can be used directly as fields.
Functionality in this crate is centered around three traits, and their respective derive macros:
[ExtractAttributes]
Extracts attributes from an object containing a list of syn::Attribute, and parses them
into a Rust type. Should be implemented for top-level structures that will be parsed directly
out of a set of matching attributes.
[ParseAttributes]
Parses a Rust type from any object containing a list of syn::Attribute. Should be used if
the set of matching attributes can potentially be shared between this type and other types.
[ParseMetaItem]
Parses a Rust type from a syn::parse::ParseStream. Should be implemented for
any types that can be nested inside an attribute.
Basic usage of this crate requires simply deriving one (or a few) of these traits, and then
calling [extract_attributes] or [parse_attributes]. For more advanced functionality,
several #[deluxe(...)] attributes are supported on structs, enums, variants
and fields. See the examples below, and the documentation for each derive macro
for a complete description of the supported attributes.
A list of field types supported by default can be seen in the list of provided
ParseMetaItem
implementations.
For more complex usage, manual implementations of these traits can be provided.
See the documentation on the individual traits for more details on how to
manually implement your own parsers.
Deluxe takes inspiration from the darling crate, but
offers a few enhancements over it. Darling is built around pre-parsed
syn::Meta objects, and therefore is restricted to the meta
syntax.
Deluxe parses its types directly from TokenStream objects in the attributes
and so is able to use any syntax that parses as a valid token tree. Deluxe also
does not provide extra traits for parsing special syn objects like
DeriveInput and Field. Instead, Deluxe uses a generic trait to parse from
any type containing a Vec<syn::Attribute>.
Inside your procedural macro, the [ExtractAttributes] trait can be derived to
extract a struct from a named attribute:
```rust
my_desc attributesstruct MyDescription { name: String, version: String, }
pub fn derivemydescription(item: TokenStream) -> TokenStream {
let mut input = syn::parse::
// Extract a description, modifying `input.attrs` to remove the matched attributes.
let MyDescription { name, version } = match deluxe::extract_attributes(&mut input) {
Ok(desc) => desc,
Err(e) => return e.into_compile_error().into()
};
let ident = &input.ident;
let (impl_generics, type_generics, where_clause) = input.generics.split_for_impl();
let tokens = quote::quote! {
impl #impl_generics #ident #type_generics #where_clause {
fn my_desc() -> &'static str {
concat!("Name: ", #name, ", Version: ", #version)
}
}
};
tokens.into()
} ```
Then, try adding the attribute in some code that uses your macro:
```rust
struct Hello(String);
let hello = Hello("Moon".into()); asserteq!(hello.mydesc(), "Name: hello world, Version: 0.2"); ```
The attributes alias, default, rename, and skip are supported, and
behave the same as in Serde. The append attribute can be used
on Vec fields to aggregate all duplicates of a key. The rest attribute can
be used to do custom processing on any unknown keys.
```rust
struct MyObject {
// can be specified with key id or object_id
#[deluxe(alias = object_id)]
id: u64,
// field is optional, defaults to `Default::default` if not present
#[deluxe(default)]
count: u64,
// defaults to "Empty" if not present
#[deluxe(default = String::from("Empty"))]
contents: String,
// can be specified only with key `name`
#[deluxe(rename = name)]
s: String,
// skipped during parsing entirely
#[deluxe(skip)]
internal_flag: bool,
// appends any extra fields with the key `expr` to the Vec
#[deluxe(append, rename = expr)]
exprs: Vec<syn::Expr>,
// adds any unknown keys to the hash map
#[deluxe(rest)]
rest: std::collections::HashMap<syn::Path, syn::Expr>,
} ```
```rust // omitted fields will be set to defaults
struct FirstObject;
// expr can be specified multiple times because of the append attribute
struct SecondObject;
// unknown and extra will be stored in the rest hashmap
struct ThirdObject; ```
The flatten attribute can be used to parse keys from one structure inside another:
```rust
struct A { id: u64, }
struct B { #[deluxe(flatten)] a: A, name: String, } ```
Then, fields from both A and B can be used when deriving B:
```rust
struct Object; ```
Deluxe also supports parsing into data structures with unnamed fields.
```rust
struct MyTuple(u64, String);
struct MyIdents {
id: u64,
names: (String, String),
idents: Vec
The standard attribute syntax with parenthesis can be used when specifying a
Vec type. The alternative syntax key = [...] can also be used to have an
appearance similar to an array literal.
```rust
struct Object;
struct ABC;
// idents contains same values as above
struct ABC2; ```
Attributes in C# can support positional arguments first with the named
arguments afterwards. This style can be emulated by using a tuple struct with a
normal struct flattened at the end. Placing #[deluxe(default)] on the struct
behaves the same as Serde, by filling in all fields with values from Default,
allowing every named argument to be optional.
```rust
struct Flags { native: bool, }
struct A(u64, String, #[deluxe(flatten)] Flags); ```
```rust
struct Object;
struct NativeObject; ```
Enums are supported by using the variant name as a single key, in snake-case. Variants can be renamed, aliased and skipped in the same way as fields.
```rust
enum MyEnum { A, B, C, #[deluxe(alias = d)] AnotherOne, #[deluxe(rename = e)] AnotherTwo, #[deluxe(skip)] SkipMe } ```
```rust
struct ObjectB;
struct ObjectD; ```
Enums with struct and tuple variants are also supported. The data inside is used as arguments to the attribute. All field attributes from structs are also supported inside variants.
Additionally, enum variants with named fields can be flattened. The behavior of
a flattened variant is similar to Serde's untagged mode. In a flattened
variant, the name of the variant will be ignored. Instead, Deluxe will attempt
to use the unique keys in each variant to determine if that variant was
specified. A compile error will be thrown if it is not possible to determine a
unique, unambiguous key between two variants.
```rust
enum MyEnum { A, B(u64, String), C { id: u64, name: String }, #[deluxe(flatten)] D { d: u64, name: String }, } ```
```rust
struct ObjectA;
struct ObjectB;
struct ObjectC;
// no inner parenthesis needed here due to flattening
struct ObjectD; ```
During parsing, Deluxe can store references to the container type holding the attributes for easier access. Container fields are skipped during attribute parsing.
```rust
struct MyObject<'t> {
id: u64,
// Fill container in using the parsed type. Note this restricts the
// derived ParseAttributes impl so it can only be used on DeriveInput.
#[deluxe(container)]
container: &'t syn::DeriveInput,
}
pub fn derivemyobject(item: TokenStream) -> TokenStream {
let input = syn::parse::
// `obj.container` now holds a reference to `input`
let obj: MyObject = match deluxe::parse_attributes(&input) {
Ok(obj) => obj,
Err(e) => return e.into_compile_error().into()
};
let tokens = quote::quote! { /* ... generate some code here ... */ };
tokens.into()
} ```
To support both extracting and parsing, a container field can also be a value type. In that case, the container will be cloned into the structure.