Description

Procedural derive macro for serializing a struct into a TOML template with field descriptions that is easily edited and deserialized.

Nested structs are not currently supported.

Purpose

Make it easy to write a struct that defines a TOML template for optional configuration of an executable. Once the struct is deserialized with the derive macro implemented to_string_pretty_toml() function, it can be written to a (TOML) file, the file should be understandable without knowing any details of the binary. Deserializing the produced TOML file with no edits produceses the original struct with all optional fields None. Editing the produced TOML file will then deserialize into the original struct with those edited values.

Table of Contents

• Description
• Purpose
• Table of Contents
• Guide
  • What is derived?
  • Example use in fastPASTA
    • Implementing
    • Serializing
    • Deserializing

Guide

What is derived?

A pub trait named TomlConfig with a single function with the signature: fn to_string_pretty_toml(&self) -> String

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

Example use in fastPASTA

This macro was originally made for use in the fastPASTA crate. The example is based on how the macro is used in fastPASTA.

Implementing

The struct CustomChecks is implemented like this:

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>)>,
}

Serializing

The template file is generated e.g. like this.

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

The contents of "custom_checks.toml" is now:

# 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)

Editing all the fields to contain Some values could look like this:

# 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]]

Deserializing

Deserializing from a TOML file is the same method as with any other TOML file, using serde_derive:

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

A user that is already familiar with the configuration file might simply write

cdps = 10

And input it to the binary. Which would deserialize into a struct with the cdps field containing Some(10), and the rest of the fields are None.