fieldx v0.1.3

用于构建具有延迟初始化字段、构建模式和serde支持的结构的程序宏，重点在于声明性语法。

让我们从一个例子开始

use fieldx::fxstruct;

#[fxstruct( lazy )]
struct Foo {
    count: usize,
    foo:   String,
    #[fieldx( lazy(off), get )]
    order: RefCell<Vec<&'static str>>,
}

impl Foo {
    fn build_count(&self) -> usize {
        self.order.borrow_mut().push("Building count.");
        12
    }

    fn build_foo(&self) -> String {
        self.order.borrow_mut().push("Building foo.");
        format!("foo is using count: {}", self.count())
    }
}

let foo = Foo::new();
assert_eq!(foo.order().borrow().len(), 0);
assert_eq!(foo.foo(), "foo is using count: 12");
assert_eq!(foo.foo(), "foo is using count: 12");
assert_eq!(foo.order().borrow().len(), 2);
assert_eq!(foo.order().borrow()[0], "Building foo.");
assert_eq!(foo.order().borrow()[1], "Building count.");

这里发生的事情是

• 一个所有字段默认为 lazy 的结构体
• 对于字段 order，显式禁用延迟初始化
• 方法 build_count 和 build_foo 返回对应字段的初始值

在运行时，我们首先确保 order 向量是空的，这意味着没有调用任何 build_ 方法。然后我们通过其访问器方法读取 foo。然后我们确保每个 build_ 方法只被调用一次。

正如人们所注意到的那样，这里需要的手动操作量最小，因为宏处理了大部分模板代码，它还提供了一个基本的 new 关联函数。

此外，请注意，我们不需要记住字段的初始化顺序。由于它总是会初始化，所以 foo 的构建器在使用 count 时不需要担心它是否已经初始化，因为总是会初始化。

基础知识

该模块提供了两个属性：fxstruct 和 fieldx。前者负责配置结构体，后者用于调整字段参数。

该宏只能用于命名结构体，不支持联合类型或枚举。应用时，它根据提供的参数重写应用到的类型。以下是最大的更改和新增内容列表

• 字段类型可以包装到容器类型中

  在上面的例子中，foo 和 count 变成了 [OnceCell<String>][OnceCell] 和 OnceCell<usize>，而 order 保持不变。

• 添加了对 Foo 的部分实现，包括支持方法和相关函数

  即，这是访问器和 new 存在的地方。

• 根据参数，可能会添加 Default 特性的隐式实现

• 如果需要，将实现构建器结构和相关函数 builder()

• 此外，如果需要，还会提供用于正确 serde 支持的阴影结构体

注意 用户被强烈建议不要直接访问修改后的字段。该模块将尽最大努力通过相应的方法提供所有必要的 API。

同步和非同步结构体

如果需要一个线程安全的结构体，则 fxstruct 必须接受 sync 参数：#[fxstruct(sync, ...)]。当被指示时，宏将尽力在字段级别提供并发安全性。这意味着

• 构建器方法保证在每个懒初始化过程中只调用一次，无论是单线程还是多线程应用程序
• 对结构体字段的访问是锁保护的（除非用户另有要求）

同步和非同步结构体在它们与用户代码的交互方式上也非常不同。

此外，非同步结构体的非可变访问器通常返回其字段的引用。同步结构体的访问器，除非指示使用 clone 或 copy，或与一个非受保护的字段一起使用，返回一种锁保护器。

同步结构体字段的包装类型是非 std 的，由该模块提供。

同步结构体的受保护和未受保护的字段

对于要成为 Sync+Sent 的 fieldx 同步结构体，所有字段都应预期为 锁保护的（或者，有时我们可以说 "保护的"）。但是，“预期”并不意味着“必须”。除非使用 fxstruct 属性（即使用 结构级 参数）指定的默认值告诉否则，未使用 fieldx 属性带有相应参数的字段将保持 未受保护的。即

#[fxstruct(sync)]
struct Foo {
    #[fieldx(lazy)]
    foo: String, // protected
    #[fieldx(get_mut)]
    bar: String, // unprotected
}

当然，结构体是否保持线程安全将取决于未受保护字段的安全性。

可选字段

在这个上下文中，“可选”与 Option 类型的意义相同。当然，可以简单地使用核心类型声明一个字段（实际上，fieldx 内部就是这样做的）。那么使用 fieldx 的优点是什么呢？

首先，手动声明可能意味着额外的样板代码来实现访问器，以及其他事情。使用 fieldx 的大部分内容可以隐藏在单个声明之下

#[fxstruct]
struct Foo {
    #[fieldx(predicate, clearer, get, set(into))]
    description: String,
}

let mut obj = Foo::new();
assert!( !obj.has_description() );
obj.set_description("foo");
assert!( obj.has_description() );
assert_eq!( obj.description(), &Some(String::from("foo")) );
obj.clear_description();
assert!( !obj.has_description() );

<digression_mode> 此外，从美学角度来看，某些 has_description 比以下代码更具吸引力：obj.description().is_some()。</digression_mode>

接下来，sync 结构体的可选字段默认情况下由锁保护。这可以通过显式调用 lock(off) 来改变，但必须意识到结构体的同步状态将取决于字段的健壮性。

最后一点要注意的是，如果将字段转换为 lazy 有助于某些情况，那么重构可以简化为仅添加相应的 fieldx 属性并为其实现一个新的构建器。

惰性协议

尽管这是一个非常简单的概念，但惰性有自己的特性。如上所示，基本原理是这样的：当我们将字段声明为 lazy 时，宏将其包装成某种代理容器类型（对于非同步结构体是 OnceCell）。从未初始化的字段中进行的第一次读取[^only_via_method] 将触发构建方法调用，并将返回的值存储在该字段中。

以下是注意事项

1. 构建器预计是不可错误的。这一要求来源于当我们调用字段的访问器时，我们期望返回字段类型的值。由于 Rust 要求半就地处理错误（与许多其他语言中的异常相反），我们无法克服这一限制。构建器可能会引发恐慌，但这很少是一个好选择。

   对于需要可控错误处理的情况，可以为字段赋予 Result 类型。然后，obj.field()? 可以作为一种处理错误的方法。

2. 字段构建器方法不能修改它们的对象。这种限制也源于典型的访问器方法不需要也不应该使用可变的 &self。当然，使用内部可变性总是可能的，就像这里的第一个例子。

[^only_via_method]：显然，必须通过调用相应的方法来访问。通常，它将是字段的访问器，但对于 sync 结构体，更可能是读取器。

构建器模式

重要！ 首先需要指出这里存在术语上的不明确性。术语 build 和 builder 用于不同的过程，尽管在本质上相同。如前所述，惰性构建器 是返回关联字段初始值的方法。本节中的 结构体构建器 是一个收集用户初始值并能够创建原始结构体最终实例的对象。这种歧义有一些历史背景，可以追溯到 Perl 的 Moo 模块成为作者的 主要工具的时代。然后它被 Raku AttrX::Mooish 采用，最后自动进入 fieldx，最初没有实现构建器模式。

由 fxstruct 宏生成的默认 new 方法不接受任何参数，仅创建一个由类型默认值初始化的裸骨对象。对于结构体字段的提交自定义值，最好通过使用构建器模式来完成。

#[fxstruct(builder)]
struct Foo {
    #[fieldx(lazy)]
    description: String,
    count: usize,
}

impl Foo {
    fn build_description(&self) -> String {
        format!("this is item #{}", self.count)
    }
}

let obj = Foo::builder()
            .count(42)
            .build()
            .expect("Foo builder failure");
assert_eq!( obj.description(), &String::from("this is item #42") );

let obj = Foo::builder()
            .count(13)
            .description(String::from("count is ignored"))
            .build()
            .expect("Foo builder failure");
// Since the `description` is given a value the `count` field is not used
assert_eq!( obj.description(), &String::from("count is ignored") );

由于在构建新对象实例时可能发生的唯一与 fieldx 相关的失败情况是未提供值的必填字段，如果发生这种情况，build() 方法将返回 FieldXError。

软件包功能

以下功能由该软件包支持

使用方法

大多数 fxstruct 和 fieldx 的参数都可以采用两种形式之一：关键字（arg），或 "函数"（arg(subarg)）。

此外，大多数参数都由 fxstruct 和 fieldx 共享。但它们的意义以及它们参数的解析方式可能因每个属性而略有不同。例如，如果参数接受字面字符串子参数，则它很可能是在与 fieldx 关联时作为方法名；但对于 fxstruct，它将定义方法名的公共前缀。

大多数参数之间也存在共同点：它们可以通过使用与它们一起使用的 off 子参数来暂时（例如，用于测试目的）或永久关闭。请参阅上面的例子中的 lazy(off)。

属性参数

关于术语的一些说明

• 参数 类型 确定可以接收哪些子参数

  • 关键字 - 类似于布尔型，仅接受 off：keyword(off)
  • 标志 - 与上面的关键字类似，但不接受任何参数；实际上，上面的 off 是一个 标志
  • 辅助工具 - 引入与辅助方法绑定的功能（见下文）
  • 列表 或 函数 - 可以接受多个子参数
  • 元 - 可以接受一些语法结构

• 辅助方法 - 实现某些功能

  几乎所有辅助方法都是由宏生成的。唯一的例外是必须由用户提供的懒惰构建器。

• 对于 指定参数是否特定于属性

辅助参数的子参数

辅助参数共享一些常见的子参数。我们将在下面描述它们，但如果它们的意义不明确，则最好跳过此部分，稍后再回来。

例如

#[fxstruct( get( "get_", public(crate) ) )]

将生成以 get_ 为前缀的访问器方法，其可见性为 pub(crate)

let foo = obj.get_foo();

使用

#[fieldx( get( "special_type", private ) )]
ty: String,

拥有字段的结构的某个方法可以使用访问器如下

let foo = self.special_type();

attributes* 子参数族

有时可能需要为各种生成的语法元素指定属性，例如方法或辅助结构。当适用时，此功能由 attributes*（子）参数支持。其语法为 attributes(<attr1>, <attr2>, ...)，其中指定了精确的 <attr>，正如在代码中指定一样，但省略了起始的 #[ 和结束的 ]。

例如，attributes_fn(allow(dead_code), cfg(feature = "myfeature")) 将扩展成类似的内容

#[allow(dead_code)]
#[cfg(feature = "myfeature")]

当前支持以下族成员：attributes、attributes_fn 和 attributes_impl。特定上下文中支持哪些已在下面进行文档说明。

fxstruct 参数

attributes

类型：list

为 builder 和 serde 参数生成的结构体提供默认属性。

attributes_impl

类型：list

应用于结构体实现的属性。

sync

类型：keyword

声明结构体为线程安全。

lazy

类型：helper

为除标记为 lazy(off) 的字段外的所有字段启用懒模式。

builder

类型：helper

通过引入关联函数和构建器类型启用构建器功能。

#[fxstruct(builder, get)]
struct Foo {
    description: String,
}
let obj = Foo::builder()
               .description(String::from("some description"))
               .build()?;
assert_eq!(obj.description(), "some description");

builder 的字面字符串子参数定义了构建器方法设置器的前缀。例如，使用 builder("set_")，将使用 .set_description(...) 调用。

其他子参数

• attributes（见上面的部分）– 构建器结构体的属性

• attributes_impl - 结构体实现的属性

• into – 强制所有构建器设置方法尝试使用 .into() 方法进行自动类型转换

  使用 into，上面的示例不需要 String::from，调用可以像这样：.description("some description")

#[fxstruct(get, get_mut)]
struct Foo {
    description: String,
}
let mut obj = Foo::new();
*obj.description_mut() = "some description".to_string();
assert_eq!(obj.description(), "some description");

#[fxstruct(set(into), get)]
struct Foo {
    description: String,
}
let mut obj = Foo::new();
obj.set_description("some description");
assert_eq!(obj.description(), &"some description".to_string());

#[fxstruct(sync, reader, writer)]
struct Foo {
    description: String,
}
let obj = Foo::new();
{
    let mut wguard = obj.write_description();
    *wguard = String::from("let's use something different");
}
{
    let rguard = obj.read_description();
    assert_eq!(*rguard, "let's use something different".to_string());
}

#[cfg(feature = "serde")]
#[fxstruct(sync, get, serde("BazDup", default(Self::serde_default())))]
#[derive(Clone)]
pub(super) struct Baz {
    #[fieldx(reader)]
    f1: String,
    f2: String,
}

impl Baz {
    fn serde_default() -> Fubar {
        Fubar {
            postfix: "from fubar".into()
        }
    }
}

struct Fubar {
    postfix: String,
}

impl From<Fubar> for BazDup {
    fn from(value: Fubar) -> Self {
        Self {
            f1: format!("f1 {}", value.postfix),
            f2: format!("f2 {}", value.postfix),
        }
    }
}

let json_src = r#"{"f1": "f1 json"}"#;
let foo_de = serde_json::from_str::<Baz>(&json_src).expect("Bar deserialization failure");
assert_eq!(*foo_de.f1(), "f1 json".to_string());
assert_eq!(*foo_de.f2(), "f2 from fubar".to_string());

#[fxstruct(sync)]
struct Foo {
    #[fieldx(get(copy), reader, lazy)]
    bar: u32
}
impl Foo {
    fn build_bar(&self) -> u32 { 1234 }
    fn do_something(&self) -> u32 {
        // We need to protect the field value until we're done using it.
        let bar_guard = self.read_bar();
        let outcome = *bar_guard * 2;
        outcome
    }
}
let foo = Foo::new();
assert_eq!(foo.do_something(), 2468);

#[fxstruct(sync)]
struct Foo {
    #[fieldx(get_mut, get(copy), writer, lazy)]
    bar: u32
}
impl Foo {
    fn build_bar(&self) -> u32 {
        eprintln!("Building bar");
        1234
    }
    fn do_something1(&self) {
        eprintln!("Using writer.");
        let mut bar_guard = self.write_bar();
        bar_guard.store(42);
    }
    fn do_something2(&self) {
        eprintln!("Using get_mut.");
        let mut bar_guard = self.bar_mut();
        *bar_guard = 12;
    }
}

let foo = Foo::new();
foo.do_something1();
assert_eq!(foo.bar(), 42);

let foo = Foo::new();
foo.do_something2();
assert_eq!(foo.bar(), 12);

Using writer.
Using get_mut.
Building bar