feat: enhance template rendering and add new string manipulation functions

- Update the render method to accept nullable associative arrays for user-defined variables.
- Introduce a new 'mapping' filter in the Environment class to check for ObjectValue instances.
- Add a 'join' filter in the Interpreter class for concatenating array or string values with a specified separator.
- Improve error handling in array filters to provide clearer messages.
- Refactor the Parser class to streamline member and call expression parsing.

Author: CodeWithKyrian

src/Core/Environment.php

@@ -80,6 +80,7 @@ public function __construct(?Environment $parent = null)
                 return is_int($operand->value);
             },
             'iterable' => fn(RuntimeValue $operand) => $operand instanceof ArrayValue || $operand instanceof StringValue,
+            'mapping' => fn(RuntimeValue $operand) => $operand instanceof ObjectValue,
             'lower' => function (RuntimeValue $operand) {
                 if ($operand->type !== "StringValue") {
                     return false;

src/Core/Interpreter.php

@@ -385,29 +385,45 @@ private function evaluateFilterExpression(FilterExpression $node, Environment $e
 
             if ($filterName === "tojson") {
                 return new StringValue(json_encode($operand));
+            } elseif ($filterName === "join") {
+                if ($operand instanceof StringValue) {
+                    $value = mb_str_split($operand->value);
+                } elseif ($operand instanceof ArrayValue) {
+                    $value = $operand->value;
+                } else {
+                    throw new \Exception("Cannot apply join filter to type: $operand->type");
+                }
+
+                [$args, $kwargs] = $this->evaluateArguments($filter->args, $environment);
+                $separator = $args[0] ?? $kwargs["separator"] ?? new StringValue("");
+
+                if (!($separator instanceof StringValue)) {
+                    throw new \Exception("separator must be a string");
+                }
+
+                return new StringValue(implode($separator->value, $value));
             }
 
             if ($operand instanceof ArrayValue) {
                 switch ($filterName) {
                     case "selectattr":
-                        // Check if all items in the array are instances of ObjectValue
+                    case "rejectattr":
                         if (array_some($operand->value, fn($x) => !($x instanceof ObjectValue))) {
-                            throw new \Exception("`selectattr` can only be applied to an array of objects");
+                            throw new \Exception("`$filterName` can only be applied to an array of objects");
                         }
 
                         if (array_some($filter->args, fn($x) => $x->type !== "StringLiteral")) {
-                            throw new \Exception("The arguments of `selectattr` must be strings");
+                            throw new \Exception("The arguments of `$filterName` must be strings");
                         }
 
-
                         [$attrExpr, $testNameExpr, $valueExpr] = $filter->args;
 
                         $attr = $this->evaluate($attrExpr, $environment);
                         $testName = isset($testNameExpr) ? $this->evaluate($testNameExpr, $environment) : null;
                         $value = isset($valueExpr) ? $this->evaluate($valueExpr, $environment) : null;
 
                         if (!($attr instanceof StringValue)) {
-                            throw new \Exception("The attribute name of `selectattr` must be a string");
+                            throw new \Exception("The attribute name of `$filterName` must be a string");
                         }
 
                         $testFunction = null;
@@ -424,11 +440,16 @@ private function evaluateFilterExpression(FilterExpression $node, Environment $e
 
                         $filtered = [];
                         foreach ($operand->value as $item) {
-                            $a = $item->value[$attr->value] ?? null;
-                            if ($a !== null) {
-                                if ($testFunction($a, $value)) {
-                                    $filtered[] = $item;
-                                }
+                            $attrValue = $item->value[$attr->value] ?? null;
+                            if ($attrValue === null) {
+                                continue;
+                            }
+
+                            $testResult = $testFunction($attrValue, $value);
+                            $shouldInclude = ($filterName === "selectattr") ? $testResult : !$testResult;
+
+                            if ($shouldInclude) {
+                                $filtered[] = $item;
                             }
                         }
 

src/Core/Parser.php

@@ -417,20 +417,26 @@ private function parseAdditiveExpression(): Statement
 
     private function parseCallMemberExpression(): Statement
     {
-        $member = $this->parseMemberExpression();
+        $member = $this->parseMemberExpression($this->parsePrimaryExpression());
+
         if ($this->is(TokenType::OpenParen)) {
             return $this->parseCallExpression($member);
         }
+
         return $member;
     }
 
-    private function parseCallExpression($callee): CallExpression
+    private function parseCallExpression(Statement $callee): CallExpression
     {
-        $callExpression = new CallExpression($callee, $this->parseArgs());
+        $expression = new CallExpression($callee, $this->parseArgs());
+
+        $expression = $this->parseMemberExpression($expression); // foo->x()->y
+
         if ($this->is(TokenType::OpenParen)) {
-            $callExpression = $this->parseCallExpression($callExpression);
+            $expression = $this->parseCallExpression($expression); // foo->x()()
         }
-        return $callExpression;
+
+        return $expression;
     }
 
     /**
@@ -502,9 +508,8 @@ private function parseMemberExpressionArgumentsList(): Statement
         return $slices[0];
     }
 
-    private function parseMemberExpression(): Statement
+    private function parseMemberExpression(Statement $object): Statement
     {
-        $object = $this->parsePrimaryExpression();
 
         while ($this->is(TokenType::Dot) || $this->is(TokenType::OpenSquareBracket)) {
             $operator = $this->tokens[$this->current]; // . or [

src/Runtime/StringValue.php

@@ -21,7 +21,8 @@ public function __construct(string $value)
             "title" => new FunctionValue(fn() => new StringValue(toTitleCase($this->value))),
             "length" => new NumericValue(strlen($this->value)),
             "rstrip" => new FunctionValue(fn() => new StringValue(rtrim($this->value))),
-            "lstrip" => new FunctionValue(fn() => new StringValue(ltrim($this->value)))
+            "lstrip" => new FunctionValue(fn() => new StringValue(ltrim($this->value))),
+            "split" => new FunctionValue(fn($args) => new ArrayValue(explode($args[0] ?? ' ', $this->value, $args[1] ?? -1))),
         ];
     }
 }

src/Template.php

@@ -31,10 +31,10 @@ public function __construct(string $template)
     /**
      * Renders the template with the provided items as variables.
      *
-     * @param array $items Associative array of user-defined variables.
+     * @param ?array $items Associative array of user-defined variables.
      * @return string The rendered template.
      */
-    public function render(array $items): string
+    public function render(?array $items): string
     {
         // Create a new environment for this template
         $env = new Environment();
@@ -43,11 +43,13 @@ public function render(array $items): string
         $env->set('false', false);
         $env->set('true', true);
         $env->set('raise_exception', fn($args) => throw new RuntimeException($args));
-        $env->set('range', fn($args) => range($args[0], $args[1]));
+        $env->set('range', range(...));
 
         // Add user-defined variables
-        foreach ($items as $key => $value) {
-            $env->set($key, $value);
+        if ($items) {
+            foreach ($items as $key => $value) {
+                $env->set($key, $value);
+            }
         }
 
         $interpreter = new Interpreter($env);