Is it possible to access a custom state object (eg. a Rust struct / reference) in a custom function?

[tesfabpel]

I'm testing minijinja (after trying tera) and I don't know how to register a custom function in an Environment with a way to access a state or if the feature is missing altogether...

For example, I'm using tera / minijinja to have a static site generator to use at work and I'd like to have a languages function that returns a list or available languages in the website I'm generating to render a button in the header to switch between the languages.
Of course, such a function would need to access the state of my site generator when called...
It should return a Vec<SiteLanguage> where SiteLanguage could be a struct with iso2Letters, name and isActive fields.

It would be used in this way:

{% for lang in languages() %}
<li class='{% if lang.isActive %}active{% endif %}'>
    <a href='/{{ lang.iso2Letters }}'>
        <img src='img/flag-{{ lang.iso2Letters }}.png' alt=''>{{ lang.name }}
    </a>
</li>
{% endfor %}

Thanks.

EDIT: in tera, the register_function function accepts a struct implementing the Function trait which of course allows you to store any number of fields in your custom struct...

[mitsuhiko]

There are many ways in which this can be done and depending on what you have in mind you might like one more than the other. In general state access happens with &State:

use minijinja::State;
use serde::Serialize;

#[derive(Serialize)]
pub struct SiteLanguage {
    iso2_letters: String,
    name: String,
    is_active: bool,
}

fn get_languages(state: &State) -> Vec<Value> {
    let mut rv = Vec::new();
    let current_lang = state.lookup("CURRENT_LANGUAGE").unwrap();
    let current_lang = current_lang.as_str().unwrap();
    for lang in state.lookup("LANGUAGES").unwrap().try_iter().unwrap() {
        let lang = lang.to_string();
        rv.push(Value::from_serializable(&SiteLanguage {
           is_active = current_lang == lang,
           name: get_language_name(name), // todo: de -> German etc.
           iso2_letters: lang,
        }));
    }
    rv
}

let mut env = Environment::new();
env.add_function("languages", get_languages);
env.add_global("LANGUAGES", Value::from(vec!["de", "en"]));
env.add_global("CURRENT_LANGUAGE", "de");

This is a trivial example where calling languages() just looks up the LANGUAGES global variable in the template. That does not sound super useful in itself but it shows the concept. From there however you just need to now be creative and think where your data is coming from. Putting stuff into the template context is what datetimeformat uses to pick the default format for instance.

If you need extra functionality you can for instance you can store a custom struct in the context that you look up and then use downcast_object_ref to get back to the raw struct to pull and data out. You could also use thread locals to pull data. The minijinja example for actix-web for instance shows how the request object can be accessed from within a template with the help of thread locals: https://github.com/mitsuhiko/minijinja/blob/main/examples/actix-web-demo/src/main.rs

If for instance your state is can be put into an Arc you can easily pass it to templates on render and then pull it in filters:

use std::sync::Arc;
use minijinja::{State, value::Object};

#[derive(Debug)]
pub struct AppState {
    config: ...,
}

#[derive(Debug)]
pub struct AppStateHolder {
    state: Arc<AppState>,
}

impl Object for AppStateHolder {}

fn with_app_state<R, F: FnOnce(&AppState) -> R>(state: &State, f: F) -> R {
    let app_state_holder = state.lookup("APP").unwrap();
    f(&app_state_holder.downcast_object_ref::<AppStateHolder>().unwrap().state)
}

fn print_config(state: &State) -> String {
    with_app_state(state, |app_state| {
        format!("{:?}", app_state.config);
    })
}

env.add_global("print_config", print_config);
let tmpl = env.get_template("whatever.txt").unwrap();
tmpl.render(context! {
    APP => Value::from_object(AppStateHolder { state: app_state.clone() }),
});

Hope this helps.

[mitsuhiko]

Also to address your edit:

EDIT: in tera, the register_function function accepts a struct implementing the Function trait which of course allows you to store any number of fields in your custom struct...

You can also do that in MiniJinja. If you implement Object you can create a callable object. Just register it with env.add_global("my_function", Value::from_object(MyCallableStruct { ... })).

https://docs.rs/minijinja/latest/minijinja/value/trait.Object.html

Macros for instance in the engine are just custom objects that are callable: https://github.com/mitsuhiko/minijinja/blob/main/minijinja/src/vm/macro_object.rs

[tesfabpel]

Sorry for the long wait, I've managed to try with env.add_global("my_function", Value::from_object(MyCallableStruct { ... })) and indeed it worked perfectly!
If I may suggest it, I'd put this into the docs because having a struct referencing the app's state is probably something frequent according to me...
Or maybe, before that, having add_function accepts a Function trait with a method fn call(&self, state: &State, args: &[Value]) -> Result<Value, Error> like Object has, so it's more fit for the use case (like, it makes more sense to have it under add_function than add_global), IDK...

[mitsuhiko]

I added a comment in 17e9c56. Maybe this helps future readers.