language: Add expression literals

Add expression literals, so you can set properties of type
Gtk.Expression.

blueprintcompiler/completions.py

@@ -177,6 +177,15 @@ def property_completer(lsp, ast_node, match_variables):
                     docs=prop.doc,
                     detail=prop.detail,
                 )
+            elif prop.type.full_name == "Gtk.Expression":
+                yield Completion(
+                    prop_name,
+                    CompletionItemKind.Property,
+                    sort_text=f"0 {prop_name}",
+                    snippet=f"{prop_name}: expr $0;",
+                    docs=prop.doc,
+                    detail=prop.detail,
+                )
             else:
                 yield Completion(
                     prop_name,

blueprintcompiler/language/__init__.py

@@ -41,6 +41,7 @@ from .types import ClassName
 from .ui import UI
 from .values import (
     ArrayValue,
+    ExprLiteral,
     Flag,
     Flags,
     IdentLiteral,

blueprintcompiler/language/contexts.py

@@ -79,3 +79,9 @@ class ScopeCtx:
         for child in node.children:
             if child.context[ScopeCtx] is self:
                 yield from self._iter_recursive(child)
+
+
+@dataclass
+class ExprLiteralCtx:
+    """Indicates that the context is an expression literal, where the
+    "item" keyword may be used."""

blueprintcompiler/language/expression.py

@@ -81,6 +81,16 @@ class LiteralExpr(ExprBase):
             or self.root.is_legacy_template(self.literal.value.ident)
         )
 
+    @property
+    def is_this(self) -> bool:
+        from .values import IdentLiteral
+
+        return (
+            not self.is_object
+            and isinstance(self.literal.value, IdentLiteral)
+            and self.literal.value.ident == "item"
+        )
+
     @property
     def literal(self):
         from .values import Literal
@@ -91,6 +101,15 @@ class LiteralExpr(ExprBase):
     def type(self) -> T.Optional[GirType]:
         return self.literal.value.type
 
+    @validate()
+    def item_validations(self):
+        if self.is_this:
+            if not isinstance(self.rhs, CastExpr):
+                raise CompileError('"item" must be cast to its object type')
+
+            if not isinstance(self.rhs.rhs, LookupOp):
+                raise CompileError('"item" can only be used for looking up properties')
+
 
 class LookupOp(InfixExpr):
     grammar = [".", UseIdent("property")]
@@ -285,6 +304,9 @@ expr.children = [
 def decompile_lookup(
     ctx: DecompileCtx, gir: gir.GirContext, cdata: str, name: str, type: str
 ):
+    if ctx.parent_node is not None and ctx.parent_node.tag == "property":
+        ctx.print("expr ")
+
     if t := ctx.type_by_cname(type):
         type = decompile.full_name(t)
     else:
@@ -304,6 +326,8 @@ def decompile_lookup(
     if constant is not None:
         if constant == ctx.template_class:
             ctx.print("template." + name)
+        elif constant == "":
+            ctx.print("item as <" + type + ">." + name)
         else:
             ctx.print(constant + "." + name)
         return
@@ -318,6 +342,9 @@ def decompile_lookup(
 def decompile_constant(
     ctx: DecompileCtx, gir: gir.GirContext, cdata: str, type: T.Optional[str] = None
 ):
+    if ctx.parent_node is not None and ctx.parent_node.tag == "property":
+        ctx.print("expr ")
+
     if type is None:
         if cdata == ctx.template_class:
             ctx.print("template")
@@ -330,6 +357,9 @@ def decompile_constant(
 
 @decompiler("closure", skip_children=True)
 def decompile_closure(ctx: DecompileCtx, gir: gir.GirContext, function: str, type: str):
+    if ctx.parent_node is not None and ctx.parent_node.tag == "property":
+        ctx.print("expr ")
+
     if t := ctx.type_by_cname(type):
         type = decompile.full_name(t)
     else:

blueprintcompiler/language/gobject_object.py

@@ -28,7 +28,18 @@ from .common import *
 from .response_id import ExtResponse
 from .types import ClassName, ConcreteClassName
 
-RESERVED_IDS = {"this", "self", "template", "true", "false", "null", "none"}
+RESERVED_IDS = {
+    "this",
+    "self",
+    "template",
+    "true",
+    "false",
+    "null",
+    "none",
+    "item",
+    "expr",
+    "typeof",
+}
 
 
 class ObjectContent(AstNode):

blueprintcompiler/language/values.py

@@ -23,7 +23,8 @@ from blueprintcompiler.gir import ArrayType
 from blueprintcompiler.lsp_utils import SemanticToken
 
 from .common import *
-from .contexts import ScopeCtx, ValueTypeCtx
+from .contexts import ExprLiteralCtx, ScopeCtx, ValueTypeCtx
+from .expression import Expression
 from .gobject_object import Object
 from .types import TypeName
 
@@ -111,6 +112,35 @@ class TypeLiteral(AstNode):
         return get_docs_section("Syntax TypeLiteral")
 
 
+class ExprLiteral(AstNode):
+    grammar = [Keyword("expr"), Expression]
+
+    @property
+    def expression(self) -> Expression:
+        return self.children[Expression][0]
+
+    @validate("expr")
+    def validate_for_type(self) -> None:
+        expected_type = self.parent.context[ValueTypeCtx].value_type
+        expr_type = self.root.gir.get_type("Expression", "Gtk")
+        if expected_type is not None and not expected_type.assignable_to(expr_type):
+            raise CompileError(
+                f"Cannot convert Gtk.Expression to {expected_type.full_name}"
+            )
+
+    @docs("expr")
+    def ref_docs(self):
+        return get_docs_section("Syntax ExprLiteral")
+
+    @context(ExprLiteralCtx)
+    def expr_literal(self):
+        return ExprLiteralCtx()
+
+    @context(ValueTypeCtx)
+    def value_type(self):
+        return ValueTypeCtx(None, must_infer_type=True)
+
+
 class QuotedLiteral(AstNode):
     grammar = UseQuoted("value")
 
@@ -319,7 +349,12 @@ class IdentLiteral(AstNode):
                 if self.ident == "null":
                     if not self.context[ValueTypeCtx].allow_null:
                         raise CompileError("null is not permitted here")
-                else:
+                elif self.ident == "item":
+                    if not self.context[ExprLiteralCtx]:
+                        raise CompileError(
+                            '"item" can only be used in an expression literal'
+                        )
+                elif self.ident not in ["true", "false"]:
                     raise CompileError(
                         f"Could not find object with ID {self.ident}",
                         did_you_mean=(
@@ -375,6 +410,7 @@ class IdentLiteral(AstNode):
 class Literal(AstNode):
     grammar = AnyOf(
         TypeLiteral,
+        ExprLiteral,
         QuotedLiteral,
         NumberLiteral,
         IdentLiteral,
@@ -383,7 +419,7 @@ class Literal(AstNode):
     @property
     def value(
         self,
-    ) -> T.Union[TypeLiteral, QuotedLiteral, NumberLiteral, IdentLiteral]:
+    ) -> T.Union[TypeLiteral, ExprLiteral, QuotedLiteral, NumberLiteral, IdentLiteral]:
         return self.children[0]
 
 

blueprintcompiler/outputs/xml/__init__.py

@@ -205,6 +205,8 @@ class XmlOutput(OutputFormat):
                 xml.put_text(self._object_id(value, value.ident))
         elif isinstance(value, TypeLiteral):
             xml.put_text(value.type_name.glib_type_name)
+        elif isinstance(value, ExprLiteral):
+            self._emit_expression(value.expression, xml)
         else:
             if isinstance(value.value, float) and value.value == int(value.value):
                 xml.put_text(int(value.value))
@@ -245,6 +247,9 @@ class XmlOutput(OutputFormat):
             raise CompilerBugError()
 
     def _emit_literal_expr(self, expr: LiteralExpr, xml: XmlEmitter):
+        if expr.is_this:
+            return
+
         if expr.is_object:
             xml.start_tag("constant")
         else:

docs/reference/expressions.rst

@@ -42,8 +42,8 @@ Expressions are composed of property lookups and/or closures. Property lookups a
 
 .. _Syntax LookupExpression:
 
-Lookup Expressions
-------------------
+Lookups
+-------
 
 .. rst-class:: grammar-block
 
@@ -56,8 +56,8 @@ The type of a property expression is the type of the property it refers to.
 
 .. _Syntax ClosureExpression:
 
-Closure Expressions
--------------------
+Closures
+--------
 
 .. rst-class:: grammar-block
 
@@ -72,8 +72,8 @@ Blueprint doesn't know the closure's return type, so closure expressions must be
 
 .. _Syntax CastExpression:
 
-Cast Expressions
-----------------
+Casts
+-----
 
 .. rst-class:: grammar-block
 
@@ -81,7 +81,32 @@ Cast Expressions
 
 Cast expressions allow Blueprint to know the type of an expression when it can't otherwise determine it. This is necessary for closures and for properties of application-defined types.
 
+Example
+~~~~~~~
+
 .. code-block:: blueprint
 
    // Cast the result of the closure so blueprint knows it's a string
-   label: bind $my_closure() as <string>
+   label: bind $format_bytes(template.file-size) as <string>
+
+.. _Syntax ExprLiteral:
+
+Expression Literals
+-------------------
+
+.. rst-class:: grammar-block
+
+   ExprLiteral = 'expr' :ref:`Expression<Syntax Expression>`
+
+Some APIs take *an expression itself*--not its result--as a property value. For example, `Gtk.BoolFilter <https://docs.gtk.org/gtk4/class.BoolFilter.html>`_ has an ``expression`` property of type `Gtk.Expression <https://docs.gtk.org/gtk4/class.Expression.html>`_. This expression is evaluated for every item in a list model to determine whether the item should be filtered.
+
+To define an expression for such a property, use ``expr`` instead of ``bind``. Inside the expression, you can use the ``item`` keyword to refer to the item being evaluated. You must cast the item to the correct type using the ``as`` keyword, and you can only use ``item`` in a property lookup--you may not pass it to a closure.
+
+Example
+~~~~~~~
+
+.. code-block:: blueprint
+
+   BoolFilter {
+     expression: expr item as <$UserAccount>.active;
+   }

tests/sample_errors/expr_item_not_cast.blp

@@ -0,0 +1,5 @@
+using Gtk 4.0;
+
+BoolFilter {
+  expression: expr item.visible;
+}

tests/sample_errors/expr_item_not_cast.err

@@ -0,0 +1 @@
+4,20,4,"item" must be cast to its object type

tests/sample_errors/expr_literal_assignment.blp

@@ -0,0 +1,5 @@
+using Gtk 4.0;
+
+Label {
+  label: expr 1;
+}

tests/sample_errors/expr_literal_assignment.err

@@ -0,0 +1 @@
+4,10,4,Cannot convert Gtk.Expression to string

tests/sample_errors/expr_literal_closure_arg.blp

@@ -0,0 +1,5 @@
+using Gtk 4.0;
+
+BoolFilter {
+  expression: expr $closure(item as <Entry>) as <bool>;
+}

tests/sample_errors/expr_literal_closure_arg.err

@@ -0,0 +1 @@
+4,29,4,"item" can only be used for looking up properties

tests/sample_errors/expr_literal_item.blp

@@ -0,0 +1,5 @@
+using Gtk 4.0;
+
+BoolFilter {
+  expression: expr item as <Label>;
+}

tests/sample_errors/expr_literal_item.err

@@ -0,0 +1 @@
+4,20,4,"item" can only be used for looking up properties

tests/samples/bind_expr_prop.blp

@@ -0,0 +1,9 @@
+using Gtk 4.0;
+
+BoolFilter filter1 {
+  expression: expr true;
+}
+
+BoolFilter filter2 {
+  expression: bind filter1.expression;
+}

tests/samples/bind_expr_prop.ui

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+DO NOT EDIT!
+This file was @generated by blueprint-compiler. Instead, edit the
+corresponding .blp file and regenerate this file with blueprint-compiler.
+-->
+<interface>
+  <requires lib="gtk" version="4.0"/>
+  <object class="GtkBoolFilter" id="filter1">
+    <property name="expression">
+      <constant type="gboolean">true</constant>
+    </property>
+  </object>
+  <object class="GtkBoolFilter" id="filter2">
+    <property name="expression" bind-source="filter1" bind-property="expression" bind-flags="sync-create"/>
+  </object>
+</interface>

tests/samples/bind_literal.blp

@@ -0,0 +1,5 @@
+using Gtk 4.0;
+
+Label {
+  label: bind "Hello, world!";
+}

tests/samples/bind_literal.ui

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+DO NOT EDIT!
+This file was @generated by blueprint-compiler. Instead, edit the
+corresponding .blp file and regenerate this file with blueprint-compiler.
+-->
+<interface>
+  <requires lib="gtk" version="4.0"/>
+  <object class="GtkLabel">
+    <binding name="label">
+      <constant type="gchararray">Hello, world!</constant>
+    </binding>
+  </object>
+</interface>

tests/samples/expr_literal.blp

@@ -0,0 +1,5 @@
+using Gtk 4.0;
+
+BoolFilter {
+  expression: expr item as <Entry>.visible;
+}

tests/samples/expr_literal.ui

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+DO NOT EDIT!
+This file was @generated by blueprint-compiler. Instead, edit the
+corresponding .blp file and regenerate this file with blueprint-compiler.
+-->
+<interface>
+  <requires lib="gtk" version="4.0"/>
+  <object class="GtkBoolFilter">
+    <property name="expression">
+      <lookup name="visible" type="GtkEntry"></lookup>
+    </property>
+  </object>
+</interface>

tests/samples/expr_literal_closure.blp

@@ -0,0 +1,5 @@
+using Gtk 4.0;
+
+BoolFilter {
+  expression: expr $closure(item as <Entry>.visible) as <bool>;
+}

tests/samples/expr_literal_closure.ui

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+DO NOT EDIT!
+This file was @generated by blueprint-compiler. Instead, edit the
+corresponding .blp file and regenerate this file with blueprint-compiler.
+-->
+<interface>
+  <requires lib="gtk" version="4.0"/>
+  <object class="GtkBoolFilter">
+    <property name="expression">
+      <closure function="closure" type="gboolean">
+        <lookup name="visible" type="GtkEntry"></lookup>
+      </closure>
+    </property>
+  </object>
+</interface>

tests/samples/expr_literal_literal.blp

@@ -0,0 +1,5 @@
+using Gtk 4.0;
+
+BoolFilter {
+  expression: expr true;
+}

tests/samples/expr_literal_literal.ui

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+DO NOT EDIT!
+This file was @generated by blueprint-compiler. Instead, edit the
+corresponding .blp file and regenerate this file with blueprint-compiler.
+-->
+<interface>
+  <requires lib="gtk" version="4.0"/>
+  <object class="GtkBoolFilter">
+    <property name="expression">
+      <constant type="gboolean">true</constant>
+    </property>
+  </object>
+</interface>

tests/test_samples.py

@@ -198,6 +198,7 @@ class TestSamples(unittest.TestCase):
                 "adw_breakpoint_template",
                 "expr_closure",
                 "expr_closure_args",
+                "expr_literal_closure",
                 "parseable",
                 "signal",
                 "signal_not_swapped",