Extend documentation of custom filters

[saona-raimundo]

Related to #743 and #102

Extends documentation of custom filters.

[djc]

Thanks, some great improvements here!

[djc]

There are actually no restrictions on the arguments, and while the return type must be an ::askama::Result<T>, T can be of any type.

[saona-raimundo]

Thank you!
I was checking it again and wanted to say that "the first argument to the filter is a reference to the expression it is applied to", but it is not totally true and found some unexpected (for me) behaviour:

Consider the templates

{{ 2|my_filter }}

and

{{ (1 + 1)|my_filter }}

I would expect both to work the same, but they do not: the first case is 2 is given directly to my filter, while in the second case &(1 + 1) is given as reference.

The problem arises for the signature of the filter: should it take a reference or not?

fn my_filter(n: usize) -> ::askama::Result<String>

works for the first case and

fn my_filter(n: &usize) -> ::askama::Result<String>

works for the second.

Question.
Is this expected for you, or should 2 be past a reference &2?

[djc]

I think this is expected, although I agree that it is quite subtle -- would be great to document it! I think the recommended way to abstract over the difference would be to use a trait. For example, std::fmt::Display has a blanket implementation for &T where T: std::fmt::Display, so you could take an impl std::fmt::Display and receive either a &T or a T. In other cases, you might be able to define your own trait in a similar way.

[saona-raimundo]

Okay!
To document what values are given as references and which are not, where can I look?
I would assume that everything that needs evaluation, is the result of a filter, or is a field is passed by reference. But literal values are passed without reference. Where should I look for these "literal values"?

[djc]

I think you should not document the exact rules, since they might change across otherwise semver-compatible releases. See Expr::is_copyable() for the heuristics we're using. That method is actually slightly misnamed -- naming it the other way around might make more sense (something like needs_borrow()).

[saona-raimundo]

Perfect! I changed the wording, I hope it is clear enough without too much detail.

[saona-raimundo]

Question on macro expansion: should expressions always be given by reference to filters?

[saona-raimundo]

Thank you!
I was checking it again and wanted to say that "the first argument to the filter is a reference to the expression it is applied to", but it is not totally true and found some unexpected (for me) behaviour:

Consider the templates

{{ 2|my_filter }}

and

{{ (1 + 1)|my_filter }}

I would expect both to work the same, but they do not: the first case is 2 is given directly to my filter, while in the second case &(1 + 1) is given as reference.

The problem arises for the signature of the filter: should it take a reference or not?

fn my_filter(n: usize) -> ::askama::Result<String>

works for the first case and

fn my_filter(n: &usize) -> ::askama::Result<String>

works for the second.

Question.
Is this expected for you, or should 2 be past a reference &2?

[djc]

Great work, some minor clarifications/edits suggested.