描述

将结构体序列化为具有字段描述的 TOML 模板的过程宏，该模板易于编辑和反序列化。

目前不支持嵌套结构体。

目的

使编写定义 TOML 模板的结构体变得简单，以便对可执行文件进行可选配置。一旦使用实现 derive 宏的 to_string_pretty_toml() 函数将结构体反序列化，就可以将其写入文件（TOML）中，文件应在不了解任何二进制细节的情况下可理解。不修改产生的 TOML 文件即可反序列化出原始结构体，所有可选字段均为 None。然后，编辑产生的 TOML 文件将反序列化为原始结构体，并使用编辑后的值。

目录

• 描述
• 目的
• 目录
• 指南
  • 什么是 derive？
  • 在 fastPASTA 中的示例使用
    • 实现
    • 序列化
    • 反序列化

指南

什么是 derive？

一个名为 pub trait 的 TomlConfig，它具有一个具有以下签名的单个函数： fn to_string_pretty_toml(&self) -> String

pub trait TomlConfig {
    fn to_string_pretty_toml(&self) -> String;
}

在 fastPASTA 中的示例使用

此宏最初是为在 fastPASTA 包中使用而制作的。示例基于在 fastPASTA 中如何使用宏。

实现

结构体 CustomChecks 如此实现

use descriptive_toml_derive::TomlConfig;
use serde_derive::{Deserialize, Serialize};

pub trait TomlConfig {
    fn to_string_pretty_toml(&self) -> String;
}

// Deriving the `TomlConfig` macro which implements the `TomlConfig` trait.
#[derive(TomlConfig, Default, Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CustomChecks {
    // Use the `description` field attribute of the macro
    #[description = "Number of CRU Data Packets expected in the data"]
    // Use the `example` field attribute of the macro to show some example values
    #[example = "20, 500532"]
    cdps: Option<u32>,

    #[description = "Number of Physics (PhT) Triggers expected in the data"]
    #[example = "0, 10"]
    triggers_pht: Option<u32>,

    #[description = "Legal Chip ordering for Outer Barrel (ML/OL). Needs to be a list of two lists of 7 chip IDs"]
    #[example = "[[0, 1, 2, 3, 4, 5, 6], [8, 9, 10, 11, 12, 13, 14]]"]
    chip_orders_ob: Option<(Vec<u8>, Vec<u8>)>,
}

序列化

模板文件生成示例

let toml = CustomChecks::default().to_string_pretty_toml();
std::fs::write("custom_checks.toml", toml).unwrap();

现在 "custom_checks.toml" 的内容如下

# Number of CRU Data Packets expected in the data
# Example: 20, 500532
#cdps = None [ u32 ] # (Uncomment and set to enable this check)

# Number of Physics (PhT) Triggers expected in the data
# Example: 0, 10
#triggers_pht = None [ u32 ] # (Uncomment and set to enable this check)

# Legal Chip ordering for Outer Barrel (ML/OL). Needs to be a list of two lists of 7 chip IDs
# Example: [[0, 1, 2, 3, 4, 5, 6], [8, 9, 10, 11, 12, 13, 14]]
#chip_orders_ob = None [ (Vec < u8 >, Vec < u8 >) ] # (Uncomment and set to enable this check)

将所有字段编辑为包含 Some 值可能看起来像这样

# Number of CRU Data Packets expected in the data
# Example: 20, 500532
cdps = 20

# Number of Physics (PhT) Triggers expected in the data
# Example: 0, 10
triggers_pht = 0

# Legal Chip ordering for Outer Barrel (ML/OL). Needs to be a list of two lists of 7 chip IDs
# Example: [[0, 1, 2, 3, 4, 5, 6], [8, 9, 10, 11, 12, 13, 14]]
chip_orders_ob = [[0, 1, 2, 3, 4, 5, 6], [8, 9, 10, 11, 12, 13, 14]]

反序列化

从 TOML 文件反序列化的方法与任何其他 TOML 文件相同，使用 serde_derive

let toml = std::fs::read_to_string("custom_checks.toml").unwrap();
let custom_checks = toml::from_str(&toml).unwrap();

熟悉配置文件的用户可能只需编写

cdps = 10

将输入信息输入到二进制中。它将反序列化为一个包含 cdps 字段的struct，该字段包含 Some(10)，其余字段都是 None。