Merge pull request #613 from GuillaumeGomez/create

GuillaumeGomez · web-flow · commit cff0acca4ae8 · 2025-12-13T22:17:55.000+01:00
Add new tag to declare variable without value
diff --git a/askama_derive/src/generator/expr.rs b/askama_derive/src/generator/expr.rs
@@ -982,7 +982,6 @@ impl<'a> Generator<'a, '_> {
         DisplayWrap::Unwrapped
     }
 
-    // FIXME: This function should have a `Span`, but `cond.target` isn't `WithSpan`.
     pub(super) fn visit_target(
         &mut self,
         ctx: &Context<'_>,
diff --git a/askama_derive/src/generator/node.rs b/askama_derive/src/generator/node.rs
@@ -7,7 +7,8 @@ use std::str::FromStr;
 
 use parser::expr::BinOp;
 use parser::node::{
-    Call, Comment, Cond, CondTest, FilterBlock, If, Include, Let, Lit, Loop, Match, Whitespace, Ws,
+    Call, Comment, Cond, CondTest, Declare, FilterBlock, If, Include, Let, Lit, Loop, Match,
+    Whitespace, Ws,
 };
 use parser::{Expr, Node, Span, Target, WithSpan};
 use proc_macro2::TokenStream;
@@ -103,6 +104,9 @@ impl<'a> Generator<'a, '_> {
                 Node::Let(ref l) => {
                     self.write_let(ctx, buf, l)?;
                 }
+                Node::Declare(ref c) => {
+                    self.write_decl(ctx, buf, c)?;
+                }
                 Node::If(ref i) => {
                     size_hint += self.write_if(ctx, buf, i)?;
                 }
@@ -859,6 +863,14 @@ impl<'a> Generator<'a, '_> {
         let span = ctx.span_for_node(l.span());
 
         let Some(val) = &l.val else {
+            let file_info = ctx
+                .file_info_of(l.span())
+                .map(|info| format!(" {info}:"))
+                .unwrap_or_default();
+            eprintln!(
+                "⚠️{file_info} `let` tag will stop supporting declaring variables without value. \
+                 Use `create` instead for this case",
+            );
             self.write_buf_writable(ctx, buf)?;
             buf.write_token(Token![let], span);
             if l.is_mutable {
@@ -914,6 +926,32 @@ impl<'a> Generator<'a, '_> {
         Ok(())
     }
 
+    fn write_decl(
+        &mut self,
+        ctx: &Context<'_>,
+        buf: &mut Buffer,
+        c: &'a WithSpan<Declare<'_>>,
+    ) -> Result<(), CompileError> {
+        let span = ctx.span_for_node(c.span());
+        if *c.var_name == "_" {
+            return Err(ctx.generate_error(
+                "`_` cannot be used when there is no value assigned, use `let` instead",
+                c.var_name.span(),
+            ));
+        }
+        self.handle_ws(c.ws);
+
+        self.write_buf_writable(ctx, buf)?;
+        buf.write_token(Token![let], span);
+        if c.is_mutable {
+            buf.write_token(Token![mut], span);
+        }
+        self.visit_target(ctx, buf, false, true, &Target::Name(c.var_name), span);
+        buf.write_token(Token![;], span);
+
+        Ok(())
+    }
+
     // If `name` is `Some`, this is a call to a block definition, and we have to find
     // the first block for that name from the ancestry chain. If name is `None`, this
     // is from a `super()` call, and we can get the name from `self.super_block`.
diff --git a/askama_derive/src/input.rs b/askama_derive/src/input.rs
@@ -310,6 +310,7 @@ impl TemplateInput<'_> {
                         | Node::Expr(_, _)
                         | Node::Extends(_)
                         | Node::Let(_)
+                        | Node::Declare(_)
                         | Node::Import(_)
                         | Node::Macro(_)
                         | Node::Raw(_)
diff --git a/askama_parser/src/node.rs b/askama_parser/src/node.rs
@@ -22,6 +22,7 @@ pub enum Node<'a> {
     Expr(Ws, WithSpan<Box<Expr<'a>>>),
     Call(WithSpan<Call<'a>>),
     Let(WithSpan<Let<'a>>),
+    Declare(WithSpan<Declare<'a>>),
     If(WithSpan<If<'a>>),
     Match(WithSpan<Match<'a>>),
     Loop(WithSpan<Loop<'a>>),
@@ -93,6 +94,7 @@ impl<'a: 'l, 'l> Node<'a> {
 
         let func = match tag {
             "call" => Call::parse,
+            "decl" | "declare" => Declare::parse,
             "let" | "set" => Let::parse,
             "if" => If::parse,
             "for" => Loop::parse,
@@ -190,6 +192,7 @@ impl<'a: 'l, 'l> Node<'a> {
             Self::Expr(_, span) => span.span,
             Self::Call(span) => span.span,
             Self::Let(span) => span.span,
+            Self::Declare(span) => span.span,
             Self::If(span) => span.span,
             Self::Match(span) => span.span,
             Self::Loop(span) => span.span,
@@ -1198,6 +1201,35 @@ impl<'a: 'l, 'l> Raw<'a> {
     }
 }
 
+#[derive(Debug, PartialEq)]
+pub struct Declare<'a> {
+    pub ws: Ws,
+    pub var_name: WithSpan<&'a str>,
+    pub is_mutable: bool,
+}
+
+impl<'a: 'l, 'l> Declare<'a> {
+    fn parse(i: &mut InputStream<'a, 'l>) -> ParseResult<'a, Box<Node<'a>>> {
+        let mut p = (
+            opt(Whitespace::parse),
+            ws(alt((keyword("decl"), keyword("declare"))).span()),
+            ws(opt(keyword("mut").span())),
+            ws(identifier.with_span()),
+            opt(Whitespace::parse),
+        );
+        let (pws, span, is_mut, (var_name, var_name_span), nws) = p.parse_next(i)?;
+
+        Ok(Box::new(Node::Declare(WithSpan::new(
+            Declare {
+                ws: Ws(pws, nws),
+                var_name: WithSpan::new(var_name, var_name_span),
+                is_mutable: is_mut.is_some(),
+            },
+            span,
+        ))))
+    }
+}
+
 #[derive(Debug, PartialEq)]
 pub struct Let<'a> {
     pub ws: Ws,
diff --git a/book/src/template_syntax.md b/book/src/template_syntax.md
@@ -9,6 +9,7 @@
 | `{% filter ... %} ... {% endfilter %}` | [Filter block](#filter-blocks) |
 | `{# ... #}` | [Comment](#comments) |
 | `{% let ... = ... %}` or `{% set ... = ... %}` | [Variable assignment](#assignments) |
+| `{% decl ... %}` or `{% declare ... = ... %}` | [Set variable values later](#set-variable-values-later) |
 | `{% if ... %} ... {% else if ... %} ... {% else %} ... {% endif %}` | [If-Else conditional block](#if) |
 | `{% match ... %} {% when ... %} ... {% else %} ... {% endmatch %}` | [Match block](#match) |
 | `{% for ... in ... %} ... {% else %} ... {% endfor %}` | [For loop block](#for) |
@@ -67,14 +68,6 @@ Assignments use the `let` tag:
 ```jinja
 {% let name = user.name %}
 {% let len = name.len() %}
-
-{% let val -%}
-{% if len == 0 -%}
-  {% let val = "foo" -%}
-{% else -%}
-  {% let val = name -%}
-{% endif -%}
-{{ val }}
 ```
 
 Like Rust, Askama also supports shadowing variables.
@@ -98,6 +91,21 @@ you need it to be mutable #}
 
 For compatibility with Jinja, `set` can be used in place of `let`.
 
+### Set variable values later
+
+If you want to create a variable but set its value based on a condition, you can
+declare it without a value by using the `decl` (or `declare`) keyword:
+
+```jinja
+{% decl val -%}
+{% if len == 0 -%}
+  {% let val = "foo" -%}
+{% else -%}
+  {% let val = name -%}
+{% endif -%}
+{{ val }}
+```
+
 ### Borrow rules
 
 In some cases, the value of a variable initialization will be put behind a reference
diff --git a/book/update-theme.py b/book/update-theme.py
@@ -77,7 +77,7 @@ def update_theme(target: PathLike) -> None:
     state = "before-sidebar"
     for line in input_f:
         match state:
-            case "before-sidebar" if '<nav id="mdbook-sidebar"' in line:
+            case "before-sidebar" if '<nav ' in line and 'class="sidebar"' in line:
                 line = SIDEBAR
                 state = "in-sidebar"
             case "in-sidebar":
diff --git a/testing/tests/declare.rs b/testing/tests/declare.rs
@@ -0,0 +1,45 @@
+use askama::Template;
+
+// This test ensures that the `decl` keyword works as expected.
+#[test]
+fn decl() {
+    #[derive(Template)]
+    #[template(
+        source = r#"{%- decl x -%}
+{%- if y -%}
+    {%- let x = String::new() %}
+{%- else -%}
+    {%- let x = format!("blob") %}
+{%- endif -%}
+{{ x }}"#,
+        ext = "html"
+    )]
+    struct A {
+        y: bool,
+    }
+
+    assert_eq!(A { y: false }.render().unwrap(), "blob");
+    assert_eq!(A { y: true }.render().unwrap(), "");
+}
+
+// Same as `decl` except with the `declare` keyword.
+#[test]
+fn declare() {
+    #[derive(Template)]
+    #[template(
+        source = r#"{%- declare x -%}
+{%- if y -%}
+    {%- let x = String::new() %}
+{%- else -%}
+    {%- let x = format!("blob") %}
+{%- endif -%}
+{{ x }}"#,
+        ext = "html"
+    )]
+    struct A {
+        y: bool,
+    }
+
+    assert_eq!(A { y: false }.render().unwrap(), "blob");
+    assert_eq!(A { y: true }.render().unwrap(), "");
+}
diff --git a/testing/tests/let.rs b/testing/tests/let.rs
@@ -18,8 +18,8 @@ fn let_macro() {
         y: bool,
     }
 
-    let template = A { y: false };
-    assert_eq!(template.render().unwrap(), "blob")
+    assert_eq!(A { y: false }.render().unwrap(), "blob");
+    assert_eq!(A { y: true }.render().unwrap(), "");
 }
 
 // Ensures that variables name can start with `_`.
diff --git a/testing/tests/ui/declare.rs b/testing/tests/ui/declare.rs
@@ -0,0 +1,11 @@
+use askama::Template;
+
+#[derive(Template)]
+#[template(source = "{% decl x = 'a' %}", ext = "html")]
+struct Declare1;
+
+#[derive(Template)]
+#[template(source = "{% declare x = 'a' %}", ext = "html")]
+struct Declare2;
+
+fn main() {}
diff --git a/testing/tests/ui/declare.stderr b/testing/tests/ui/declare.stderr
@@ -0,0 +1,15 @@
+error: failed to parse template source
+ --> <source attribute>:1:10
+       "= 'a' %}"
+ --> tests/ui/declare.rs:4:21
+  |
+4 | #[template(source = "{% decl x = 'a' %}", ext = "html")]
+  |                     ^^^^^^^^^^^^^^^^^^^^
+
+error: failed to parse template source
+ --> <source attribute>:1:13
+       "= 'a' %}"
+ --> tests/ui/declare.rs:8:21
+  |
+8 | #[template(source = "{% declare x = 'a' %}", ext = "html")]
+  |                     ^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/testing/tests/ui/let.stderr b/testing/tests/ui/let.stderr
diff --git a/testing/tests/ui/underscore.rs b/testing/tests/ui/underscore.rs
@@ -16,4 +16,16 @@ struct UnderscoreErr3;
 #[template(source = r#"{% match _ %}{% endmatch %}"#, ext = "html")]
 struct UnderscoreErr4;
 
+#[derive(Template)]
+#[template(source = r#"{% let _ %}"#, ext = "html")]
+struct UnderscoreErr5;
+
+#[derive(Template)]
+#[template(source = r#"{% decl _ %}"#, ext = "html")]
+struct UnderscoreErr6;
+
+#[derive(Template)]
+#[template(source = r#"{% declare _ %}"#, ext = "html")]
+struct UnderscoreErr7;
+
 fn main() {}
diff --git a/testing/tests/ui/underscore.stderr b/testing/tests/ui/underscore.stderr
@@ -0,0 +1,55 @@
+error: reserved keyword `_` cannot be used here
+ --> <source attribute>:1:12
+       "_] %}"
+ --> tests/ui/underscore.rs:4:21
+  |
+4 | #[template(source = r#"{% let x = [_] %}"#, ext = "html")]
+  |                     ^^^^^^^^^^^^^^^^^^^^^^
+
+error: reserved keyword `_` cannot be used here
+ --> <source attribute>:1:7
+       "_ + 12) != 0 %}{% endif %}"
+ --> tests/ui/underscore.rs:8:21
+  |
+8 | #[template(source = r#"{% if (_ + 12) != 0 %}{% endif %}"#, ext = "html")]
+  |                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: reserved keyword `_` cannot be used here
+ --> <source attribute>:1:12
+       "_ %}{% endif %}"
+  --> tests/ui/underscore.rs:12:21
+   |
+12 | #[template(source = r#"{% if 12 == _ %}{% endif %}"#, ext = "html")]
+   |                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: reserved keyword `_` cannot be used here
+ --> <source attribute>:1:9
+       "_ %}{% endmatch %}"
+  --> tests/ui/underscore.rs:16:21
+   |
+16 | #[template(source = r#"{% match _ %}{% endmatch %}"#, ext = "html")]
+   |                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: when you forward-define a variable, you cannot use a pattern in place of a variable name
+ --> <source attribute>:1:7
+       "_ %}"
+  --> tests/ui/underscore.rs:20:21
+   |
+20 | #[template(source = r#"{% let _ %}"#, ext = "html")]
+   |                     ^^^^^^^^^^^^^^^^
+
+error: `_` cannot be used when there is no value assigned, use `let` instead
+ --> UnderscoreErr6.html:1:8
+       "_ %}"
+  --> tests/ui/underscore.rs:24:21
+   |
+24 | #[template(source = r#"{% decl _ %}"#, ext = "html")]
+   |                     ^^^^^^^^^^^^^^^^^
+
+error: `_` cannot be used when there is no value assigned, use `let` instead
+ --> UnderscoreErr7.html:1:11
+       "_ %}"
+  --> tests/ui/underscore.rs:28:21
+   |
+28 | #[template(source = r#"{% declare _ %}"#, ext = "html")]
+   |                     ^^^^^^^^^^^^^^^^^^^^

Original file line number	Diff line number	Diff line change
`@@ -982,7 +982,6 @@ impl<'a> Generator<'a, '_> {`
`982`	`982`	`DisplayWrap::Unwrapped`
`983`	`983`	`}`
`984`	`984`
`985`		- // FIXME: This function should have a `Span`, but `cond.target` isn't `WithSpan`.
`986`	`985`	`pub(super) fn visit_target(`
`987`	`986`	`&mut self,`
`988`	`987`	`ctx: &Context<'_>,`
Original file line number	Diff line number	Diff line change
`@@ -18,8 +18,8 @@ fn let_macro() {`
`18`	`18`	`y: bool,`
`19`	`19`	`}`
`20`	`20`
`21`		`- let template = A { y: false };`
`22`		`- assert_eq!(template.render().unwrap(), "blob")`
	`21`	`+ assert_eq!(A { y: false }.render().unwrap(), "blob");`
	`22`	`+ assert_eq!(A { y: true }.render().unwrap(), "");`
`23`	`23`	`}`
`24`	`24`
`25`	`25`	// Ensures that variables name can start with `_`.