Skip to main content

State

Struct State 

Source
pub struct State<'template, 'env> { /* private fields */ }
Expand description

Provides access to the current execution state of the engine.

The state is passed to filters, tests, functions, and callable objects to let them interface with the engine. Typed callbacks can request either a shared or mutable reference. Shared access is useful for inspecting the template environment, context variables, and current auto-escaping behavior; mutable access additionally permits nested calls and render-local storage.

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>

Source

pub fn env(&self) -> &'env Environment<'env>

Returns a reference to the current environment.

Source

pub fn name(&self) -> &str

Returns the name of the current template.

Source

pub fn auto_escape(&self) -> &AutoEscape

Returns the current value of the auto escape flag.

Source

pub fn undefined_behavior(&self) -> UndefinedBehavior

Returns the current undefined behavior.

Source

pub fn current_block(&self) -> Option<&str>

Returns the name of the innermost block.

Source

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.

Source

pub fn call_macro( &mut 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.

Source

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 mut rendered = tmpl
    .render_captured(context!(name => "John"))?;
let rv = rendered.with_state_mut(|state| state.render_block("hi"))?;
println!("{}", rv);

Rendering a block is a stateful operation and therefore requires mutable access to the state. Filters and functions can request this by taking &mut State as their first parameter. Execution frames are restored if rendering fails, while explicit mutations to temps or extensions remain.

Source

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.

Source

pub fn exports(&self) -> Vec<&str>

Returns a list of the names of all exports (top-level variables).

Like in Jinja2, names starting with an underscore are private and are not considered exports. They can still be retrieved with lookup.

Source

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.

Source

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.

Source

pub fn apply_filter( &mut 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"));
Source

pub fn perform_test( &mut 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);
Source

pub fn format(&mut 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");
Source

pub fn consume_fuel(&self, fuel: u64) -> Result<(), Error>

Consumes fuel.

Custom filters, functions and methods can use this to account for expensive work they perform on behalf of a template. The engine already charges for the size of the value they return, but not for the work that went into producing it.

If this runs out of fuel, an OutOfFuel error is returned and the rendering will fail. If fuel tracking is not enabled or the fuel feature is turned off, this does nothing.

fn expensive(state: &State, n: u64) -> Result<u64, Error> {
    state.consume_fuel(n)?;
    Ok((0..n).sum())
}
Source

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 temporarily 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 useful for dynamically named data that needs to be represented as a Value. For ordinary typed Rust state, prefer get_or_insert_extension, which avoids object wrappers and interior mutability.

§Example
use minijinja::{Value, State};

fn inc(state: &mut 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
}
Source

pub fn set_temp(&mut self, name: &str, value: Value) -> Option<Value>

Inserts a temp and returns the old temp.

For more information see get_temp.

Source

pub fn get_extension<T>(&self) -> Option<&T>
where T: Send + 'static,

Returns a reference to a typed render-local extension.

Extensions are similar to temps, but store ordinary Rust values keyed by their type. They are useful for state that should be shared by filters and functions for the duration of a render without requiring a Value, crate::value::Object, or interior mutability. There can be one extension of each concrete type; use a newtype when independent values have the same underlying type. Extension values must be Send because states can be moved between threads.

Extensions are preserved across nested evaluation, including includes, blocks, and macro calls. They are dropped together with the state.

Source

pub fn get_extension_mut<T>(&mut self) -> Option<&mut T>
where T: Send + 'static,

Returns a mutable reference to a typed render-local extension.

For more information see get_extension.

Source

pub fn get_or_insert_extension<T>(&mut self, value: T) -> &mut T
where T: Send + 'static,

Returns a mutable extension, inserting it if necessary.

If an extension of type T is already present, value is not inserted. Extensions require mutable state so that stored values do not need a mutex or other interior mutability.

§Example
use minijinja::State;

#[derive(Default)]
struct Counter(usize);

fn next(state: &mut State) -> usize {
    let counter = state.get_or_insert_extension(Counter::default());
    counter.0 += 1;
    counter.0
}
Source

pub fn get_or_insert_extension_with<T, F>(&mut self, f: F) -> &mut T
where T: Send + 'static, F: FnOnce() -> T,

Returns a mutable extension, inserting one from f if necessary.

For more information see get_or_insert_extension.

Source§

impl State<'_, '_>

This impl block contains no public items.

Fuel helpers for the built-in filters, functions and tests.

Trait Implementations§

Source§

impl<'a> ArgType<'a> for &State<'_, '_>

Source§

type Output = &'a State<'a, 'a>

The output type of this argument.
Source§

impl Debug for State<'_, '_>

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'template, 'env> !RefUnwindSafe for State<'template, 'env>

§

impl<'template, 'env> !Sync for State<'template, 'env>

§

impl<'template, 'env> !UnwindSafe for State<'template, 'env>

§

impl<'template, 'env> Forget for State<'template, 'env>

§

impl<'template, 'env> Freeze for State<'template, 'env>

§

impl<'template, 'env> Move for State<'template, 'env>

§

impl<'template, 'env> Send for State<'template, 'env>

§

impl<'template, 'env> Unpin for State<'template, 'env>

§

impl<'template, 'env> UnsafeUnpin for State<'template, 'env>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> AsAny for T
where T: Any,

Source§

fn as_any_ref(&self) -> &(dyn Any + 'static)

Source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Source§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

Source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

Source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

Source§

fn implicit( self, class: Class, constructed: bool, tag: u32, ) -> TaggedParser<'a, Implicit, Self, E>

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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 more
Source§

impl<T> Paint for T
where T: ?Sized,

Source§

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 primary(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Primary].

§Example
println!("{}", value.primary());
Source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Fixed].

§Example
println!("{}", value.fixed(color));
Source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Rgb].

§Example
println!("{}", value.rgb(r, g, b));
Source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Black].

§Example
println!("{}", value.black());
Source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Red].

§Example
println!("{}", value.red());
Source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Green].

§Example
println!("{}", value.green());
Source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Yellow].

§Example
println!("{}", value.yellow());
Source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Blue].

§Example
println!("{}", value.blue());
Source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Magenta].

§Example
println!("{}", value.magenta());
Source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Cyan].

§Example
println!("{}", value.cyan());
Source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: White].

§Example
println!("{}", value.white());
Source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlack].

§Example
println!("{}", value.bright_black());
Source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightRed].

§Example
println!("{}", value.bright_red());
Source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightGreen].

§Example
println!("{}", value.bright_green());
Source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightYellow].

§Example
println!("{}", value.bright_yellow());
Source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlue].

§Example
println!("{}", value.bright_blue());
Source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.bright_magenta());
Source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightCyan].

§Example
println!("{}", value.bright_cyan());
Source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightWhite].

§Example
println!("{}", value.bright_white());
Source§

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>

Returns self with the bg() set to [Color :: Primary].

§Example
println!("{}", value.on_primary());
Source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Fixed].

§Example
println!("{}", value.on_fixed(color));
Source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Rgb].

§Example
println!("{}", value.on_rgb(r, g, b));
Source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Black].

§Example
println!("{}", value.on_black());
Source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Red].

§Example
println!("{}", value.on_red());
Source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Green].

§Example
println!("{}", value.on_green());
Source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Yellow].

§Example
println!("{}", value.on_yellow());
Source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Blue].

§Example
println!("{}", value.on_blue());
Source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Magenta].

§Example
println!("{}", value.on_magenta());
Source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Cyan].

§Example
println!("{}", value.on_cyan());
Source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: White].

§Example
println!("{}", value.on_white());
Source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlack].

§Example
println!("{}", value.on_bright_black());
Source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightRed].

§Example
println!("{}", value.on_bright_red());
Source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightGreen].

§Example
println!("{}", value.on_bright_green());
Source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightYellow].

§Example
println!("{}", value.on_bright_yellow());
Source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlue].

§Example
println!("{}", value.on_bright_blue());
Source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.on_bright_magenta());
Source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightCyan].

§Example
println!("{}", value.on_bright_cyan());
Source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightWhite].

§Example
println!("{}", value.on_bright_white());
Source§

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 bold(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Bold].

§Example
println!("{}", value.bold());
Source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Dim].

§Example
println!("{}", value.dim());
Source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Italic].

§Example
println!("{}", value.italic());
Source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Underline].

§Example
println!("{}", value.underline());

Returns self with the attr() set to [Attribute :: Blink].

§Example
println!("{}", value.blink());

Returns self with the attr() set to [Attribute :: RapidBlink].

§Example
println!("{}", value.rapid_blink());
Source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Invert].

§Example
println!("{}", value.invert());
Source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Conceal].

§Example
println!("{}", value.conceal());
Source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Strike].

§Example
println!("{}", value.strike());
Source§

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 mask(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Mask].

§Example
println!("{}", value.mask());
Source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Wrap].

§Example
println!("{}", value.wrap());
Source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Linger].

§Example
println!("{}", value.linger());
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.

Returns self with the quirk() set to [Quirk :: Clear].

§Example
println!("{}", value.clear());
Source§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Resetting].

§Example
println!("{}", value.resetting());
Source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Bright].

§Example
println!("{}", value.bright());
Source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: OnBright].

§Example
println!("{}", value.on_bright());
Source§

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);
Source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
Source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more