Toml示例

一个库，帮助生成toml示例

简介

此crate提供TomlExample特性和相应的derive宏。

在结构体上派生TomlExample将提供一个to_example函数，帮助生成基于文档的toml示例文件

• 支持#[serde(default)]、#[serde(default = "function_name")]属性（serde功能，可选）
• 支持#[serde(rename)]、#[serde(rename_all = "renaming rules")]重命名规则可以是lowercase、UPPERCASE、PascalCase、camelCase、snake_case、SCREAMING_SNAKE_CASE、kebab-case、SCREAMING-KEBAB-CASE
• 提供 #[toml_example(default)]、#[toml_example(default = 0)]、#[toml_example(default = ""default_string"")] 属性
• 属性宏的顺序很重要，如果同时存在不同值的 #[serde(default = ..] 和 #[toml_example(default = ...)]

快速示例

use toml_example::TomlExample;

/// Config is to arrange something or change the controls on a computer or other device
/// so that it can be used in a particular way
#[derive(TomlExample)]
struct Config {
    /// Config.a should be a number
    a: usize,
    /// Config.b should be a string
    b: String,
    /// Optional Config.c is a number
    c: Option<usize>,
    /// Config.d is a list of number
    d: Vec<usize>,
    /// Config.e should be a number
    #[serde(default = "default_int")]
    e: usize,
    /// Config.f should be a string
    #[serde(default = "default_str")]
    f: String,
    /// Config.g should be a number
    #[toml_example(default =7)]
    g: usize,
    /// Config.f should be a string
    #[toml_example(default = "seven")]
    h: String,
}
fn default_int() -> usize {
    7
}
fn default_str() -> String {
    "seven".into()
}

Config::to_toml_example("example.toml");  // write example to a file
let example = Config::toml_example();

基于每个字段的文档字符串的 Toml 示例

# Config is to arrange something or change the controls on a computer or other device
# so that it can be used in a particular way

# Config.a should be a number
a = 0

# Config.b should be a string
b = ""

# Optional Config.c is a number
# c = 0

# Config.d is a list of number
# d = [ 0, ]

# Config.e should be a number
e = 7

# Config.f should be a string
f = "seven"

# Config.g should be a number
g = 7

# Config.h should be a string
h = "seven"

嵌套结构体

嵌套结构体用 Option<T>、Vec<T>、HashMap<String, T>、BTreeMap<String, T> 包装处理。请在字段上添加 #[toml_example(nesting)] 或 #[toml_example(nesting = prefix)]。 #[toml_example(nesting)]

  /// Service with specific port
  #[derive(TomlExample)]
  struct Service {
      /// port should be a number
      #[toml_example(default = 80)]
      port: usize,
  }
  #[derive(TomlExample)]
  #[allow(dead_code)]
  struct Node {
      /// Services are running in the node
      #[toml_example(nesting)]
      #[toml_example(default = http)]
      services: HashMap<String, Service>,
  }

Node::toml_example() 将遵循以下字符串。

# Services are running in the node
# Service with specific port
[services.http]
# port should be a number
port = 80

如果您想在示例中将可选字段变为必填字段，请在该字段上放置 #[toml_example(require)]。如果您想跳过某些字段，可以使用 #[toml_example(skip)]，#[serde(skip)]，或者 #[serde(skip_deserializing)] 也同样有效。

use toml_example::TomlExample;
#[derive(TomlExample)]
struct Config {
    /// Config.a is an optional number
    #[toml_example(require)]
    a: Option<usize>,
    /// Config.b is an optional string
    #[toml_example(require)]
    b: Option<String>,
    #[toml_example(require)]
    #[toml_example(default = "third")]
    c: Option<String>,
    #[toml_example(skip)]
    d: usize,
}

# Config.a is an optional number
a = 0

# Config.b is an optional string
b = ""

c = "third"