该 crate 通过 descriptive_toml_derive 发布，并包含过程化 derive 宏的实现。

lib.rs:

描述

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

目前不支持嵌套结构体。

目的

使编写定义可执行文件可选配置的 TOML 模板的 struct 变得容易。一旦使用实现 derive 宏的 to_string_pretty_toml() 函数将 struct 反序列化，就可以将其写入（TOML）文件，该文件无需了解二进制文件的任何详细信息即可理解。不编辑生成的 TOML 文件产生的反序列化将生成具有所有可选字段 None 的原始 struct。然后，编辑生成的 TOML 文件将反序列化为具有那些编辑值的原始 struct。

目录

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

指南

什么是 derive 的？

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

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

在 fastPASTA 中的示例使用

此宏最初是为在 fastPASTA crate 中使用而制作的。示例基于宏在 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。