MiniJinja Documentation

The repository contains numerous examples covering various integration and feature scenarios:

Core Features & Syntax

• hello / minimal: Basic Hello World examples.
• inheritance: Template inheritance usage.
• macros: Using macros and imports.
• line-statements: Line statements and comment syntax.
• recursive-for: Recursive for loops.
• expr: Expression evaluation support.
• debug: Using the built-in debug() function.
• error: Built-in error reporting support.

Context & Data Handling

• dynamic-context / dynamic-objects: Using dynamic objects as template context.
• merge-context: Merging context from multiple values.
• render-value: Passing Value as Serialize context.
• none-is-undefined: Configuring None to behave like undefined.
• undefined-tracking: Tracking undefined values in templates.
• value-tracking: Tracking values referenced at runtime.
• deserialize: Deserializing directly from a value.
• load-lazy: Loading data lazily on demand.
• self-referential-context: Using helpers for self-referential contexts.

Loading & Extensions

• custom-loader: Loading templates dynamically at runtime.
• path-loader: Loading templates from disk using the loader feature.
• load-resource: Loading files dynamically from disk within templates.
• embedding: Using minijina-embed to embed templates into the binary.
• filters: Writing custom filters and global functions.
• call-block-function: Using the {% call %} block with custom functions.

Advanced & Integration

• actix-web-demo: Integration with the Actix Web framework.
• function-using-async / object-using-async: Using tokio::task::block_on within functions or objects.
• streaming: Using one-shot iterators to stream results.
• syntax-highlighting: Implementing syntax highlighting with syntect.
• build-script: Generating Rust code via MiniJinja in build scripts.
• dsl: Using MiniJinja as a Domain Specific Language (DSL).

The minijinja-cabi crate provides a C ABI wrapper for MiniJinja, allowing you to use the MiniJinja template engine within C programs. The C header file is located at include/minijinja.h.

To use it, you typically follow these steps:

1. Create a new environment using mj_env_new().
2. Add templates to the environment using mj_env_add_template().
3. Create a context object using mj_value_new_object() and populate it with data (e.g., mj_value_set_string_key()).
4. Render the template using mj_env_render_template().
5. Handle potential errors with mj_err_print() and free resources using mj_str_free() and mj_env_free().

#include <minijinja.h>
#include <stdio.h>

int main()
{
    mj_env *env = mj_env_new();

    bool ok = mj_env_add_template(env, "hello", "Hello {{ name }}!");
    mj_value ctx = mj_value_new_object();
    mj_value_set_string_key(&ctx, "name", mj_value_new_string("C-Lang"));

    char *rv = mj_env_render_template(env, "hello", ctx);
    if (!rv) {
        mj_err_print();
    } else {
        printf("%s\n", rv);
        mj_str_free(rv);
    }

    mj_env_free(env);

    return 0;
}

MiniJinja provides built-in error rendering support to improve template debuggability. When a template fails to render, the error output includes:

1. A trace of the failure: It shows the specific error message and the file/line number where the error occurred.
2. Contextual code snippets: It displays the source code around the error location, using > to point to the problematic line and ^ to highlight the specific expression.
3. Referenced variables: It lists the variables that were in scope at the time of the error, helping you inspect their values.
4. Cause chain: If the error was caused by a nested operation (e.g., an error inside an {% include %}), it shows the underlying cause and the specific context of that sub-template.

$ cargo run
template error: could not render include: error in "include.txt" (in hello.txt:8)
---------------------------------- hello.txt ----------------------------------
   5 |             {% with foo = 42 %}
   6 |               {{ range(10) }}
   7 |               {{ other_seq|join(" ") }}
   8 >               {% include "include.txt" %}
     i                  ^^^^^^^^^^^^^^^^^^^^^ could not render include
   9 |             {% endwith %}
  10 |           {% endwith %}
  11 |         {% endfor %}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Referenced variables: {
    foo: 42,
    other_seq: [
        0,
        1,
        2,
        3,
        4,
    ],
    range: minijinja::functions::builtins::range,
}
-------------------------------------------------------------------------------

caused by: invalid operation: tried to use + operator on unsupported types number and string (in include.txt:1)
--------------------------------- include.txt ---------------------------------
   1 > Hello {{ item_squared + bar }}!
     i          ^^^^^^^^^^^^^^^^^^^^ invalid operation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Referenced variables: {
    bar: "test",
    item_squared: 4,
}
-------------------------------------------------------------------------------