annotation-rs

针对Rust的编译时注释解析器

功能

注释

annotation-rs提供了一个派生宏Annotation，可以通过结构体StructStruct、TupleStruct和NoFieldStruct来创建注释结构体。

use annotation_rs::Annotation;

#[derive(Annotation)]
struct NoField;

#[derive(Annotation)]
struct Tuple(i32, String);

#[derive(Annotation)]
struct Struct {
    int: i32,
    float: f64,
    bool: bool,
}

类型

• String：Rust中的String。
• Bool：Rust中的bool。
• 整数：Rust中的任何整数类型。
• 浮点数：Rust中的任何浮点类型。
• 对象：其他注释结构体。
• 枚举：定义枚举，记得使用enum_value=true选项。
• Vec：T的Vec（T不能是对象、Vec或HashMap）。
• HashMap：通过String Skey映射的T的HashMap。如果想要使字段可选，在字段类型上使用Option<T>。

use annotation_rs::{AnnotationEnumValue, Annotation};

#[derive(Annotation)]
struct Bar;

#[derive(AnnotationEnumValue)]
enum SomeEnum {
    A,
    B
}

#[derive(Annotation)]
struct Foo {
    pub string: String,
    pub bool: bool,
    pub int: i32, // or other integer types like u32 ...
    pub float: f32, // or other float types like f64
    pub object: Bar, // any defined object
    #[field(enum_value=true)]
    pub enum_field: SomeEnum, // have to add enum_value option
    pub list: Vec<i32>, // nested type of vec can`t be Object, Vec or HashMap
    pub map: std::collections::HashMap<String, SomeEnum>,
    pub optional: Option<i32> // optional field
}

选项

• alias
  生成的读取器将以给定的名称解析字段，而不是Rust中字段的名称。

  #[derive(Annotation)]
  struct Foo {
      #[field(alias = "i32")]
      pub int32: i32,
  }
  

• default
  设置此字段的默认值。如果解析时值不存在，则将默认值设置为字段，即使字段是可选的。Object、Vec或HashMap字段不能有默认值。

  #[derive(Annotation)]
  struct Foo {
      #[field(default = 1024)]
      pub int32: i32
  }
  

• enum_value
  在枚举类型字段上使用enum_value=true。

枚举

使用派生AnnotationEnumValue在枚举上创建枚举值类型。

use annotation_rs::AnnotationEnumValue;

#[derive(AnnotationEnumValue)]
enum SomeEnum {
    A,
    B
}

然后，枚举可以用作字段类型。

• variant_value属性
  自定义与变体对应的字符串值（默认是Rust中变体名称的蛇形写法）。

use annotation_rs::AnnotationEnumValue;

#[derive(AnnotationEnumValue)]
enum SomeEnum {
    #[variant_value("aaa")] // default is 'a'
    A,
    B
}

使用syn和quote解析注释

annotation_rs::AnnotationStructures<T>可以在parse_macro_input!中使用。

let annotations = syn::parse_macro_inpit!(input as annotation_rs::AnnotationStructures<Foo>);

如果您想从syn::Meta解析注释，请使用annotation_rs::AnnotationStructure::from_meta()。
具有值的注解结构可以自动转换为令牌。但每个字段的可见性必须为公共。

use proc_macro::TokenStream;

#[derive(Annotation)]
struct Foo {
    #[field(default = 1024)]
    pub int32: i32
}

fn derive_fn(input: TokenStream) -> TokenStream {
    let annotations = syn::parse_macro_input!(input as annotation_rs::AnnotationStructures<Foo>);
    let attrs = annotations.attrs;

    TokenStream::from(quote::quote! {
        fn get_attrs() -> Vec<Foo> {
            vec![#(#attrs),*]
        }
    })
}

生成派生宏

如果您想使用内置的读取器生成器，请启用annotation_reader功能。宏generate_reader用于生成派生宏。

use annotation_rs::generate_reader;

generated_reader!(
    MyDerive,
    [StructAttribute1, StructAttribute2],
    [FieldAttribute1, FieldAttribute2]
);

该宏将生成一个公共派生，可以用于读取struct、enum或union的注解，并通过生成impl块来记录元数据。

读取注解

在结构体上使用生成的派生宏，并可以使用宏has_annotation和get_annotation来处理结构体的注解。此功能需要nightly rustc，因为需要proc_macro_hygiene。

#![feature(proc_macro_hygiene)]
use annotation_rs::{get_annotation, has_annotation};

#[derive(MyDerive)]
#[StructAttribute1("some parameters")]
struct Foo {
    #[FieldAttribute1("some parameters")]
    field: i32
}

fn some_fn() {
    assert!(has_annotation!(Foo, StructAttribute1));
    assert!(has_annotation!(Foo::field, FieldAttribute1));
    let struct_attr1: Option<StructAttribute1> = get_annotation!(Foo, StructAttribute1);
    let field_attr1: Option<StructAttribute1> = get_annotation!(Foo::field, StructAttribute1);
}