Struct TemplateResolver

pub struct TemplateResolver(pub TemplateAST);

Main template resolution engine

Implementation Notes

• cfg(feature = "std")
  • Uses HashMap with std for O(1) lookups
• no_std:
  • Falls back to BTreeMap in no_std (O(log n) lookups)

Tuple Fields

0: TemplateAST

Implementations

impl TemplateResolver

pub fn encode_bin<P: AsRef<Path>>(&self, dst_file: P) -> ResolverResult<usize>

Available on crate features bincode and std only.

Serializes the resolver to bincode format and writes to a file

Design Notes

• Uses buffered writer for optimal large-file performance
• Leverages bincode’s compact binary representation
• Preserves structure ordering through deterministic serialization

Example

use tmpl_resolver::TemplateResolver;

let resolver: TemplateResolver = [
    ("h", "Hello"),
    ("greeting", "{h} { $name }!")
  ]
  .try_into()
  .expect("Invalid slice");

let file = "tmp.bincode";

resolver.encode_bin(file).expect("Failed to encode TemplateResolver to bincode file");

pub fn decode_bin<P: AsRef<Path>>(src_file: P) -> ResolverResult<Self>

Available on crate features bincode and std only.

Deserializes a resolver from bincode-formatted file

It Uses buffered reading for I/O efficiency.

Example

use tmpl_resolver::TemplateResolver;

let file = "tmp.bincode";

TemplateResolver::decode_bin(file).expect("Failed to decode bincode file to TemplateResolver");

impl TemplateResolver

pub fn decode_bin_from_slice(slice: &[u8]) -> ResolverResult<(Self, usize)>

Available on crate feature bincode only.

Decodes binary data into TemplateResolver using bincode’s optimized deserialization.

Input

• slice - Binary input slice containing serialized TemplateResolver data

Output

• A tuple of (deserialized TemplateResolver, amount of bytes read) on success
• Error details if deserialization fails

See also: bincode::serde::decode_from_slice

pub fn encode_bin_to_vec(&self) -> ResolverResult<Vec<u8>>

Available on crate feature bincode only.

Encodes the Self(TemplateResolver) into a binary format stored in a Vec<u8>.

Example

use tmpl_resolver::TemplateResolver;

let res: TemplateResolver =
  [("🐱", "喵 ฅ(°ω°ฅ)"), ("hello", "{🐱}")].try_into()?;

let _data = res.encode_bin_to_vec()?;

See also: bincode::serde::encode_to_vec

impl TemplateResolver

pub fn try_from_slice(raw: &[(&str, &str)]) -> ResolverResult<Self>

Construct from slice (no_std compatible)

use tap::Pipe;
use tmpl_resolver::TemplateResolver;

let res = [
  ("🐱", "喵 ฅ(°ω°ฅ)"),
  ("hello", "Hello {🐱}"),
]
 .as_ref()
 .pipe(TemplateResolver::try_from_slice)?;

let text = res.get_with_context("hello", &[])?;
assert_eq!(text, "Hello 喵 ฅ(°ω°ฅ)");

pub fn try_from_str_entries<K, V, I>(iter: I) -> ResolverResult<Self>

where K: AsRef<str>, V: AsRef<str>, I: Iterator<Item = (K, V)>,

Attempts to build a TemplateResolver from raw unprocessed key-value entries.

Process Flow

1. Accepts an iterator of raw (key, value) pairs
2. Parses each value into template AST (Abstract Syntax Tree)
3. Converts keys to normalized format
4. Collects results into a TemplateAST
5. Constructs the final resolver

Parameters

• iter: Iterator over raw unvalidated entries.
  • e.g., [(k1, v1), (k2, v2)].into_iter()

Type Constraints

• K: Key type with string-like representation
• V: Raw value type containing template text
• I: Iterator providing raw configuration entries

Example

use tap::Pipe;
use tmpl_resolver::{TemplateResolver, resolver::MiniStr, resolver::BTreeRawMap};


let res = r##"
  "🐱" = "喵 ฅ(°ω°ฅ)"

  "问候" = """
$period ->
  [morning] 早安{🐱}
  [night] 晚安{🐱}
  *[other] {$period}好
  """

  "称谓" = """
  $gender ->
[male] 先生
[female] 女士
*[test] { $🧑‍🏫 }
  """

  greeting = "{ 问候 }！{ $name }{ 称谓 }。"
"##
  .pipe(toml::from_str::<BTreeRawMap>)?
  .into_iter()
  .pipe(TemplateResolver::try_from_str_entries)?;

assert_eq!(res.try_get("🐱")?, "喵 ฅ(°ω°ฅ)");

See also:

• Self::try_from_slice
• Self::try_from_raw

impl TemplateResolver

pub fn get_with_context( &self, var_name: &str, context: &[(&str, &str)], ) -> ResolverResult<MiniStr>

Core resolution method

If the context is empty, you can directly use Self::try_get.

Algorithm

1. Context sorting for O(log n) parameter lookups
2. Recursive template evaluation
3. Branch prediction for conditional blocks

Example

use tmpl_resolver::{TemplateResolver, error::ResolverError};

let res: TemplateResolver = [
  ("h", "Hello"),
  ("greeting", "{h} {$🐱}"),
]
.try_into()?;

let ctx = [("🐱", "喵 ฅ(°ω°ฅ)")];

let text = res.get_with_context("greeting", &ctx)?;
assert_eq!(text, "Hello 喵 ฅ(°ω°ฅ)");

See also: Self::get_with_ctx_map

pub fn get_with_ctx_btree_map( &self, var_name: &str, context_map: &BTreeRawMap, ) -> ResolverResult<MiniStr>

Similar to Self::get_with_context, but the context is BTreeMap<MiniStr, MiniStr> instead of &[(&str, &str)].

pub fn try_get(&self, var_name: &str) -> ResolverResult<MiniStr>

Similar to Self::get_with_context, but no context.

Example

use tmpl_resolver::{TemplateResolver, error::ResolverError};

let res: TemplateResolver = [
  ("🐱", "ฅ(°ω°ฅ)"),
  ("hi", "Hello"),
  ("greeting", "{ hi } { 🐱 }"),
]
.try_into()?;

let text = res.try_get("greeting")?;
assert_eq!(text, "Hello ฅ(°ω°ฅ)");

pub fn get_with_ctx_map( &self, var_name: &str, context_map: &ContextMap<'_>, ) -> ResolverResult<MiniStr>

Available on crate feature std only.

Similar to Self::get_with_context, but the context is &ContextMap instead of &[(&str, &str)].

If the parameter you need to pass is a Context HashMap that owns the data internally (e.g., HashMap<KString, CompactString>), instead of HashMap<&str, &str>, please use Self::get_with_ctx_map_buf.

Example

use tmpl_resolver::TemplateResolver;

let res: TemplateResolver = [
  ("g", "Good"),
  ("greeting", "{g} { time-period }! { $name }"),
  (
    "time-period",
    "$period ->
      [morning] Morning
      *[other] {$period}",
  ),
]
.try_into()?;

let ctx_map = [("name", "Tom"), ("period", "night")]
  .into_iter()
  .collect();

let text = res.get_with_ctx_map("greeting", &ctx_map)?;
assert_eq!(text, "Good night! Tom");

pub fn get_with_ctx_map_buf( &self, var_name: &str, context_map: &ContextMapBuf, ) -> ResolverResult<MiniStr>

Available on crate feature std only.

Similar to Self::get_with_ctx_map, but the context is &ContextMapBuf instead of &ContextMap.

Example

use tmpl_resolver::TemplateResolver;

let res: TemplateResolver = [
  ("greeting", "{$hi} { $name }"),
]
.try_into()?;

let ctx_map = [("name", "Tom"), ("hi", "Hello!")]
  .into_iter()
  .map(|(k, v)| (k.into(), v.into()) )
  .collect();

let text = res.get_with_ctx_map("greeting", &ctx_map)?;
assert_eq!(text, "Hello! Tom");

impl TemplateResolver

pub fn into_btree_map(self) -> OrderedAST

Converts the resolver into a BTreeMap.

An ordered BTreeMap is useful when you need to serialize the TemplateResolver to a configuration file or a binary file.

Example

use tmpl_resolver::TemplateResolver;

let resolver = TemplateResolver::default();
let _map = resolver.into_btree_map();

pub fn into_inner(self) -> TemplateAST

Takes ownership of the Self and returns the inner data (template AST)

Example

use tmpl_resolver::TemplateResolver;

let resolver = TemplateResolver::default();
let _inner_data = resolver.into_inner();

impl TemplateResolver

pub fn try_from_raw<K, V, I>(iter: I) -> ResolverResult<Self>

where K: Into<KString> + Display, V: AsRef<str>, I: IntoIterator<Item = (K, V)>,

Available on crate feature std only.

Construct from IntoIterator<(K, V)>, e.g., HashMap

Example

use tmpl_resolver::TemplateResolver;
use tap::pipe::Pipe;

let resolver = [
   (
     "salutation",
     "
     $gender ->
       [male] Mr.
       *[female] Ms.",
   ),
   ("g", "Good"),
   (
     "time-greeting",
     "$period ->
       [morning] {g} Morning
       [evening] {g} Evening
       *[other] {g} {$period}
     ",
   ),
   ("greeting", "{ time-greeting }! { salutation }{ $name }"),
 ]
 // .into_iter()
 // .map(|(k, v)| (k.into(), v.into()))
 // .collect::<tmpl_resolver::resolver::AHashRawMap>()
 .pipe(TemplateResolver::try_from_raw)?;

let text = resolver
   .get_with_context(
     "greeting",
     &[
       ("period", "evening"),
       ("name", "Alice"),
       ("gender", "unknown"),
     ],
   )
   .expect("Failed to get text");

assert_eq!(text, "Good Evening! Ms.Alice");

Methods from Deref<Target = TemplateAST>

pub fn capacity(&self) -> usize

Returns the number of elements the map can hold without reallocating.

This number is a lower bound; the HashMap<K, V> might be able to hold more, but is guaranteed to be able to hold at least this many.

Examples

use std::collections::HashMap;
let map: HashMap<i32, i32> = HashMap::with_capacity(100);
assert!(map.capacity() >= 100);

pub fn keys(&self) -> Keys<'_, K, V>

An iterator visiting all keys in arbitrary order. The iterator element type is &'a K.

Examples

use std::collections::HashMap;

let map = HashMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for key in map.keys() {
    println!("{key}");
}

Performance

In the current implementation, iterating over keys takes O(capacity) time instead of O(len) because it internally visits empty buckets too.

pub fn values(&self) -> Values<'_, K, V>

An iterator visiting all values in arbitrary order. The iterator element type is &'a V.

Examples

use std::collections::HashMap;

let map = HashMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for val in map.values() {
    println!("{val}");
}

Performance

In the current implementation, iterating over values takes O(capacity) time instead of O(len) because it internally visits empty buckets too.

pub fn iter(&self) -> Iter<'_, K, V>

An iterator visiting all key-value pairs in arbitrary order. The iterator element type is (&'a K, &'a V).

Examples

use std::collections::HashMap;

let map = HashMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for (key, val) in map.iter() {
    println!("key: {key} val: {val}");
}

Performance

In the current implementation, iterating over map takes O(capacity) time instead of O(len) because it internally visits empty buckets too.

pub fn len(&self) -> usize

Returns the number of elements in the map.

Examples

use std::collections::HashMap;

let mut a = HashMap::new();
assert_eq!(a.len(), 0);
a.insert(1, "a");
assert_eq!(a.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

Examples

use std::collections::HashMap;

let mut a = HashMap::new();
assert!(a.is_empty());
a.insert(1, "a");
assert!(!a.is_empty());

pub fn hasher(&self) -> &S

Returns a reference to the map’s BuildHasher.

Examples

use std::collections::HashMap;
use std::hash::RandomState;

let hasher = RandomState::new();
let map: HashMap<i32, i32> = HashMap::with_hasher(hasher);
let hasher: &RandomState = map.hasher();

pub fn get<Q>(&self, k: &Q) -> Option<&V>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Returns a reference to the value corresponding to the key.

The key may be any borrowed form of the map’s key type, but Hash and Eq on the borrowed form must match those for the key type.

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.get(&2), None);

pub fn get_key_value<Q>(&self, k: &Q) -> Option<(&K, &V)>

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Returns the key-value pair corresponding to the supplied key. This is potentially useful:

• for key types where non-identical keys can be considered equal;
• for getting the &K stored key value from a borrowed &Q lookup key; or
• for getting a reference to a key with the same lifetime as the collection.

The supplied key may be any borrowed form of the map’s key type, but Hash and Eq on the borrowed form must match those for the key type.

Examples

use std::collections::HashMap;
use std::hash::{Hash, Hasher};

#[derive(Clone, Copy, Debug)]
struct S {
    id: u32,
    name: &'static str, // ignored by equality and hashing operations
}

impl PartialEq for S {
    fn eq(&self, other: &S) -> bool {
        self.id == other.id
    }
}

impl Eq for S {}

impl Hash for S {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.id.hash(state);
    }
}

let j_a = S { id: 1, name: "Jessica" };
let j_b = S { id: 1, name: "Jess" };
let p = S { id: 2, name: "Paul" };
assert_eq!(j_a, j_b);

let mut map = HashMap::new();
map.insert(j_a, "Paris");
assert_eq!(map.get_key_value(&j_a), Some((&j_a, &"Paris")));
assert_eq!(map.get_key_value(&j_b), Some((&j_a, &"Paris"))); // the notable case
assert_eq!(map.get_key_value(&p), None);

pub fn contains_key<Q>(&self, k: &Q) -> bool

where K: Borrow<Q>, Q: Hash + Eq + ?Sized,

Returns true if the map contains a value for the specified key.

The key may be any borrowed form of the map’s key type, but Hash and Eq on the borrowed form must match those for the key type.

Examples

use std::collections::HashMap;

let mut map = HashMap::new();
map.insert(1, "a");
assert_eq!(map.contains_key(&1), true);
assert_eq!(map.contains_key(&2), false);

Trait Implementations

impl Clone for TemplateResolver

fn clone(&self) -> TemplateResolver

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TemplateResolver

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TemplateResolver

fn default() -> TemplateResolver

Returns the “default value” for a type.

impl Deref for TemplateResolver

type Target = HashMap<KStringBase<Box<str>>, Template, RandomState>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'de> Deserialize<'de> for TemplateResolver

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<TemplateResolver> for OrderedAST

Converts the resolver into an ordered abstract syntax tree (AST) representation.

Feature-dependent Behavior

• ​With std feature: Converts internal storage to a alloc::collections::BTreeMap-backed ordered AST through iterative collection. This guarantees deterministic ordering.
• ​Without std feature: Directly returns the pre-ordered AST structure without conversion, optimized for no_std environments.

fn from(value: TemplateResolver) -> Self

Converts to this type from the input type.

impl PartialEq for TemplateResolver

fn eq(&self, other: &TemplateResolver) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for TemplateResolver

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&[(&str, &str)]> for TemplateResolver

type Error = ResolverError

The type returned in the event of a conversion error.

fn try_from(value: &[(&str, &str)]) -> Result<Self, Self::Error>

Performs the conversion.

impl<const N: usize> TryFrom<[(&str, &str); N]> for TemplateResolver

type Error = ResolverError

The type returned in the event of a conversion error.

fn try_from(value: [(&str, &str); N]) -> Result<Self, Self::Error>

Performs the conversion.

impl<K, V, S> TryFrom<AHashMap<K, V, S>> for TemplateResolver

where K: Into<KString> + Display, V: AsRef<str>,

Available on crate feature std only.

type Error = ResolverError

The type returned in the event of a conversion error.

fn try_from(value: AHashMap<K, V, S>) -> Result<Self, Self::Error>

Performs the conversion.

impl<K, V> TryFrom<BTreeMap<K, V>> for TemplateResolver

where K: AsRef<str>, V: AsRef<str>,

type Error = ResolverError

The type returned in the event of a conversion error.

fn try_from(value: BTreeMap<K, V>) -> Result<Self, Self::Error>

Performs the conversion.

impl<K, V, S> TryFrom<HashMap<K, V, S>> for TemplateResolver

where K: Into<KString> + Display, V: AsRef<str>,

Available on crate feature std only.

type Error = ResolverError

The type returned in the event of a conversion error.

fn try_from(value: StdHashMap<K, V, S>) -> Result<Self, Self::Error>

Performs the conversion.

impl<K, V> TryFrom<Vec<(K, V)>> for TemplateResolver

where K: Into<KString> + Display, V: AsRef<str>,

Available on crate feature std only.

type Error = ResolverError

The type returned in the event of a conversion error.

fn try_from(value: Vec<(K, V)>) -> Result<Self, Self::Error>

Performs the conversion.

impl StructuralPartialEq for TemplateResolver