2 个版本

0.1.1	2023年7月15日
0.1.0	2023年7月7日

#4 在 #toml-macro

每月下载量 35
在 fastpasta_toml_macro 中使用

MIT/Apache

18KB
124 行

descriptive_toml_derive

描述

这是一个过程宏，可以将结构体序列化为一个带有字段描述的 TOML 模板，该模板易于编辑和反序列化。

目前不支持嵌套结构体。

目的

使编写定义可选配置的 TOML 模板的结构体变得简单。一旦使用实现的 derive 宏对结构体进行反序列化 to_string_pretty_toml() 函数，就可以将其写入文件（TOML），该文件应无需了解二进制文件的任何细节即可理解。不进行编辑地反序列化生成的 TOML 文件将生成包含所有可选字段 None 的原始结构体。然后编辑生成的 TOML 文件将反序列化为具有这些编辑值的原始结构体。

指南

什么是派生的？

一个名为 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 fastpasta_toml_macro_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。

依赖项

~300–750KB
~18K SLoC

废弃宏 fastpasta_toml_macro_derive