Handlebars-rust

https://github.com/sunng87/handlebars-rust
Admin
Handlebars-rust is a Rust implementation of the Handlebars templating language, providing robust...
Tokens:92,355
Snippets:624
Trust Score:10
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Usage examples

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/output.md

Examples of using the Output trait and its implementations: custom output sink, streaming to a file, and writing from a helper.

```APIDOC
## Usage examples

### Custom output sink
```rust
use handlebars::*;
use std::io::{Cursor, Write};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    struct ByteCounter { count: usize }
    impl Output for ByteCounter {
        fn write(&mut self, seg: &str) -> std::io::Result<()> {
            self.count += seg.len();
            Ok(())
        }
    }

    let mut hbs = Handlebars::new();
    hbs.register_template_string("t", "hello {{name}}")?;

    let mut counter = ByteCounter { count: 0 };
    hbs.render_to_write("t", &serde_json::json!({"name": "world"}), &mut counter)?;
    assert_eq!(counter.count, "hello world".len());
    Ok(())
}
```

### Streaming render to a file
```rust
use handlebars::Handlebars;
use std::fs::File;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hbs = Handlebars::new();
    hbs.register_template_string("page", "<html>{{title}}</html>")?;

    let file = File::create("out.html")?;
    hbs.render_to_write("page", &serde_json::json!({"title": "Doc"}), file)?;
    Ok(())
}
```

### Writing from a helper
```rust
use handlebars::*;
use std::io::Write;

fn separator(_: &Helper<'_>, _: &Handlebars<'_>, _: &Context,
             _: &mut RenderContext<'_, '_>, out: &mut dyn Output) -> HelperResult {
    out.write("\n---\n")?;          // Output::write
    Ok(())
}
```
```

--------------------------------

### Parsing and Matching Paths Example

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/path.md

Demonstrates how to parse various path types and match them against Path variants.

```rust
use handlebars::{Path, PathSeg, RenderContext, ScopedJson, Context};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = Path::parse("a/b/c")?;
    assert!(matches!(path, Path::Relative(_)));

    let local = Path::parse("@index")?;
    assert!(matches!(local, Path::Local((0, ref name, _)) if name == "index"));

    let up = Path::parse("../../d")?;
    assert!(matches!(up, Path::Local((2, ref name, _)) if name == "d"));

    // inspecting relative-path segments
    if let Path::Relative((segs, raw)) = Path::parse("./addr/[country]")? {
        assert_eq!(raw, "./addr/[country]");
        assert!(matches!(&segs[0], PathSeg::Named(n) if n == "addr"));
        assert!(matches!(&segs[1], PathSeg::Named(n) if n == "country"));
    }
    Ok(())
}
```

--------------------------------

### Quick Start with Handlebars

Source: https://github.com/sunng87/handlebars-rust/blob/master/README.md

Demonstrates basic template rendering using the Handlebars registry and template registration.

```rust
use handlebars::Handlebars;
use serde_json::json;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    let mut reg = Handlebars::new();
    // render without register
    println!(
        "{}",
        reg.render_template("Hello {{name}}", &json!({"name": "foo"}))?
    );

    // register template using given name
    reg.register_template_string("tpl_1", "Good afternoon, {{name}}")?;
    println!("{}", reg.render("tpl_1", &json!({"name": "foo"}))?);

    Ok(())
}
```

--------------------------------

### Error handling example

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/errors.md

An example demonstrating how to create a helper that returns a nested custom error and how to inspect and downcast the error reason when rendering fails.

```APIDOC
## Error Handling Example

### Description
This example shows how to define a helper that returns a `RenderError` with a nested custom error, and how to inspect the error reason and downcast the nested source.

### Code
```rust
use handlebars::{Handlebars, RenderError, RenderErrorReason};
use thiserror::Error;

#[derive(Debug, Error)]
enum HelperError {
    #[error("db error")]
    DbError,
}

// helper that fails with a nested custom error
fn error_helper(h: &Helper, _: &Handlebars, _: &Context,
                _: &mut RenderContext, _: &mut dyn Output) -> Result<(), RenderError> {
    match h.param(0).and_then(|v| v.value().as_str()) {
        Some("db") => Err(RenderErrorReason::NestedError(Box::new(HelperError::DbError)).into()),
        _ => Ok(()),
    }
}

fn main() {
    let mut hbs = Handlebars::new();
    hbs.register_helper("err", Box::new(error_helper));
    hbs.register_template_string("t", "{{err db}}").unwrap();

    match hbs.render("t", &()) {
        Err(e) => {
            // inspect the reason, then downcast the nested source
            if let RenderErrorReason::NestedError(cause) = e.reason() {
                assert!(cause.downcast_ref::<HelperError>().is_some());
                println!("{}", e); // "Nested error: db error"
            }
        }
        Ok(_) => unreachable!(),
    }
}
```
```

--------------------------------

### EachHelper usage examples

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/builtin-helpers.md

Demonstrates iteration over arrays and objects, including the use of block parameters and the inverse branch for empty collections.

```handlebars
{{#each items}}[{{@index}}] {{this}}{{#unless @last}}, {{/unless}}{{/each}}
{{#each dict as |v k|}}{{k}}={{v}}; {{/each}}
{{#each empty_list}}x{{else}}nothing{{/each}}
```

--------------------------------

### IfHelper usage examples

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/builtin-helpers.md

Demonstrates conditional rendering with if, else if, and else branches, as well as the includeZero option for truthiness evaluation.

```handlebars
{{#if user}}Hello {{user.name}}{{else if guest}}Hello guest{{else}}Goodbye{{/if}}
{{#if score includeZero=true}}0 is truthy here{{/if}}
```

--------------------------------

### WithHelper usage examples

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/builtin-helpers.md

Demonstrates changing the evaluation context using the with helper, with and without block parameters.

```handlebars
{{#with address}}{{city}}, {{country}}{{/with}}
{{#with settings as |s|}}{{s.theme}}{{/with}}
```

--------------------------------

### Implement a block helper with block parameters

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/block.md

This example demonstrates creating a block helper that exposes a block parameter, similar to the built-in #each or #with helpers.

```rust
use handlebars::*;
use serde_json::json;

fn with_city<'reg: 'rc, 'rc>(
    h: &Helper<'rc>,
    r: &'reg Handlebars<'reg>,
    ctx: &'rc Context,
    rc: &mut RenderContext<'reg, 'rc>,
    out: &mut dyn Output,
) -> HelperResult {
    let v = h.param(0)
        .ok_or(RenderErrorReason::ParamNotFoundForIndex("with_city", 0))?;

    let mut block = BlockContext::new();
    if let Some(path) = v.context_path() {
        block.base_path_mut().clone_from(path);
    } else {
        block.set_base_value(v.value().clone());
    }

    // {{#with_city addr as |the_city|}} exposes {{the_city.city}}
    if let Some(bp) = h.block_param() {
        let mut params = BlockParams::new();
        params.add_value(bp, v.value().clone())?;
        block.set_block_params(params);
    }

    rc.push_block(block);
    let result = h.template().map(|t| t.render(r, ctx, rc, out)).unwrap_or(Ok(()));
    rc.pop_block();
    result
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hbs = Handlebars::new();
    hbs.register_helper("with_city", Box::new(with_city));
    hbs.register_template_string("t", "{{#with_city addr as |c|}}{{c.city}}{{/with_city}}")?;
    println!("{}", hbs.render("t", &json!({"addr": {"city": "Hangzhou"}}))?);
    Ok(())
}
```

--------------------------------

### Reusing Context across render calls

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/context.md

Example demonstrating how to build a Context once and reuse it for multiple template rendering operations.

```rust
use handlebars::{Context, Handlebars};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let hbs = Handlebars::new();
    let data = serde_json::json!([0, 1, 2, 3]);

    // build once ...
    let ctx = Context::from(data);

    assert_eq!(
        hbs.render_template_with_context("{{#each this}}{{this}}{{/each}}", &ctx)?,
        "0123"
    );

    let mut reg = Handlebars::new();
    reg.register_template_string("t0", "{{#each this}}{{this}}{{/each}}")?;
    assert_eq!(reg.render_with_context("t0", &ctx)?, "0123");
    Ok()
}
```

--------------------------------

### Path Parsing Validation Example

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/path.md

Validates that Path::parse accepts standard template path syntax.

```rust
use handlebars::{Context, Handlebars, Path};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let hbs = Handlebars::new();
    let ctx = Context::wraps(serde_json::json!({"user": {"name": "Ada"}}))?;

    // render_template_with_context resolves paths internally; here we
    // just prove Path::parse accepts the same syntax used in templates
    assert!(Path::parse("user.name").is_ok());
    assert!(Path::parse("user.[name]").is_ok());
    assert!(Path::parse("@root/user").is_ok());
    assert!(Path::parse("this.[2]").is_ok());
    assert!(Path::parse("bad path!").is_err());
    Ok(())
}
```

--------------------------------

### End-to-end error handling example

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/errors.md

Demonstrates how to define a custom helper error, register it, and inspect the nested source error using RenderErrorReason::NestedError.

```rust
use handlebars::{Handlebars, RenderError, RenderErrorReason};
use thiserror::Error;

#[derive(Debug, Error)]
enum HelperError {
    #[error("db error")]
    DbError,
}

// helper that fails with a nested custom error
fn error_helper(h: &Helper, _: &Handlebars, _: &Context,
                _: &mut RenderContext, _: &mut dyn Output) -> Result<(), RenderError> {
    match h.param(0).and_then(|v| v.value().as_str()) {
        Some("db") => Err(RenderErrorReason::NestedError(Box::new(HelperError::DbError)).into()),
        _ => Ok(()),
    }
}

fn main() {
    let mut hbs = Handlebars::new();
    hbs.register_helper("err", Box::new(error_helper));
    hbs.register_template_string("t", "{{err db}}").unwrap();

    match hbs.render("t", &()) {
        Err(e) => {
            // inspect the reason, then downcast the nested source
            if let RenderErrorReason::NestedError(cause) = e.reason() {
                assert!(cause.downcast_ref::<HelperError>().is_some());
                println!("{}", e); // "Nested error: db error"
            }
        }
        Ok(_) => unreachable!(),
    }
}
```

--------------------------------

### Custom Output sink implementation

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/output.md

Example of implementing the Output trait for a custom struct to track rendering metrics like byte counts.

```rust
use handlebars::*;
use std::io::{Cursor, Write};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    struct ByteCounter { count: usize }
    impl Output for ByteCounter {
        fn write(&mut self, seg: &str) -> std::io::Result<()> {
            self.count += seg.len();
            Ok(())
        }
    }

    let mut hbs = Handlebars::new();
    hbs.register_template_string("t", "hello {{name}}")?;

    let mut counter = ByteCounter { count: 0 };
    hbs.render_to_write("t", &serde_json::json!({"name": "world"}), &mut counter)?;
    assert_eq!(counter.count, "hello world".len());
    Ok(())
}
```

--------------------------------

### Mutating Context data in a decorator

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/context.md

Example showing how to clone and mutate context data within a custom decorator.

```rust
use handlebars::*;

fn add_field<'reg: 'rc, 'rc>(
    _: &Decorator,
    _: &Handlebars,
    ctx: &Context,
    rc: &mut RenderContext,
) -> Result<(), RenderError> {
    let mut new_ctx = ctx.clone();
    {
        let m = new_ctx.data_mut().as_object_mut().expect("object data");
        m.insert("banner".into(), to_json("fresh"));
    }
    rc.set_context(new_ctx);
    Ok(())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hbs = Handlebars::new();
    hbs.register_decorator("add_field", Box::new(add_field));
    hbs.register_template_string("t", "[{{before}}|{{*add_field}}{{after}}]")?;
    println!("{}", hbs.render("t", &serde_json::json!({"before": 1, "after": 2}))?);
    Ok(())
}
```

--------------------------------

### Mode Configuration Methods

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Methods to get and set registry mode flags: strict mode, dev mode, recursive lookup, and prevent indent.

```APIDOC
## Mode Configuration Methods

### Description
Methods to get and set registry mode flags: strict mode, dev mode, recursive lookup, and prevent indent.

### Methods

#### set_strict_mode
- Signature: pub fn set_strict_mode(&mut self, enabled: bool)
- Default: false
- Behavior: When true, rendering a missing value raises RenderError instead of rendering an empty string.

#### strict_mode
- Signature: pub fn strict_mode(&self) -> bool
- Default: false

#### set_dev_mode
- Signature: pub fn set_dev_mode(&mut self, enabled: bool)
- Default: false
- Behavior: Must be enabled before registering templates; reloads file/embed/script sources on each visit. Disabling clears template_sources.

#### dev_mode
- Signature: pub fn dev_mode(&self) -> bool
- Default: false

#### set_recursive_lookup
- Signature: pub fn set_recursive_lookup(&mut self, enabled: bool)
- Default: false
- Behavior: When true, variable resolution walks up enclosing scopes until a match is found.

#### recursive_lookup
- Signature: pub fn recursive_lookup(&self) -> bool
- Default: false

#### set_prevent_indent
- Signature: pub fn set_prevent_indent(&mut self, enable: bool)
- Default: false
- Behavior: When true, leading whitespace of partial include lines is preserved instead of auto-indenting.

#### prevent_indent
- Signature: pub fn prevent_indent(&self) -> bool
- Default: false

```

--------------------------------

### Inspecting rendering errors

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/testing.md

Example of using error-returning assertions to inspect RenderError metadata and verify error messages.

```rust
use handlebars::{Handlebars, RenderErrorReason};
use handlebars::testing::TestHandlebars;
use serde_json::json;

#[test]
fn strict_mode_cases() {
    let mut hbs = Handlebars::new();

    hbs.assert_render_template_ok("{{#each data}}{{/each}}", &json!({}));

    hbs.set_strict_mode(true);
    let err = hbs.assert_render_template_err(
        "{{#each data}}{{/each}}",
        &json!({}),
        None,                       // no message filter
    );
    assert!(matches!(err.reason(), RenderErrorReason::MissingVariable(_)));

    // optional error-message substring check
    hbs.assert_render_template_err("{{missing}}", &json!({}), Some("MissingVariable"));
}
```

--------------------------------

### Catching errors in consumer code

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/errors.md

Example Rust code demonstrating how to catch template registration and render errors, and access error details such as reason, position, and template name.

```APIDOC
## Catching errors in consumer code

### Description
Example Rust code showing how to handle template registration and render errors using the handlebars crate.

### Code
```rust
use handlebars::{Handlebars, RenderErrorReason, TemplateErrorReason};

// Template *registration* errors:
match hbs.register_template_string("t", "{{#if}}") {
    Err(e) => {
        let reason = e.reason();            // &TemplateErrorReason
        let pos = e.pos();                  // Option<(line, col)>
        let name = e.name();                // Option<&String> (template name)
        // ...
    }
    Ok(_) => {}
}

// Render errors:
match hbs.render("t", &data) {
    Err(e) => {
        let reason = e.reason();            // &RenderErrorReason
        let line = e.line_no;               // Option<usize>
        let col = e.column_no;              // Option<usize>
        let tpl = e.template_name.as_deref(); // Option<&str>
        // match reason with matches!(reason, RenderErrorReason::TemplateNotFound(name))
    }
    Ok(_) => {}
}
```
```

--------------------------------

### Handling serialization failure

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/context.md

Example of catching a serialization error when wrapping a type that fails to serialize.

```rust
use handlebars::{Context, RenderErrorReason};

// any type whose Serialize impl errors out
let err = Context::wraps(FailingSerialize).unwrap_err();
assert!(matches!(err.reason(), RenderErrorReason::SerdeError(_)));
```

--------------------------------

### Basic Template Registration and Rendering

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Demonstrates how to initialize a Handlebars registry, render a template directly, and register a template string for later use.

```rust
use handlebars::Handlebars;
use serde_json::json;
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    let mut reg = Handlebars::new();
    // render without register
    println!("{}", reg.render_template("Hello {{name}}", &json!({"name": "foo"}))?);

    // register template using given name
    reg.register_template_string("tpl_1", "Good afternoon, {{name}}")?;
    println!("{}", reg.render("tpl_1", &json!({"name": "foo"}))?);
    Ok(())
}
```

--------------------------------

### Directory Registration with Builder

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Shows how to register all templates in a directory using the DirectorySourceOptionsBuilder to specify file extensions.

```rust
use handlebars::{Handlebars, DirectorySourceOptionsBuilder};

let mut hbs = Handlebars::new();
hbs.register_templates_directory(
    "/path/to/templates",
    DirectorySourceOptionsBuilder::default()
        .tpl_extension("hbs")
        .build()
        .unwrap(),
).unwrap();
```

--------------------------------

### Basic usage of handlebars_helper!

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/macros.md

Demonstrates defining and registering simple helpers with positional and hash parameters.

```rust
use handlebars::{handlebars_helper, Handlebars};
use serde_json::json;

handlebars_helper!(is_above_10: |x: u64| x > 10);
handlebars_helper!(is_above: |x: u64, { compare: u64 = 10 }| x > compare);

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut handlebars = Handlebars::new();
    handlebars.register_helper("is-above-10", Box::new(is_above_10));
    handlebars.register_helper("is-above", Box::new(is_above));

    let result = handlebars
        .render_template("{{#if (is-above-10 12)}}great!{{else}}okay{{/if}}", &json!({}))?;
    assert_eq!(&result, "great!");

    let result2 = handlebars
        .render_template("{{#if (is-above 12 compare=10)}}great!{{else}}okay{{/if}}", &json!({}))?;
    assert_eq!(&result2, "great!");
    Ok(())
}
```

--------------------------------

### Using *args and **kwargs in handlebars_helper!

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/macros.md

Shows how to capture arbitrary positional arguments using *args and hash arguments using **kwargs.

```rust
use handlebars::{handlebars_helper, Handlebars};
use serde_json::json;
use std::collections::BTreeMap;

handlebars_helper!(sum_all: |*args: Vec<&serde_json::Value>|
    args.iter().filter_map(|v| v.as_i64()).sum::<i64>());

handlebars_helper!(describe: |x: str, **kwargs: BTreeMap<&str, &serde_json::Value>|
    format!("{} with {} extras", x, kwargs.len()));

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hbs = Handlebars::new();
    hbs.register_helper("sum_all", Box::new(sum_all));
    hbs.register_helper("describe", Box::new(describe));
    println!("{}", hbs.render_template("{{sum_all 1 2 3 4}}", &json!({}))?);      // 10
    println!("{}", hbs.render_template("{{describe \"hi\" a=1 b=2}}", &json!({}))?); // hi with 2 extras
    Ok(())
}
```

--------------------------------

### Helper Returning Typed ScopedJson

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/json-value.md

Example of a custom helper that returns a ScopedJson value, demonstrating strict-mode awareness.

```rust
use handlebars::*;
use serde_json::json;

fn shout(h: &Helper<'_>, _: &Handlebars<'_>, _: &Context,
         _: &mut RenderContext<'_, '_>) -> Result<ScopedJson<'_>, RenderError> {
    let v = h.param(0)
        .ok_or(RenderErrorReason::ParamNotFoundForIndex("shout", 0))?;
    if v.is_value_missing() {
        return Ok(ScopedJson::Missing);           // strict-mode aware
    }
    Ok(ScopedJson::Derived(json!(v.value().to_string().to_uppercase())))
}
```

--------------------------------

### Context constructors

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/context.md

Methods to initialize a new Context instance.

```rust
pub fn null() -> Context                                // src/context.rs:179
pub fn wraps<T: Serialize>(e: T) -> Result<Context, RenderError>   // src/context.rs:184
```

--------------------------------

### Truthiness Checks with JsonTruthy

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/json-value.md

Examples of using the is_truthy method on various JSON values, including handling of zero and empty collections.

```rust
use handlebars::json::value::JsonTruthy;
use serde_json::json;

assert!(json!(1).is_truthy(false));
assert!(!json!(0).is_truthy(false));
assert!(json!(0).is_truthy(true));     // include_zero
assert!(!json!("").is_truthy(false));
assert!(json!([] ).is_truthy(false) == false);  // empty array falsey
```

--------------------------------

### Registry::new

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Creates a new empty Registry and registers built-in helpers and decorators.

```APIDOC
## Registry::new

### Description
Creates a new empty Registry and registers built-in helpers and decorators.

### Method
new

### Signature
pub fn new() -> Registry<'reg>

### Notes
- Registers built-in helpers: if, unless, each, with, lookup, raw, log, eq, ne, gt, gte, lt, lte, and, or, not, len (plus 8 string helpers with feature string_helpers).
- Registers built-in decorator: inline.

```

--------------------------------

### String rendering via renders

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/renderable.md

Shows how to perform direct string rendering using the default renders method on a compiled template.

```rust
use handlebars::*;
use std::rc::Rc;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let hbs = Handlebars::new();
    let tpl = Template::compile("Hello {{name}}")?;
    let ctx = Context::wraps(serde_json::json!({"name": "Ning"}))?;
    let mut rc = RenderContext::new(None);
    let out = tpl.renders(&hbs, &ctx, &mut rc)?;
    assert_eq!(out, "Hello Ning");
    Ok(())
}
```

--------------------------------

### render

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Renders a registered template by name into a String using StringOutput. Data must implement serde::Serialize.

```APIDOC
## render

### Description
Renders a registered template by name into a String (via StringOutput).

### Method
Rust method

### Signature
pub fn render<T>(&self, name: &str, data: &T) -> Result<String, RenderError>
where
    T: Serialize,

### Parameters
- **name** (&str) - Required - The name of the registered template.
- **data** (&T) - Required - The data to render, must implement serde::Serialize.

### Return Value
Result<String, RenderError> - The rendered string or a RenderError.

```

--------------------------------

### Template::new

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/template.md

Creates an empty Template instance. This is equivalent to Template::default().

```APIDOC
## Template::new

### Description
Creates an empty Template instance. This is equivalent to Template::default().

### Method
new

### Signature
pub fn new() -> Template

### Returns
- Template - An empty template.

```

--------------------------------

### Streaming render to file

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/output.md

Demonstrates using render_to_write to stream template output directly into a file.

```rust
use handlebars::Handlebars;
use std::fs::File;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hbs = Handlebars::new();
    hbs.register_template_string("page", "<html>{{title}}</html>")?;

    let file = File::create("out.html")?;
    hbs.render_to_write("page", &serde_json::json!({"title": "Doc"}), file)?;
    Ok(())
}
```

--------------------------------

### Context From implementation

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/context.md

Conversion from Json to Context, avoiding fallible serialization.

```rust
impl From<Json> for Context { fn from(data: Json) -> Context }
```

--------------------------------

### render_with_context_to_write

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Streams the rendered output of a registered template using a pre-built Context into a writer.

```APIDOC
## render_with_context_to_write

### Description
Streams the rendered output of a registered template using a pre-built Context into a writer.

### Method
Rust method

### Signature
pub fn render_with_context_to_write<W>(&self, name: &str, ctx: &Context, writer: W) -> Result<(), RenderError>
where
    W: Write,

### Parameters
- **name** (&str) - Required - The name of the registered template.
- **ctx** (&Context) - Required - The pre-built context to use.
- **writer** (W) - Required - The writer to write the output to, must implement std::io::Write.

### Return Value
Result<(), RenderError> - Ok if successful, or a RenderError.

```

--------------------------------

### RenderContext.context() and RenderContext.set_context()

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/render-context.md

Shows how a decorator can modify the render context by cloning the current context, inserting a key-value pair, and replacing the context with copy-on-write semantics.

```APIDOC
## RenderContext.context() and RenderContext.set_context()

### Description
Retrieves the current context and replaces it with a modified copy. This is used in decorators to inject or update context variables.

### Method
context() -> Option<&Context>
set_context(ctx: Context)

### Parameters
- **ctx** (Context) - Required - The new context to set.

### Return Value
- **context()** - Option<&Context> - The current context, if any.

### Usage Example
```rust
use handlebars::*;

fn set_in_context(rc: &mut RenderContext<'_, '_>, key: &str, value: serde_json::Value) {
    let mut gctx = match rc.context() {
        Some(c) => (*c).clone(),
        None => Context::wraps(serde_json::json!({})).unwrap(),
    };
    if let serde_json::Value::Object(m) = gctx.data_mut() {
        m.insert(key.to_string(), value);
        rc.set_context(gctx);   // copy-on-write context replacement
    }
}
```
```

--------------------------------

### Usage of string case helpers

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/builtin-helpers.md

Converts strings using various case formats provided by the heck crate. Requires the string_helpers feature to be enabled.

```handlebars
{{lowerCamelCase "lower camel case"}}   {{! → lowerCamelCase }}
{{kebabCase "Hello World"}}             {{! → hello-world }}
```

--------------------------------

### engine

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Borrows the rhai Engine. Requires the script_helper feature.

```APIDOC
## engine

### Description
Borrows the rhai Engine. Requires the script_helper feature.

### Method
engine

### Signature
pub fn engine(&self) -> &Engine

### Returns
&Engine - A reference to the rhai Engine.

### Source
src/registry.rs:573
```

--------------------------------

### register_script_helper_file

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Loads the script file; in dev mode the file is recompiled on every call.

```APIDOC
## register_script_helper_file

### Description
Loads the script file; in dev mode the file is recompiled on every call.

### Method
register_script_helper_file

### Signature
pub fn register_script_helper_file<P>(&mut self, name: &str, script_path: P) -> Result<(), ScriptError>
where
    P: AsRef<Path>,

### Parameters
- **name** (&str) - Required - The name of the helper.
- **script_path** (P) - Required - The path to the script file.

### Returns
Result<(), ScriptError> - Ok if successful, otherwise a ScriptError.

### Source
src/registry.rs:554
```

--------------------------------

### Distinguishing Literal Constants from Context References

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/json-value.md

Demonstrates how to inspect helper parameters to determine if they originate from the context or are literal constants.

```rust
use handlebars::*;

fn describe(h: &Helper<'_>, _: &Handlebars<'_>, _: &Context,
            _: &mut RenderContext<'_, '_>, out: &mut dyn Output) -> HelperResult {
    for (i, p) in h.params().iter().enumerate() {
        let origin = if p.relative_path().is_some() { "context" } else { "literal" };
        write!(out, "param{i} from {origin}, ")?;
        if let Some(c) = p.try_get_constant_value() {
            write!(out, "constant: {c}")?;
        }
    }
    Ok(())
}
```

--------------------------------

### Context::from (Json)

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/context.md

Creates a Context from a serde_json::Value without fallible serialization.

```APIDOC
## Context::from (Json)

### Description
Creates a Context from a serde_json::Value without fallible serialization.

### Method
from

### Signature
impl From<Json> for Context { fn from(data: Json) -> Context }

### Parameters
- **data** (Json) - Required - The JSON value to wrap.

### Returns
Context - A Context wrapping the given JSON value.

### Example
```rust
let ctx = Context::from(serde_json::json!([0, 1, 2, 3]));
```
```

--------------------------------

### Writing from a helper

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/output.md

Standard pattern for writing output from within a custom Handlebars helper using the Output trait.

```rust
use handlebars::*;
use std::io::Write;

fn separator(_: &Helper<'_>, _: &Handlebars<'_>, _: &Context,
             _: &mut RenderContext<'_, '_>, out: &mut dyn Output) -> HelperResult {
    out.write("\n---\n")?;          // Output::write
    Ok(())
}
```

--------------------------------

### DirectorySourceOptions

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/configuration.md

Constructor-option struct for register_templates_directory. It configures the template file extension, and whether hidden or temporary files are included.

```APIDOC
## DirectorySourceOptions

### Description
Constructor-option struct for `register_templates_directory`. It configures the template file extension, and whether hidden or temporary files are included.

### Fields
- **tpl_extension** (String) - Optional (has default) - Default: ".hbs" - Filename suffix matched by `register_templates_directory`; stripped from the registered template name. Builder setter accepts `Into<String>` so `"hbs"` and `".hbs"` both work.
- **hidden** (bool) - Optional - Default: false - When `true`, files whose stem starts with `.` are included.
- **temporary** (bool) - Optional - Default: false - When `true`, files whose stem starts with `#` are included.

### Builder Example
```rust
DirectorySourceOptionsBuilder::default()
    .tpl_extension("hbs")
    .hidden(true)
    .build()
    .unwrap();
```

### Plain Construction Example
```rust
DirectorySourceOptions { ..Default::default() }
```
```

--------------------------------

### {{#with value}} ... {{/with}}

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/builtin-helpers.md

Pushes a new block context based on the provided value. If the value is truthy, the block is rendered with the value as the new base context.

```APIDOC
## [with] {{#with value}} ... {{/with}}

### Description
Pushes a new block context based on the provided value. If the value is truthy, the block is rendered with the value as the new base context.

### Parameters
#### Positional Parameters
- **param0** (any) - Required - The value to use as the new context.

### Behavior
- If param0 is missing, raises RenderErrorReason::ParamNotFoundForIndex("with", 0).
- If truthy, pushes a new block whose base is the value (inherits local @key/@index/etc. from the enclosing block). Block param as |v| binds the value.
- If falsey/missing, renders the inverse branch if present; else in strict mode raises RenderError::strict_error(relative_path); else renders nothing.

### Example
```handlebars
{{#with address}}{{city}}, {{country}}{{/with}}
{{#with settings as |s|}}{{s.theme}}{{/with}}
```
```

--------------------------------

### register_template_file

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Loads a template file, registers its content, and records a FileSource for reload-on-visit when dev mode is enabled. Returns TemplateError on file read failure.

```APIDOC
## register_template_file

### Description
Loads a template file, registers its content, and records a FileSource for reload-on-visit when dev mode is enabled. Returns TemplateError on file read failure.

### Method
register_template_file

### Signature
pub fn register_template_file<P>(&mut self, name: &str, tpl_path: P) -> Result<(), TemplateError> where P: AsRef<Path>

### Parameters
- **name** (&str) - Required - The name under which the template is registered.
- **tpl_path** (P) - Required - Path to the template file.

### Returns
- Result<(), TemplateError> - Ok on success, or TemplateError. A file read failure maps to TemplateError::from((IoError, name)), i.e. TemplateErrorReason::IoError.
```

--------------------------------

### register_script_helper

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Compiles the rhai source with the registry engine and registers it as an inline helper. Inside the script, `params` is an array of the helper params and `hash` a map of the helper hash.

```APIDOC
## register_script_helper

### Description
Compiles the rhai source with the registry engine and registers it as an inline helper. Inside the script, `params` is an array of the helper params and `hash` a map of the helper hash.

### Method
register_script_helper

### Signature
pub fn register_script_helper(&mut self, name: &str, script: &str) -> Result<(), ScriptError>

### Parameters
- **name** (&str) - Required - The name of the helper.
- **script** (&str) - Required - The rhai source code.

### Returns
Result<(), ScriptError> - Ok if successful, otherwise a ScriptError.

### Source
src/registry.rs:540
```

--------------------------------

### register_templates_directory

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Walks a directory and registers every file with the specified extension, excluding hidden and temporary files. Template names are relative paths with extension stripped.

```APIDOC
## register_templates_directory

### Description
Walks a directory and registers every file with the specified extension, excluding hidden and temporary files. Template names are relative paths with extension stripped.

### Method
register_templates_directory

### Signature
#[cfg(feature = "dir_source")] pub fn register_templates_directory<P>(&mut self, dir_path: P, options: DirectorySourceOptions) -> Result<(), TemplateError> where P: AsRef<Path>

### Parameters
- **dir_path** (P) - Required - Path to the directory to walk.
- **options** (DirectorySourceOptions) - Required - Options controlling which files are registered (e.g., tpl_extension).

### Returns
- Result<(), TemplateError> - Ok on success, or TemplateError.

### Notes
- Walks dir_path (min depth 1) and registers every file whose name ends with options.tpl_extension and whose file stem is not ignored (hidden .-files and temporary #-files).
- Template names are the path relative to dir_path with the extension stripped, using / separators (e.g., templates/some/path/file.hbs -> some/path/file).
```

--------------------------------

### Context::null

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/context.md

Creates a Context wrapping Json::Null.

```APIDOC
## Context::null

### Description
Creates a Context wrapping Json::Null.

### Method
null()

### Signature
pub fn null() -> Context

### Parameters
None

### Returns
Context - A Context wrapping Json::Null.

### Example
```rust
let ctx = Context::null();
```
```

--------------------------------

### Log helper usage

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/builtin-helpers.md

The log helper logs rendered parameters using the log crate. It supports configurable log levels via the level hash.

```handlebars
{{log this}}
{{log this level="warn"}}
```

--------------------------------

### render_template_with_context_to_write

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Streams the rendered output of an unregistered template string using a pre-built Context into a writer.

```APIDOC
## render_template_with_context_to_write

### Description
Streams the rendered output of an unregistered template string using a pre-built Context into a writer.

### Method
Rust method

### Signature
pub fn render_template_with_context_to_write<W>(
    &self,
    template_string: &str,
    ctx: &Context,
    writer: W,
) -> Result<(), RenderError>
where
    W: Write,

### Parameters
- **template_string** (&str) - Required - The template string to render.
- **ctx** (&Context) - Required - The pre-built context to use.
- **writer** (W) - Required - The writer to write the output to, must implement std::io::Write.

### Return Value
Result<(), RenderError> - Ok if successful, or a RenderError.

```

--------------------------------

### Catching Template and Render Errors

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/errors.md

Demonstrates how to handle errors during template registration and rendering by matching on the result and accessing error details like reason, position, and template name.

```rust
use handlebars::{Handlebars, RenderErrorReason, TemplateErrorReason};

// Template *registration* errors:
match hbs.register_template_string("t", "{{#if}}") {
    Err(e) => {
        let reason = e.reason();            // &TemplateErrorReason
        let pos = e.pos();                  // Option<(line, col)>
        let name = e.name();                // Option<&String> (template name)
        // ...
    }
    Ok(_) => {}
}

// Render errors:
match hbs.render("t", &data) {
    Err(e) => {
        let reason = e.reason();            // &RenderErrorReason
        let line = e.line_no;               // Option<usize>
        let col = e.column_no;              // Option<usize>
        let tpl = e.template_name.as_deref(); // Option<&str>
        // match reason with matches!(reason, RenderErrorReason::TemplateNotFound(name))
    }
    Ok(_) => {}
}
```

--------------------------------

### render_with_context

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Renders a registered template by name using a pre-built Context. Reuses the context for efficiency.

```APIDOC
## render_with_context

### Description
Renders a registered template by name using a pre-built Context.

### Method
Rust method

### Signature
pub fn render_with_context(&self, name: &str, ctx: &Context) -> Result<String, RenderError>

### Parameters
- **name** (&str) - Required - The name of the registered template.
- **ctx** (&Context) - Required - The pre-built context to use.

### Return Value
Result<String, RenderError> - The rendered string or a RenderError.

```

--------------------------------

### Registering a custom Rust helper

Source: https://github.com/sunng87/handlebars-rust/blob/master/README.md

Use the handlebars_helper! macro to define a helper function and register it with the handlebars instance.

```rust
handlebars_helper!(hex: |v: i64| format!("0x{:x}", v));

/// register the helper
handlebars.register_helper("hex", Box::new(hex));
```

--------------------------------

### Strict Mode Error Handling

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/registry.md

Shows how to enable strict mode to catch missing variables during template rendering.

```rust
use handlebars::{Handlebars, RenderErrorReason};
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hbs = Handlebars::new();
    hbs.set_strict_mode(true);

    match hbs.render_template("accessing non-exists key {{the_key_never_exists}}",
                              &json!({"the_only_key": "the_only_value"})) {
        Err(e) => {
            assert_eq!(e.column_no, Some(26));
            assert!(matches!(e.reason(), RenderErrorReason::MissingVariable(path)
                if path.as_deref() == Some("the_key_never_exists")));
            Ok(())
        }
        Ok(_) => panic!("strict mode should have raised an error"),
    }
}
```

--------------------------------

### RenderContext.block() and RenderContext.get_local_var()

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/render-context.md

Shows how a helper can read the current block scope, such as the @index variable of an enclosing each block, using RenderContext methods.

```APIDOC
## RenderContext.block() and RenderContext.get_local_var()

### Description
Reads the current block scope and retrieves a local variable (e.g., @index) from it. This is used within helpers to access block-level state.

### Method
block() -> Option<&BlockContext>
get_local_var(key: &str) -> Option<&Value>

### Parameters
- **key** (string) - Required - The name of the local variable to retrieve.

### Return Value
- **block()** - Option<&BlockContext> - The current block context, if any.
- **get_local_var(key)** - Option<&Value> - The value of the local variable, if present.

### Usage Example
```rust
use handlebars::*;

fn my_block_helper<'reg: 'rc, 'rc>(
    h: &Helper<'rc>,
    r: &'reg Handlebars<'reg>,
    ctx: &'rc Context,
    rc: &mut RenderContext<'reg, 'rc>,
    out: &mut dyn Output,
) -> HelperResult {
    // read the current block scope, e.g. @index of the enclosing each
    let index = rc.block().and_then(|b| b.get_local_var("index"));

    // render the inner template within the current context
    if let Some(t) = h.template() {
        t.render(r, ctx, rc, out)?;
    }
    Ok(())
}
```
```

--------------------------------

### RenderContext constructor

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/render-context.md

Creates a new RenderContext with default values and an optional root template name.

```rust
pub fn new(root_template: Option<&'reg String>) -> RenderContext<'reg, 'rc>
```

--------------------------------

### Implement an output-writing helper with error handling

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/helper-api.md

This helper writes directly to the output stream and includes explicit error handling for parameter validation. It follows the pattern found in examples/error.rs.

```rust
use handlebars::*;
use std::io::Write;

fn greet(h: &Helper<'_>, _: &Handlebars<'_>, _: &Context,
         _: &mut RenderContext<'_, '_>, out: &mut dyn Output) -> HelperResult {
    let name = h.param(0)
        .and_then(|v| v.value().as_str())
        .ok_or_else(|| RenderErrorReason::ParamTypeMismatchForName(
            "greet", "0".to_string(), "str".to_string()).into())?;
    write!(out, "Hello, {name}!")?;
    Ok(())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut hbs = Handlebars::new();
    hbs.register_helper("greet", Box::new(greet as fn(_,_,_,_,_) -> HelperResult));
    hbs.register_template_string("t", "{{greet world}}")?;
    println!("{}", hbs.render("t", &serde_json::json!({"world": "Rust"}))?);
    Ok(())
}
```

--------------------------------

### Define handlebars_helper! macro grammar

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/macros.md

The grammar for the handlebars_helper! macro, showing positional parameters, hash parameters with defaults, and variadic arguments.

```text
handlebars_helper!(Name: | param: Type, ..., { hash_name: HashType = default_literal }, ..., *args, **kwargs | body );
```

--------------------------------

### Raw helper usage

Source: https://github.com/sunng87/handlebars-rust/blob/master/_autodocs/api-reference/builtin-helpers.md

The raw helper renders block content verbatim without parsing Handlebars expressions inside.

```handlebars
{{{{raw}}}}{{this is not evaluated}}{{/raw}}
```
Tokens:
Raw