feat: add macro support, new filters, negative array indexing and improved error handling

- Add macro support with {% macro %} and {% endmacro %} blocks
- Add new filters: tojson, map, and indent
- Add support for Python-style negative array indices (e.g., messages[-1])
- Fix undefined array key errors in parser and lexer with proper bounds checking
- Add support for for-else loops with {% else %} blocks
- Add select expressions for conditional value selection
- Improve error messages and exception handling throughout
- Add JsonSerializable interface to runtime values
- Support both lowercase and uppercase boolean literals (true/false, True/False)

Author: CodeWithKyrian

src/AST/ForStatement.php

@@ -2,23 +2,26 @@
 
 declare(strict_types=1);
 
-
 namespace Codewithkyrian\Jinja\AST;
 
+/**
+ * Loop over each item in a sequence
+ * https://jinja.palletsprojects.com/en/3.0.x/templates/#for
+ */
 class ForStatement extends Statement
 {
     public string $type = "For";
 
     /**
-     * @param Identifier|TupleLiteral $loopvar
-     * @param Expression $iterable
-     * @param Statement[] $body
+     * @param Identifier|TupleLiteral $loopvar The variable to loop over
+     * @param Expression $iterable The iterable to loop over
+     * @param Statement[] $body The block to render for each item in the iterable
+     * @param Statement[]|null $defaultBlock Optional default block to render if the iterable is empty
      */
     public function __construct(
         public Identifier|TupleLiteral $loopvar,
-        public Expression              $iterable,
-        public array                   $body
-    )
-    {
-    }
-}
+        public Expression|SelectExpression $iterable,
+        public array                   $body,
+        public ?array                  $defaultBlock = null
+    ) {}
+}

src/AST/Macro.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codewithkyrian\Jinja\AST;
+
+class Macro extends Statement
+{
+    public string $type = "Macro";
+
+    /**
+     * @param Identifier $name The name of the macro
+     * @param Expression[] $args The arguments of the macro
+     * @param Statement[] $body The body of the macro
+     */
+    public function __construct(public Identifier $name, public array $args, public array $body) {}
+}

src/AST/SelectExpression.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codewithkyrian\Jinja\AST;
+
+class SelectExpression extends Expression
+{
+    public string $type = "SelectExpression";
+
+    public function __construct(public Expression $lhs, public Expression $test) {}
+}

src/AST/SetStatement.php

@@ -12,7 +12,5 @@ class SetStatement extends Statement
     public function __construct(
         public Expression $assignee,
         public Expression $value
-    )
-    {
-    }
-}
+    ) {}
+}

src/Core/Environment.php

@@ -70,6 +70,7 @@ public function __construct(?Environment $parent = null)
             },
             'false' => fn(RuntimeValue $operand) => $operand->type === "BooleanValue" && !$operand->value,
             'true' => fn(RuntimeValue $operand) => $operand->type === "BooleanValue" && $operand->value,
+            'string' => fn(RuntimeValue $operand) => $operand->type === "StringValue",
             'number' => fn(RuntimeValue $operand) => $operand->type === "NumericValue",
             'integer' => function (RuntimeValue $operand) {
                 if ($operand->type !== "NumericValue") {
@@ -102,6 +103,12 @@ public function __construct(?Environment $parent = null)
             'equalto' => function (RuntimeValue $a, RuntimeValue $b) {
                 return $a->value === $b->value;
             },
+            'eq' => function (RuntimeValue $a, RuntimeValue $b) {
+                return $a->value === $b->value;
+            },
+            'ne' => function (RuntimeValue $a, RuntimeValue $b) {
+                return $a->value !== $b->value;
+            }
         ];
     }
 
@@ -155,6 +162,9 @@ public function lookupVariable(string $name): RuntimeValue
     }
 
 
+    /**
+     * Helper function to convert a PHP value to a runtime value.
+     */
     public static function convertToRuntimeValues(mixed $input): RuntimeValue
     {
         if (is_numeric($input)) {
@@ -170,30 +180,23 @@ public static function convertToRuntimeValues(mixed $input): RuntimeValue
         }
 
         if (is_callable($input)) {
-            // Wrap the PHP callable in a runtime function value
             return new FunctionValue(function ($args, $scope) use ($input) {
-                // Assuming args are also runtime values; extract their inner values for the callable
-                $plainArgs = array_map(function ($arg) {
-                    return $arg->value;
-                }, $args);
+                $plainArgs = array_map(fn($arg) => $arg->value, $args);
                 $result = call_user_func_array($input, $plainArgs);
-                // Convert the result back to a runtime value
                 return $this->convertToRuntimeValues($result);
             });
         }
 
         if (is_array($input)) {
-            if (array_keys($input) !== range(0, count($input) - 1)) {
-                // Associative array, treat as ObjectValue
-                $convertedItems = [];
-                foreach ($input as $key => $value) {
-                    $convertedItems[$key] = self::convertToRuntimeValues($value);
-                }
-                return new ObjectValue($convertedItems);
-            } else {
-                // Sequential array, treat as ArrayValue
+            if (array_is_list($input)) {
                 return new ArrayValue(array_map(self::convertToRuntimeValues(...), $input));
             }
+
+            $convertedItems = [];
+            foreach ($input as $key => $value) {
+                $convertedItems[$key] = self::convertToRuntimeValues($value);
+            }
+            return new ObjectValue($convertedItems);
         }
 
         if (is_callable($input)) {
@@ -213,5 +216,4 @@ public static function convertToRuntimeValues(mixed $input): RuntimeValue
 
         throw new RuntimeException("Cannot convert to runtime value: Unsupported type");
     }
-
 }