描述

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

目前不支持嵌套结构体。

目的

使编写定义可执行程序可选配置的 TOML 模板的结构体变得容易。一旦使用实现的 derive 宏和 to_string_pretty_toml() 函数反序列化结构体，就可以将其写入（TOML）文件，文件应该在不了解任何二进制细节的情况下可理解。使用未经编辑的生成的 TOML 文件进行反序列化将产生具有所有可选字段 None 的原始结构体。然后，编辑生成的 TOML 文件将反序列化为具有那些编辑值的原始结构体。

目录

• 描述
• 目的
• 目录
• 指南
  • 什么是 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 包的使用而制作的。示例基于在 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 字段包含 Some(10)，其余字段都是 None。