[−][src]Derive Macro liquid_derive::FilterParameters
#[derive(FilterParameters)] { // Attributes available to this derive: #[parameter] #[evaluated] }
Implements FilterParameters
, as well as two of the traits it requires
(Display
and FilterParametersReflection
) and its evaluated counterpart.
Before declaring the struct, the #[evaluated = "..."]
attribute may be
used to rename the evaluated counterpart (defaults to this struct's name
prepended by "Evaluated"). This may be useful to avoid name collisions.
Each parameter has the following structure:
#[parameter(...)] NAME: TYPE
NAME
will be the name of the parameter (although it may be renamed
if it collides with a rust keyword, see below for more information).
TYPE
will be either Expression
or Option<Expression>
, marking the
parameter, respectively, as either required or optional. Note Expression
here is the type ::liquid_core::runtime::Expression
.
Inside the #[parameter(...)]
attribute there may be some information
about the parameter, such as:
- description
-> (REQUIRED) the description of this parameter for
FilterReflection
- rename
-> overrides NAME
as the liquid name of the parameter
(to avoid collisions with rust keywords)
- mode
-> either "keyword" or "positional" (defaults to "positional")
- arg_type
-> a shortcut to unwrap the content of a value while evaluating
the argument (defaults to "any"). See below for more information.
Argument Type
If you want to only accept a certain type of Value
for a given argument,
you may mark its type with arg_type = "..."
. This will take away the burden
and boilerplate of handling errors and unwraping the liquid Value
into a rust
type.
Right now, there is a default arg_type
, "any", that accepts any value, as well
as other 6 types, one for each type of Scalar
:
- "any" -> any Value
is accepted, this is the default option and evaluate
will
only convert Expression
to Value
.
- "integer" -> only Scalar(Integer)
is accepted, evaluate
will unwrap Value
into i32
.
- "float" -> only Scalar(Float)
is accepted, evaluate
will unwrap Value
into f64
.
- "bool" -> only Scalar(Bool)
is accepted, evaluate
will unwrap Value
into bool
.
- "date" -> only Scalar(Date)
is accepted, evaluate
will unwrap Value
into Date
.
- "str" -> only Scalar(Str)
is accepted, evaluate
will unwrap Value
into KStringCow
.
Examples
From slice filter:
#[derive(Debug, FilterParameters)] struct SliceArgs { #[parameter( description = "The offset of the slice.", arg_type = "integer" // Only integer scalars are accepted )] offset: Expression, // Required parameter named `offset` #[parameter( description = "The length of the slice.", arg_type = "integer" // Only integer scalars are accepted )] length: Option<Expression>, // Optional parameter named `length` }
From test filter:
#[derive(Debug, FilterParameters)] // The evaluated counterpart of this `FilterParameters` would have been // `EvaluatedTestMixedFilterParameters`, but because of this attribute // it will be named `TestMixedFilterParametersEvaluated` instead. #[evaluated(TestMixedFilterParametersEvaluated)] struct TestMixedFilterParameters { #[parameter( description = "1", arg_type = "integer", // Only integer scalars are accepted mode = "keyword" // This is a keyword parameter )] a: Option<Expression>, // Optional parameter named `a` #[parameter( description = "2", arg_type = "bool" // Only boolean scalars are accepted )] b: Expression, // Required parameter named `b` #[parameter( description = "3", arg_type = "float", // Only floating point scalars are accepted mode = "keyword" // This is a keyword parameter )] c: Option<Expression>, // Optional parameter named `c` #[parameter( description = "4", arg_type = "date" // Only date scalars are accepted )] d: Expression, // Required parameter named `d` #[parameter( description = "5", arg_type = "str" // Only string scalars are accepted )] e: Option<Expression>, // Optional parameter named `e` #[parameter( rename = "type", // Will override field name in liquid description = "6", arg_type = "any", // Any `Value` is accepted. This is the same as not defining `arg_type` mode = "keyword" // This is a keyword parameter )] f: Expression, // Required parameter named `type` (see `rename` in attribute) }