文本占位符

Text Placeholder 是一个简约的文本模板引擎，专为在文本模板中操作命名占位符而设计。

该库基于两个主要元素

• 占位符：在文本模板中定义的标记，旨在在最终版本中替换为实际内容。

• 上下文：在模板渲染过程中替换占位符的精确数据集。

对于在 no_std 环境 中使用，Text Placeholder 可以通过禁用 默认功能 来进行配置。这允许库保持与 no_std 规范的兼容性。

占位符

占位符在特定的边界内定义，并在模板解析后进行替换。

让我们定义一个具有命名占位符 first 和 second 的模板

let template = Template::new("Hello {{first}} {{second}}!");

模板默认使用 handlebars 语法作为边界，但可以被覆盖

let template = Template::new_with_placeholder("Hello $[first] $[second]!", "$[", "]");

上下文

上下文是用于用实际数据替换占位符的数据结构。

您可以将占位符视为 HashMap 中的键或 struct 字段名称。实际上，这是该库支持的这三种上下文类型

• HashMap。
• 一个函数
• 结构体，作为一个 可选 功能。

HashMap

每个占位符都应该是一个 key，与一个可以转换为 str 的 value 相关联。

以下是在 HashMap 中可用的方法

• fill_with_hashmap
  • 用空字符串替换缺失的占位符。
  • 用空字符串替换无法转换为字符串的占位符。
• fill_with_hashmap_strict，当占位符缺失时返回一个 Error::PlaceholderError，
  • 占位符缺失。
  • 占位符值无法转换为字符串。

示例

use text_placeholder::Template;
use std::collections::HashMap; // or for no_std `use hashbrown::HashMap;`

let default_template = Template::new("Hello {{first}} {{second}}!");

let mut table = HashMap::new();
table.insert("first", "text");
table.insert("second", "placeholder");

assert_eq!(default_template.fill_with_hashmap(&table), "Hello text placeholder!");

// We can also specify our own boundaries:

let custom_template = Template::new_with_placeholder("Hello $[first]] $[second]!", "$[", "]");

assert_eq!(default_template.fill_with_hashmap(&table), "Hello text placeholder!");

函数

此函数用于生成替换值。该值可以从HashMap或BTreeMap中提取，从配置文件或数据库中读取，或仅从键本身计算得出。

该函数接收一个key并返回一个Option<Cow<str>> - 这意味着它可以返回一个借用&str、一个拥有String或没有值。返回无值会导致fill_with_function失败（这相当于fill_with_hashmap_strict）。

实际上，这是一个FnMut闭包，因此它还可以修改外部状态，例如跟踪使用了哪些key值。key具有从模板借用的一生，因此可以存储在闭包之外。

示例

use text_placeholder::Template;
use std::borrow::Cow;

let template = Template::new("Hello {{first}} {{second}}!");

let mut idx = 0;
assert_eq!(
    &*template.fill_with_function(
    |key| {
      idx += 1;
      Some(Cow::Owned(format!("{key}-{idx}")))
    })
    .unwrap(),
    "Hello first-1 second-2!"
);
assert_eq!(idx, 2);

结构体

允许使用实现serde::Serialize特质的结构体作为上下文。

这是一个依赖于serde的可选功能。要启用它，请将以下内容添加到您的Cargo.toml文件中

[dependencies]
text_placeholder = { version = "0.4", features = ["struct_context"] }

每个占位符都应该是一个具有相关value的field，该值可以转换为str。

以下方法可用于结构体

• fill_with_struct
  • 用空字符串替换缺失的占位符。
  • 用空字符串替换无法转换为字符串的占位符。
• fill_with_struct_strict在返回时会返回一个Error::PlaceholderError。
  • 占位符缺失。
  • 占位符值无法转换为字符串。

示例

use text_placeholder::Template;

#[derive(Serialize)]
struct Context {
    first: String,
    second: String
}

let default_template = Template::new("Hello {{first}} {{second}}!");
let context = Context { first: "text".to_string(), second: "placeholder".to_string() };

assert_eq!(default_template.fill_with_struct(&context), "Hello text placeholder!");

// We can also specify our own boundaries:

let custom_template = Template::new_with_placeholder("Hello $[first]] $[second]!", "$[", "]");

assert_eq!(default_template.fill_with_struct(&context), "Hello text placeholder!");