OptionalStruct

快速入门

从tests/builder.rs文件开始

use optional_struct::*;

#[optional_struct]
#[derive(Eq, PartialEq, Debug)]
struct Foo {
    paf: u16,
    bar: Option<u8>,
    #[optional_wrap]
    baz: Option<char>,
    #[optional_rename(OptionalMiaou)]
    #[optional_wrap]
    miaou: Miaou,
}

#[optional_struct]
#[derive(Eq, PartialEq, Debug)]
struct Miaou {
    a: i8,
    b: i16,
}

#[test]
fn test_builder() {
    let default = Foo {
        paf: 12,
        bar: None,
        baz: Some('a'),
        miaou: Miaou {
            a: 1,
            b: -1,
        },
    };

    let first = OptionalFoo {
        paf: Some(42),
        bar: Some(7),
        baz: Some(None),
        miaou: None,
    };

    let second = OptionalFoo {
        paf: Some(24),
        bar: None,
        baz: Some(Some('c')),
        miaou: Some(OptionalMiaou {
            a: Some(2),
            b: None,
        }),
    };

    let collapsed = first.apply(second).build(default);
    assert_eq!(collapsed, Foo {
        paf: 24,
        bar: Some(7),
        baz: Some('c'),
        miaou: Miaou { a: 2, b: -1 },
    });
}

目标

由于Rust没有默认参数，并且一些工具在反序列化数据时（例如serde）非常严格，缺失的配置值可能会非常令人沮丧。例如

#[derive(Deserialize)]
struct Config {
    log_file: PathBuf,
}

如果我们从文件中读取配置，并且没有指定log_file，serde将无法创建结构体。虽然serde 提供了设置字段默认值的方法，例如

#[derive(Deserialize)]
struct Config {
    #[serde(default = "get_next_log_filename")]
    log_file: PathBuf,
}

存在明显的局限性。这个crate旨在填补这个空白，通过允许可选值，并提供一种简单的方法将来自不同来源的值应用于构建我们的配置。

使用optional_struct，可以定义所需的配置，就像它将被使用一样，并且仅使用生成的结构体来处理配置/缺失值/默认值。

如何

宏optional_struct生成一个包含与它标记的结构体相同字段的结构体，但将这些字段包装在Option中。新结构体上的一个函数允许将其值应用于原始结构体（如果Option不是None）。这可以调用多次，以从不同来源应用配置，同时给调用者完全控制如何设置值的权利，因为生成的结构体可以轻松操作并在构造最终配置之前传递。

特性

1. 重命名生成的结构体

#[optional_struct(HeyU)]
struct Config();

fn main() {
    let me = HeyU();
}

2. 处理递归类型

#[optional_struct]
struct Foo {
    // Replaces Option<Bar> with OptionalBar
    // To generate Option<OptionalBar> instead, add an extra #[optional_wrap]
    // as described later
    #[optional_rename(OptionalBar)]
    bar: Bar,
}

3. 处理原始结构体中的Option（通过忽略它们）

#[optional_struct]
struct Foo {
    bar: Option<u8>,
}

fn main() {
    let opt_f = OptionalFoo { bar: Some(1) };
}

4. 强制包装（或不包装）字段

#[optional_struct]
struct Foo {
    #[optional_skip_wrap]
    bar: char,

    // Useless here since we wrap by default
    #[optional_wrap]
    baz: bool,
}

fn main() {
    let opt_f = OptionalFoo { bar: 'a', baz: Some(false) };
}

5. 更改默认包装行为

#[optional_struct(OptionalFoo, false)]
struct Foo {
    bar: u8,
    #[optional_wrap]
    baz: i8,
}

fn main() {
    let opt_f = OptionalFoo { bar: 1, baz: None };
}

6. 将serde的skip_serializing_if = ""Option::is_none""属性添加到生成的结构体中

通过将属性 #[optional_serde_skip_none] 添加到字段中，生成的结构体将具有相同的字段标记为 #[serde(skip_serializing_if = "Option::is_none")]。此属性使得 serde 在 Option 的值为 none 时（而不是在序列化为 json 时保存例如 "value" = null）完全跳过字段。

apply、build 和 try_build

这三个函数用于通过折叠“左侧”的值来构建结构的最终版本。

函数的签名（伪代码）如下：

impl OptionalStruct {
    fn build(self, s: Struct) -> Struct;
    fn try_build(self) -> Result<Struct, OptionalStruct>;
    fn apply(self, other: OptionalStruct) -> OptionalStruct;
}

这些函数的功能

1. build 接受一个实际的 Struct，并根据 OptionalStruct 中设置了哪些字段来设置其所有字段。缺失的字段保持不变。具有强制包装属性的 Option 字段将不会覆盖值，例如 Some(1) 不会覆盖 Some(2)（有关具体情况的示例，请参阅初始示例）。

2. try_build 尝试从 OptionalStruct 中构建整个 Struct，如果一切顺利，则返回 Ok(Struct)，如果缺少内容，则在 Err(OptionalStruct) 中返回初始的 OptionalStruct。

3. apply 接受一个 OptionalStruct 作为参数，并将其实例的字段应用于 左侧（即 self）。如果 self 和 other 都定义了某些内容，则采用 other 的值。如果 self 定义了某些内容但 other 没有定义，则保留该值。当然，如果 self 没有定义但 other 定义了，则使用该值。