Struct Kwargs

pub struct Kwargs { /* private fields */ }

Utility to accept keyword arguments.

Keyword arguments are represented as regular values as the last argument in an argument list. This can be quite complex to use manually so this type is added as a utility. You can use get to fetch a single keyword argument and then use assert_all_used to make sure extra arguments create an error.

Here an example of a function modifying values in different ways.

use minijinja::value::{Value, Kwargs};
use minijinja::Error;

fn modify(mut values: Vec<Value>, options: Kwargs) -> Result<Vec<Value>, Error> {
    // get pulls a parameter of any type.  Same as from_args.  For optional
    // boolean values the type inference is particularly convenient.
    if let Some(true) = options.get("reverse")? {
        values.reverse();
    }
    if let Some(limit) = options.get("limit")? {
        values.truncate(limit);
    }
    options.assert_all_used()?;
    Ok(values)
}

If for whatever reason you need a value again you can use Into to convert it back into a Value. This is particularly useful when performing calls into values. To create a Kwargs object from scratch you can use FromIterator:

use minijinja::value::{Value, Kwargs};
let kwargs = Kwargs::from_iter([
    ("foo", Value::from(true)),
    ("bar", Value::from(42)),
]);
let value = Value::from(kwargs);
assert!(value.is_kwargs());

When working with Rest you can use from_args to split all arguments into positional arguments and keyword arguments:

fn my_func(args: Rest<Value>) -> Result<Value, Error> {
    let (args, kwargs) = from_args::<(&[Value], Kwargs)>(&args)?;
    // do something with args and kwargs
}

Implementations

impl Kwargs

pub fn peek<'a, T>(&'a self, key: &'a str) -> Result<T, Error>

where T: ArgType<'a, Output = T>,

Get a single argument from the kwargs but don’t mark it as used.

pub fn get<'a, T>(&'a self, key: &'a str) -> Result<T, Error>

where T: ArgType<'a, Output = T>,

Gets a single argument from the kwargs and marks it as used.

This method works pretty much like from_args and marks any parameter used internally. For optional arguments you would typically use Option<T> and for non optional ones directly T.

Examples:

// f(int=42) -> Some(42)
// f() -> None
let optional_int: Option<u32> = kwargs.get("int")?;
// f(int=42) -> 42
// f() -> Error
let required_int: u32 = kwargs.get("int")?;

If you don’t want to mark it as used, us peek instead.

pub fn has(&self, key: &str) -> bool

Checks if a keyword argument exists.

pub fn args(&self) -> impl Iterator<Item = &str>

Iterates over all passed keyword arguments.

pub fn assert_all_used(&self) -> Result<(), Error>

Asserts that all kwargs were used.

Trait Implementations

impl<'a> ArgType<'a> for Kwargs

type Output = Kwargs

The output type of this argument.

impl Clone for Kwargs

fn clone(&self) -> Kwargs

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Kwargs

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

Formats the value using the given formatter.

impl From<Kwargs> for Value

fn from(value: Kwargs) -> Self

Converts to this type from the input type.

impl<'a> FromIterator<(&'a str, Value)> for Kwargs

fn from_iter<T>(iter: T) -> Self

where T: IntoIterator<Item = (&'a str, Value)>,

Creates a value from an iterator.

impl FromIterator<(String, Value)> for Kwargs

fn from_iter<T>(iter: T) -> Self

where T: IntoIterator<Item = (String, Value)>,

Creates a value from an iterator.

impl TryFrom<Value> for Kwargs

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Value) -> Result<Self, Self::Error>

Performs the conversion.