New expressions

Author: RoboNET

docs/wiki/Template-Expressions.md

@@ -31,7 +31,7 @@ Variables can be used in most string properties: `content`, `data`, `src`, `colo
 
 ## Inline Expressions
 
-FlexRender supports inline expressions within `{{ }}` delimiters. Expressions extend simple variable substitution with arithmetic, null coalescing, and filters.
+FlexRender supports inline expressions within `{{ }}` delimiters. Expressions extend simple variable substitution with arithmetic, comparison operators, logical NOT, null coalescing, and filters.
 
 ### Arithmetic
 
@@ -57,6 +57,52 @@ Arithmetic operators work on numeric values:
 
 Both operands must be numeric (NumberValue). Division by zero returns a null value.
 
+### Comparison Operators
+
+Comparison operators return boolean values and are primarily used in `{{#if}}` conditions:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `==` | Equal | `{{#if status == 'paid'}}...{{/if}}` |
+| `!=` | Not equal | `{{#if status != 'cancelled'}}...{{/if}}` |
+| `<` | Less than | `{{#if stock < 5}}...{{/if}}` |
+| `>` | Greater than | `{{#if total > 1000}}...{{/if}}` |
+| `<=` | Less than or equal | `{{#if quantity <= 10}}...{{/if}}` |
+| `>=` | Greater than or equal | `{{#if rating >= 4}}...{{/if}}` |
+
+```yaml
+# Show status based on comparison
+- type: text
+  content: "{{#if total > 1000}}Free shipping!{{else}}Shipping: 10${{/if}}"
+
+# Check string equality
+- type: text
+  content: "{{#if status == 'paid'}}Payment received{{else}}Awaiting payment{{/if}}"
+```
+
+Comparison rules:
+- **Numbers**: compared by value (`100 == 100.0` is true)
+- **Strings**: compared using ordinal (case-sensitive) comparison
+- **Booleans**: only `==` and `!=` supported; ordered comparisons return false
+- **Null**: `null == null` is true; `null != <anything>` is true; ordered comparisons with null return false
+- **Mixed types** (e.g., string vs number): `==` is false, `!=` is true, ordered comparisons return false
+
+### Logical NOT
+
+The `!` operator inverts the truthiness of a value:
+
+```yaml
+# Show when NOT active
+- type: text
+  content: "{{#if !active}}Account is inactive{{/if}}"
+
+# NOT with comparison
+- type: text
+  content: "{{#if !(total > 1000)}}Standard shipping{{/if}}"
+```
+
+The `!` operator evaluates the operand for [truthiness](#conditional-blocks) and returns the opposite boolean value.
+
 ### Null Coalescing
 
 The `??` operator provides a fallback when the left side is null or missing:
@@ -127,11 +173,12 @@ Operators are evaluated in this order (highest to lowest):
 
 | Precedence | Operators |
 |------------|-----------|
-| 1 (highest) | Unary minus (`-x`) |
+| 1 (highest) | Logical NOT (`!x`), Unary minus (`-x`) |
 | 2 | Multiplication, Division (`*`, `/`) |
 | 3 | Addition, Subtraction (`+`, `-`) |
-| 4 | Null coalescing (`??`) |
-| 5 (lowest) | Filter pipe (`\|`) |
+| 4 | Comparison (`==`, `!=`, `<`, `>`, `<=`, `>=`) |
+| 5 | Null coalescing (`??`) |
+| 6 (lowest) | Filter pipe (`\|`) |
 
 ### Expression Limits
 
@@ -173,6 +220,119 @@ public interface ITemplateFilter
 }
 ```
 
+---
+
+## Text Blocks
+
+Text blocks provide control flow inside `content` strings. They are processed by the template engine at render time.
+
+> **Note:** Text blocks (`{{#if}}`, `{{#each}}`) work inside text `content` values. For element-level conditions and loops, use the `if` and `for-each` element properties instead.
+
+### Conditional Blocks
+
+```
+{{#if condition}}...{{/if}}
+{{#if condition}}...{{else}}...{{/if}}
+```
+
+The condition is evaluated for truthiness:
+
+| Value | Truthy? |
+|-------|---------|
+| Non-empty string | Yes |
+| Non-zero number | Yes |
+| `true` | Yes |
+| Non-empty array | Yes |
+| Non-empty object | Yes |
+| `null` / missing key | No |
+| Empty string `""` | No |
+| `0` | No |
+| `false` | No |
+| Empty array `[]` | No |
+
+Conditions support full expressions including comparison operators, logical NOT, null coalescing, arithmetic, and filters:
+
+```yaml
+- type: text
+  content: "{{#if name}}Hello {{name}}{{else}}Hello guest{{/if}}"
+
+- type: text
+  content: "{{#if name ?? nickname}}Hi {{name ?? nickname}}{{/if}}"
+
+- type: text
+  content: "{{#if count}}{{count}} items{{else}}No items{{/if}}"
+
+# Comparison in conditions
+- type: text
+  content: "{{#if count > 0}}{{count}} items{{else}}No items{{/if}}"
+
+- type: text
+  content: "{{#if status == 'active'}}Online{{else}}Offline{{/if}}"
+
+# Logical NOT in conditions
+- type: text
+  content: "{{#if !disabled}}Feature enabled{{/if}}"
+```
+
+### Loop Blocks
+
+```
+{{#each arrayPath}}...{{/each}}
+```
+
+Iterates over an array. Inside the loop body, the current item's properties are accessible directly. Loop variables:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `@index` | number | 0-based iteration index |
+| `@first` | bool | `true` for the first item |
+| `@last` | bool | `true` for the last item |
+
+```yaml
+- type: text
+  content: "{{#each items}}{{name}}{{#if @last}}.{{else}}, {{/if}}{{/each}}"
+
+# Output with items=[{name:"A"},{name:"B"},{name:"C"}]: "A, B, C."
+```
+
+### Nesting
+
+Text blocks can be nested. The maximum nesting depth is controlled by `ResourceLimits.MaxTemplateNestingDepth` (default: 100).
+
+```yaml
+- type: text
+  content: "{{#each groups}}[{{#each items}}{{val}}{{/each}}]{{/each}}"
+
+- type: text
+  content: "{{#each users}}{{#if active}}{{name}} {{/if}}{{/each}}"
+```
+
+### String Literals and Escape Sequences
+
+String literals in expressions support both single and double quotes:
+
+```
+{{name ?? "default"}}
+{{name ?? 'default'}}
+```
+
+Escape sequences are supported inside string literals:
+
+| Escape | Result |
+|--------|--------|
+| `\\` | `\` |
+| `\"` | `"` |
+| `\'` | `'` |
+| `\n` | newline |
+| `\t` | tab |
+
+```yaml
+- type: text
+  content: "{{greeting ?? 'it\\'s a default'}}"
+```
+
+---
+
 ### Data Structure
 
 Data is passed as `ObjectValue`:

src/FlexRender.Core/TemplateEngine/InlineExpression.cs

@@ -72,3 +72,42 @@ public sealed record FilterExpression(InlineExpression Input, string FilterName,
 /// </summary>
 /// <param name="Operand">The expression to negate.</param>
 public sealed record NegateExpression(InlineExpression Operand) : InlineExpression;
+
+/// <summary>
+/// Comparison operators supported in inline expressions.
+/// </summary>
+public enum ComparisonOperator
+{
+    /// <summary>Equality operator (==).</summary>
+    Equal,
+
+    /// <summary>Inequality operator (!=).</summary>
+    NotEqual,
+
+    /// <summary>Less than operator (&lt;).</summary>
+    LessThan,
+
+    /// <summary>Greater than operator (&gt;).</summary>
+    GreaterThan,
+
+    /// <summary>Less than or equal operator (&lt;=).</summary>
+    LessThanOrEqual,
+
+    /// <summary>Greater than or equal operator (&gt;=).</summary>
+    GreaterThanOrEqual
+}
+
+/// <summary>
+/// A binary comparison expression (e.g., <c>price &gt; 100</c>, <c>status == "paid"</c>).
+/// </summary>
+/// <param name="Left">The left operand.</param>
+/// <param name="Op">The comparison operator.</param>
+/// <param name="Right">The right operand.</param>
+public sealed record ComparisonExpression(InlineExpression Left, ComparisonOperator Op, InlineExpression Right) : InlineExpression;
+
+/// <summary>
+/// A logical NOT expression (e.g., <c>!isActive</c>).
+/// Returns true when the operand is falsy, false when truthy.
+/// </summary>
+/// <param name="Operand">The expression to negate logically.</param>
+public sealed record NotExpression(InlineExpression Operand) : InlineExpression;

src/FlexRender.Core/TemplateEngine/InlineExpressionEvaluator.cs

@@ -13,6 +13,10 @@ namespace FlexRender.TemplateEngine;
 ///   <item>String + number (mixed types) produces <see cref="NullValue"/> (no implicit coercion).</item>
 ///   <item>Division by zero produces <see cref="NullValue"/> (no exception).</item>
 ///   <item>Null coalesce: returns right if left is <see cref="NullValue"/>.</item>
+///   <item>Comparison operators (<c>==</c>, <c>!=</c>, <c>&lt;</c>, <c>&gt;</c>, <c>&lt;=</c>, <c>&gt;=</c>)
+///     produce <see cref="BoolValue"/>. Null compared to null is equal; null compared to non-null
+///     yields false for all ordered comparisons (SQL NULL semantics).</item>
+///   <item>Logical NOT (<c>!</c>) returns <see cref="BoolValue"/> based on the truthiness of the operand.</item>
 /// </list>
 /// </remarks>
 public sealed class InlineExpressionEvaluator
@@ -73,9 +77,11 @@ public TemplateValue Evaluate(InlineExpression expression, TemplateContext conte
             NumberLiteral num => new NumberValue(num.Value),
             StringLiteral str => new StringValue(str.Value),
             ArithmeticExpression arith => EvaluateArithmetic(arith, context),
+            ComparisonExpression comp => EvaluateComparison(comp, context),
             CoalesceExpression coal => EvaluateCoalesce(coal, context),
             FilterExpression filter => EvaluateFilter(filter, context),
             NegateExpression neg => EvaluateNegate(neg, context),
+            NotExpression not => EvaluateNot(not, context),
             _ => NullValue.Instance
         };
     }
@@ -140,4 +146,70 @@ private TemplateValue EvaluateNegate(NegateExpression expr, TemplateContext cont
 
         return NullValue.Instance;
     }
+
+    private BoolValue EvaluateComparison(ComparisonExpression expr, TemplateContext context)
+    {
+        var left = Evaluate(expr.Left, context);
+        var right = Evaluate(expr.Right, context);
+
+        // Both null
+        if (left is NullValue && right is NullValue)
+        {
+            return new BoolValue(expr.Op is ComparisonOperator.Equal or ComparisonOperator.LessThanOrEqual or ComparisonOperator.GreaterThanOrEqual);
+        }
+
+        // One null
+        if (left is NullValue || right is NullValue)
+        {
+            return new BoolValue(expr.Op == ComparisonOperator.NotEqual);
+        }
+
+        // Number comparison
+        if (left is NumberValue leftNum && right is NumberValue rightNum)
+        {
+            var cmp = leftNum.Value.CompareTo(rightNum.Value);
+            return new BoolValue(CompareResult(cmp, expr.Op));
+        }
+
+        // String comparison
+        if (left is StringValue leftStr && right is StringValue rightStr)
+        {
+            var cmp = string.Compare(leftStr.Value, rightStr.Value, StringComparison.Ordinal);
+            return new BoolValue(CompareResult(cmp, expr.Op));
+        }
+
+        // Bool comparison (only == and !=)
+        if (left is BoolValue leftBool && right is BoolValue rightBool)
+        {
+            return expr.Op switch
+            {
+                ComparisonOperator.Equal => new BoolValue(leftBool.Value == rightBool.Value),
+                ComparisonOperator.NotEqual => new BoolValue(leftBool.Value != rightBool.Value),
+                _ => new BoolValue(false) // ordered comparison on bools is always false
+            };
+        }
+
+        // Mixed types: == is false, != is true, ordered is false
+        return new BoolValue(expr.Op == ComparisonOperator.NotEqual);
+    }
+
+    private static bool CompareResult(int cmp, ComparisonOperator op)
+    {
+        return op switch
+        {
+            ComparisonOperator.Equal => cmp == 0,
+            ComparisonOperator.NotEqual => cmp != 0,
+            ComparisonOperator.LessThan => cmp < 0,
+            ComparisonOperator.GreaterThan => cmp > 0,
+            ComparisonOperator.LessThanOrEqual => cmp <= 0,
+            ComparisonOperator.GreaterThanOrEqual => cmp >= 0,
+            _ => false
+        };
+    }
+
+    private BoolValue EvaluateNot(NotExpression expr, TemplateContext context)
+    {
+        var operand = Evaluate(expr.Operand, context);
+        return new BoolValue(!ExpressionEvaluator.IsTruthy(operand));
+    }
 }