8 releases (4 breaking)

0.5.0 Jun 5, 2023
0.4.1 Apr 16, 2023
0.4.0 Oct 9, 2020
0.3.1 Oct 7, 2020
0.1.0 Sep 14, 2020
Download history 724/week @ 2023-10-30 885/week @ 2023-11-06 931/week @ 2023-11-13 894/week @ 2023-11-20 1634/week @ 2023-11-27 1213/week @ 2023-12-04 1337/week @ 2023-12-11 1633/week @ 2023-12-18 4621/week @ 2023-12-25 3285/week @ 2024-01-01 2975/week @ 2024-01-08 2464/week @ 2024-01-15 2652/week @ 2024-01-22 3263/week @ 2024-01-29 2450/week @ 2024-02-05 2366/week @ 2024-02-12

10,988 downloads per month
Used in 14 crates (5 directly)

MIT/Apache

40KB
853 lines

Text Placeholder

Text Placeholder is a minimalistic text template engine designed for the manipulation of named placeholders within textual templates.

This library operates based on two primary elements:

  • Placeholders: Defined markers within the text templates intended to be replaced by actual content in the final rendition.

  • Context: The precise data set used for the replacement of placeholders during the template rendering process.

For use within a no_std environment, Text Placeholder can be configured by disabling the default features. This allows the library to maintain compatibility with no_std specifications.

Placeholders

Placeholders are defined within certain boundaries and will be replaced once the template is parsed.

Let's define a template with placeholders named first and second:

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

Templates use the handlebars syntax as boundaries by default, but can be overridden:

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

Context

Context is the data structure that will be used to replace your placeholders with real data.

You can think of your placeholder as a key within a HashMap or the name of a field within a struct. In fact, these are the three types of context supported by this library:

  • HashMap.
  • A function
  • Struct, as an optional feature.

HashMap

Each placeholder should be a key with an associated value that can be converted into a str.

The following methods are available with a HashMap:

  • fill_with_hashmap
    • replaces missing placeholders with an empty string.
    • replaces placeholders that cannot be converted to a strint with an empty string.
  • fill_with_hashmap_strict which returns a Error::PlaceholderError when:
    • a placeholder is missing.
    • a placeholder value cannot be converted to a string.

Example

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!");

Function

This uses a function to generate the substitution value. The value could be extracted from a HashMap or BTreeMap, read from a config file or database, or purely computed from the key itself.

The function takes a key and returns an Option<Cow<str>> - that is it can return a borrowed &str, an owned String or no value. Returning no value causes fill_with_function to fail (it's the equivalent of fill_with_hashmap_strict in this way).

The function actually a FnMut closure, so it can also modify external state, such as keeping track of which key values were used. key has a lifetime borrowed from the template, so it can be stored outside of the closure.

Example

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

Struct

Allow structs that implement the serde::Serialize trait to be used as context.

This is an optional feature that depends on serde. In order to enable it add the following to your Cargo.toml file:

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

Each placeholder should be a field in your struct with an associated value that can be converted into a str.

The following methods are available with a struct:

  • fill_with_struct
    • replaces missing placeholders with an empty string.
    • replaces placeholders that cannot be converted to a strint with an empty string.
  • fill_with_struct_strict which returns a Error::PlaceholderError when:
    • a placeholder is missing.
    • a placeholder value cannot be converted to a string.

Example

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!");

Dependencies

~1.5MB
~26K SLoC