Add askama::filter_fn proc-macro for custom filters with named/optional arg support

[seijikun]

This adds an initial implementation of the filter_fn proc-macro idea pitched here.

Reading commit-by-commit will look less noisy, but the actual proc-macro implementation is one large commit either way.
The implementation has quite some logic to calculate generic parameters. I documented what is happening in the code comments as best as I could.

This:

• Transforms existing freestanding custom filter functions (just annotate the method with #[askama::filter_fn]
• Supports required and optional filter arguments (with default values)
• Supports generic parameters for required filter arguments
• Supports generic parameters for the filter's input argument

Some limitations apply. This currently:

• Doesn't support parsing where clauses. (Bounds currently have to reside within the angle brackets)
• Doesn't support using generic parameters for optional filter arguments
• Doesn't support impl <Trait> notation for filter arguments
• Doesn't support custom lifetime parameters

This is my first proc-macro. So please bear with me 😅
The current version probably doesn't provide the best compiler diagnostics possible. I plan on incrementally improving this, if you have some pointers for me.

[GuillaumeGomez]

If you don't mind, let's wait until https://github.com/GuillaumeGomez/askama/tree/tokenstream is finished because otherwise I'll take forever to finish my rebases. ^^'

[seijikun]

If you don't mind, let's wait until https://github.com/GuillaumeGomez/askama/tree/tokenstream is finished because otherwise I'll take forever to finish my rebases. ^^'

sure, no problem!

[GuillaumeGomez]

I finally opened #558. Once merged and this PR has been rebased (sorry in advance for merge conflicts ><), time for reviews. :)

[GuillaumeGomez]

#558 was merged so when the merge conflicts are merged, let's review it! :)

[seijikun]

The Port askama to new filter_fn proc-macro-attr commit looks probably super dumb.
I'm not quite sure whether I used everything correctly 😅
But it still works, so....

[GuillaumeGomez]

Looks good to me overall. Please add ui errors test to ensure we emit errors correctly if the attributes is misused or malformed and then it looks good to me.

[seijikun]

Looks good to me overall. Please add ui errors test to ensure we emit errors correctly if the attributes is misused or malformed and then it looks good to me.

I just tried writing some ui tests to check some of the signature validation. But I somehow always get this as compiler output:

error[E0433]: failed to resolve: could not find `compile_error` in `core`

Did I accidentally use a nightly feature in my compiler error generation?

[GuillaumeGomez]

That seems surprising. What does the generated code looks like?

[seijikun]

I created a new project, added askama as dependency and added this above the main function:

#[askama::filter_fn]
pub fn filter1(input: usize) {
}

This should trigger the assert: p_assert!(sig.inputs.len() >= 2, sig.span() => "Filter function missing required input and environment args")?;.
Which compiles to:

if sig.inputs.len() >= 2 {
    return Err(syn::Error::new(sig.span(), "Filter function missing required input and environment args"));
}

The generated syn::Error is propagated up into the proc-macro's entry point, where it's converted to a TokenStream and returned:

askama/askama_macros/src/lib.rs

Line 25 in dd10583

Err(err) => err.into_compile_error().into(),

I get a proper error message, with both nightly and stable compiler:

But inside the ui-tests, for the same code, I just get error[E0433]: failed to resolve: could not find compile_error in core.

[GuillaumeGomez]

Gonna try to understand what's going on when I have some time if you or @Kijewski didn't figure out by then.

[Kijewski]

I rebased the PR and moved the code generation into askama_derive. Because the function needs syn with feature "full", I un-feature-gated the block code, because it was only feature-gated so we don't have to depend on syn/full. Needing syn/full does not make me happy. :-/

Did not review the rest of the code, yet.

[seijikun]

Needing syn/full does not make me happy. :-/

Yeah, it's unfortunate, but I couldn't find a way around it.

On the other hand, syn is a proc-macro dependency, so it should only ever be built once in an enduser application's lifetime and it won't be part of the resulting binary.
And if you're using askama for something bigger, you won't live a happy life without:

[profile.dev.package.askama_derive]
opt-level = 3

anyway. So I expect the effect on the enduser to be on the smaller side.

[GuillaumeGomez]

Do you mind fixing the merge conflicts? I'll merge once done. I can do it if you don't know how.

[seijikun]

seijikun fixing the merge conflicts - 2025, colorized

[GuillaumeGomez]

Looks good to me, thanks! Just realized: doc is missing. Please add onto the book too. :)

[seijikun]

Looks good to me, thanks! Just realized: doc is missing. Please add onto the book too. :)

This is one of the next steps noted down in: #561
I will start new PRs for these, if that's okay for you.

[GuillaumeGomez]

I'd prefer if docs came along the new feature directly. Simpler to keep track. :-/

[seijikun]

@GuillaumeGomez Just updated the Book on custom filter implementations.
Is there any other documentation work you were missing?

[GuillaumeGomez]

Just one question then it's ready. :)

[GuillaumeGomez]

It's ready. Sorry for taking so long and thanks a lot for your work!

[seijikun]

It's ready. Sorry for taking so long and thanks a lot for your work!

No worries!
Thank you for all of your work on this awesome library!
We (re-)built our entire company website (https://www.ip-projects.de) based on it and are fascinated with the speed!

[GuillaumeGomez]

Wow, that's super cool. Maybe we should add a list of projects/websites using askama. :3