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 在序列化为 json 时完全跳过值为 none 的 Option 字段（而不是保存例如 "value" = null）。

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