pub struct State<'template, 'env> { /* private fields */ }
Expand description
Provides access to the current execution state of the engine.
A read only reference is passed to filter functions and similar objects to allow limited interfacing with the engine. The state is useful to look up information about the engine in filter, test or global functions. It not only provides access to the template environment but also the context variables of the engine, the current auto escaping behavior as well as the auto escape flag.
In some testing scenarios or more advanced use cases you might need to get
a State
. The state is managed as part of the template execution but the
initial state can be retrieved via Template::new_state
.
The most common way to get hold of the state however is via functions of filters.
Notes on lifetimes: the state object exposes some of the internal lifetimes through the type. You should always elide these lifetimes as there might be lifetimes added or removed between releases.
Implementations§
Source§impl<'template, 'env> State<'template, 'env>
impl<'template, 'env> State<'template, 'env>
Sourcepub fn env(&self) -> &'env Environment<'env>
pub fn env(&self) -> &'env Environment<'env>
Returns a reference to the current environment.
Sourcepub fn auto_escape(&self) -> AutoEscape
pub fn auto_escape(&self) -> AutoEscape
Returns the current value of the auto escape flag.
Sourcepub fn undefined_behavior(&self) -> UndefinedBehavior
pub fn undefined_behavior(&self) -> UndefinedBehavior
Returns the current undefined behavior.
Sourcepub fn current_block(&self) -> Option<&str>
pub fn current_block(&self) -> Option<&str>
Returns the name of the innermost block.
Sourcepub fn lookup(&self, name: &str) -> Option<Value>
pub fn lookup(&self, name: &str) -> Option<Value>
Looks up a variable by name in the context.
§Note on Closures
Macros and call blocks analyze which variables are referenced and create closures for them. This means that unless a variable is defined as a global in the environment, was passed in the initial render context, or was referenced by a macro, this method won’t be able to find it.
Sourcepub fn call_macro(&self, name: &str, args: &[Value]) -> Result<String, Error>
pub fn call_macro(&self, name: &str, args: &[Value]) -> Result<String, Error>
Looks up a global macro and calls it.
This looks up a value as lookup
does and calls it
with the passed args.
Sourcepub fn render_block(&mut self, block: &str) -> Result<String, Error>
pub fn render_block(&mut self, block: &str) -> Result<String, Error>
Renders a block with the given name into a string.
This method works like Template::render
but
it only renders a specific block in the template. The first argument is
the name of the block.
This renders only the block hi
in the template:
let tmpl = env.get_template("hello")?;
let rv = tmpl
.eval_to_state(context!(name => "John"))?
.render_block("hi")?;
println!("{}", rv);
Note that rendering a block is a stateful operation. If an error is returned the module has to be re-created as the internal state can end up corrupted. This also means you can only render blocks if you have a mutable reference to the state which is not possible from within filters or similar.
Sourcepub fn render_block_to_write<W>(
&mut self,
block: &str,
w: W,
) -> Result<(), Error>where
W: Write,
pub fn render_block_to_write<W>(
&mut self,
block: &str,
w: W,
) -> Result<(), Error>where
W: Write,
Renders a block with the given name into an io::Write
.
For details see render_block
.
Sourcepub fn exports(&self) -> Vec<&str>
pub fn exports(&self) -> Vec<&str>
Returns a list of the names of all exports (top-level variables).
Sourcepub fn known_variables(&self) -> Vec<Cow<'_, str>>
pub fn known_variables(&self) -> Vec<Cow<'_, str>>
Returns a list of all known variables.
This list contains all variables that are currently known to the state.
To retrieve the values you can use lookup
. This will
include all the globals of the environment. Note that if the context
has been initialized with an object that lies about variables (eg: it
does not correctly implement enumeration), the returned list might not
be complete.
Sourcepub fn get_template(&self, name: &str) -> Result<Template<'env, 'env>, Error>
pub fn get_template(&self, name: &str) -> Result<Template<'env, 'env>, Error>
Fetches a template by name with path joining.
This works like Environment::get_template
with the difference that the lookup
undergoes path joining. If the environment has a configured path joining callback,
it will be invoked with the name of the current template as parent template.
For more information see Environment::set_path_join_callback
.
Sourcepub fn apply_filter(&self, filter: &str, args: &[Value]) -> Result<Value, Error>
pub fn apply_filter(&self, filter: &str, args: &[Value]) -> Result<Value, Error>
Invokes a filter with some arguments.
let rv = state.apply_filter("upper", &["hello world".into()]).unwrap();
assert_eq!(rv.as_str(), Some("HELLO WORLD"));
Sourcepub fn perform_test(&self, test: &str, args: &[Value]) -> Result<bool, Error>
pub fn perform_test(&self, test: &str, args: &[Value]) -> Result<bool, Error>
Invokes a test function on a value.
let rv = state.perform_test("even", &[42i32.into()]).unwrap();
assert!(rv);
Sourcepub fn format(&self, value: Value) -> Result<String, Error>
pub fn format(&self, value: Value) -> Result<String, Error>
Formats a value to a string using the formatter on the environment.
let rv = state.format(Value::from(42)).unwrap();
assert_eq!(rv, "42");
Sourcepub fn get_temp(&self, name: &str) -> Option<Value>
pub fn get_temp(&self, name: &str) -> Option<Value>
Looks up a temp and returns it.
Temps are similar to context values but the engine never looks them up on their own and they are not scoped. The lifetime of temps is limited to the rendering process of a template. Temps are useful so that filters and other things can temporary stash away state without having to resort to thread locals which are hard to manage. Unlike context variables, temps can also be modified during evaluation by filters and functions.
Temps are values but if you want to hold complex state you can store a custom object there.
§Example
use minijinja::{Value, State};
fn inc(state: &State) -> Value {
let old = state
.get_temp("my_counter")
.unwrap_or_else(|| Value::from(0i64));
let new = Value::from(i64::try_from(old).unwrap() + 1);
state.set_temp("my_counter", new.clone());
new
}
Sourcepub fn set_temp(&self, name: &str, value: Value) -> Option<Value>
pub fn set_temp(&self, name: &str, value: Value) -> Option<Value>
Inserts a temp and returns the old temp.
For more information see get_temp
.
Sourcepub fn get_or_set_temp_object<O, F>(&self, name: &str, f: F) -> Arc<O>
pub fn get_or_set_temp_object<O, F>(&self, name: &str, f: F) -> Arc<O>
Shortcut for registering an object as a temp.
If the value is already there, it’s returned as object, if it’s not there yet, the function is invoked to create it.
§Example
use std::sync::atomic::{AtomicUsize, Ordering};
use minijinja::{Value, State};
use minijinja::value::Object;
#[derive(Debug, Default)]
struct MyObject(AtomicUsize);
impl Object for MyObject {}
fn inc(state: &State) -> Value {
let obj = state.get_or_set_temp_object("my_counter", MyObject::default);
let old = obj.0.fetch_add(1, Ordering::AcqRel);
Value::from(old + 1)
}
§Panics
This will panick if the value registered under that name is not the object expected.
Trait Implementations§
Auto Trait Implementations§
impl<'template, 'env> Freeze for State<'template, 'env>
impl<'template, 'env> !RefUnwindSafe for State<'template, 'env>
impl<'template, 'env> Send for State<'template, 'env>
impl<'template, 'env> Sync for State<'template, 'env>
impl<'template, 'env> Unpin for State<'template, 'env>
impl<'template, 'env> !UnwindSafe for State<'template, 'env>
Blanket Implementations§
Source§impl<T> AsAny for Twhere
T: Any,
impl<T> AsAny for Twhere
T: Any,
fn as_any_ref(&self) -> &(dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
Source§impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
Source§impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
Source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moreSource§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere
T: ?Sized,
Source§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the foreground set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red()
and
green()
, which have the same functionality but are
pithier.
§Example
Set foreground color to white using fg()
:
use yansi::{Paint, Color};
painted.fg(Color::White);
Set foreground color to white using white()
.
use yansi::Paint;
painted.white();
Source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
Source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
Source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
Source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
Source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
Source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
Source§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the background set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red()
and
on_green()
, which have the same functionality but
are pithier.
§Example
Set background color to red using fg()
:
use yansi::{Paint, Color};
painted.bg(Color::Red);
Set background color to red using on_red()
.
use yansi::Paint;
painted.on_red();
Source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
Source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
Source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
Source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Source§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling Attribute
value
.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold()
and
underline()
, which have the same functionality
but are pithier.
§Example
Make text bold using attr()
:
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);
Make text bold using using bold()
.
use yansi::Paint;
painted.bold();
Source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Source§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi
Quirk
value
.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask()
and
wrap()
, which have the same functionality but are
pithier.
§Example
Enable wrapping using .quirk()
:
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);
Enable wrapping using wrap()
.
use yansi::Paint;
painted.wrap();
Source§fn clear(&self) -> Painted<&T>
👎Deprecated since 1.0.1: renamed to resetting()
due to conflicts with Vec::clear()
.
The clear()
method will be removed in a future release.
fn clear(&self) -> Painted<&T>
resetting()
due to conflicts with Vec::clear()
.
The clear()
method will be removed in a future release.Source§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the Condition
value
applies. Replaces any previous condition.
See the crate level docs for more details.
§Example
Enable styling painted
only when both stdout
and stderr
are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);