Major refactor — recursive descent parser, arithmetic, unary operators, and token system overhaul

.gitignore

@@ -1,7 +1,8 @@
 /tests/log
 /composer.lock
 /coverage.clover
-/.phpunit.result.cache
+/.phpunit.*
 /vendor/
 /.idea
 /.composer
+.DS_Store

.styleci.yml

@@ -1,5 +1,5 @@
 ---
-preset: psr2
+preset: psr12
 risky: true
 version: 8.4
 finder:

README.md

@@ -6,9 +6,9 @@
 [![Code Quality][Master quality image]][Master quality] 
 [![StyleCI](https://styleci.io/repos/39503126/shield?branch=master&style=flat)](https://styleci.io/repos/39503126)
 
-You're looking at a standalone PHP library to parse and evaluate text based rules with a Javascript-like syntax. This project was born out of the necessity to evaluate hundreds of rules that were originally written and evaluated in JavaScript, and now needed to be evaluated on the server-side, using PHP.
+A standalone PHP library to parse and evaluate text-based rules using a JavaScript-like syntax. This project was born out of the need to evaluate hundreds of rules originally written in JavaScript on the server side, using PHP.
 
-This library has initially been used to change and configure the behavior of certain "Workflows" (without changing actual code) in an intranet application, but it may serve a purpose elsewhere.
+The library was initially used to configure the behavior of "Workflows" in an intranet application without changing actual code, but it may serve a purpose elsewhere.
 
 ## Install
 
@@ -44,7 +44,7 @@ $variables = [
     'coupon_code' => (string) $_POST['coupon_code'],
 ];
 
-$rule = new Rule('coupon_code.test(/^summer20[0-9]{2}$/) == true', $variables);
+$rule = new Rule('coupon_code.test(/^summer20[0-9]{2}$/)', $variables);
 var_dump($rule->isTrue()); // bool(true)
 ```
 
@@ -56,6 +56,60 @@ $rule = new Rule('points >= 50 && points <= 100', $variables);
 var_dump($rule->isTrue()); // bool(true)
 ```
 
+Perform arithmetic operations
+```php
+$variables = ['price' => 100, 'quantity' => 3];
+
+$rule = new Rule('price * quantity > 250', $variables);
+var_dump($rule->isTrue()); // bool(true)
+```
+
+Arithmetic operators follow standard precedence rules: `*`, `/`, `%` bind tighter than `+`, `-`. Parentheses can be used to override precedence.
+```php
+$rule = new Rule('2 + 3 * 4 == 14');
+var_dump($rule->isTrue()); // bool(true) - multiplication before addition
+
+$rule = new Rule('(2 + 3) * 4 == 20');
+var_dump($rule->isTrue()); // bool(true) - parentheses override precedence
+```
+
+Unary minus and logical NOT operators are also supported:
+```php
+$rule = new Rule('-5 * 3 == -15');
+var_dump($rule->isTrue()); // bool(true) - unary minus binds tighter than multiplication
+
+$rule = new Rule('--5 == 5');
+var_dump($rule->isTrue()); // bool(true) - double negation
+
+$rule = new Rule('!false');
+var_dump($rule->isTrue()); // bool(true) - logical NOT
+
+$rule = new Rule('!(1 == 2)');
+var_dump($rule->isTrue()); // bool(true) - NOT with parenthesized comparison
+
+$rule = new Rule('!foo', ['foo' => false]);
+var_dump($rule->isTrue()); // bool(true) - NOT with variable
+```
+
+Get the actual computed result of an expression (not just true/false)
+```php
+$rule = new Rule('5 * 3');
+var_dump($rule->result()); // int(15)
+
+$rule = new Rule('"hello " + "world"');
+var_dump($rule->result()); // string("hello world")
+
+$rule = new Rule('parseInt("42")');
+var_dump($rule->result()); // int(42)
+
+$rule = new Rule('price * quantity', ['price' => 100, 'quantity' => 3]);
+var_dump($rule->result()); // int(300)
+
+// Comparison and logical expressions still return bool
+$rule = new Rule('foo > 5', ['foo' => 10]);
+var_dump($rule->result()); // bool(true)
+```
+
 Call methods on objects from within rules
 ```php
 class User
@@ -73,54 +127,62 @@ $variables = [
 $rule = new Rule('user.points() > 300', $variables);
 var_dump($rule->isTrue()); // bool(true)
 ```
+
 For security reasons, PHP's magic methods like `__construct` and `__destruct` cannot be 
 called from within rules. However, `__call` will be invoked automatically if available,
-unless the called method is defined. 
+unless the called method is defined.
 
 ## Built-in Methods
 
-Name        | Example             
------------ | ------------------------
-charAt      | `"foo".charAt(2) === "o"`            
-concat      | `"foo".concat("bar", "baz") === "foobarbaz"`
-endsWith    | `"foo".endsWith("oo") === true`               
-startsWith  | `"foo".startsWith("fo") === true`        
-indexOf     | `"foo".indexOf("oo") === 1`                
-join        | `["foo", "bar"].join(",") === "foo,bar"`            
-replace     | `"foo".replace("oo", "aa") === "faa"`               
-split       | `"foo-bar".split("-") === ["foo", "bar"]`           
-substr      | `"foo".substr(1) === "oo"`                 
-test        | `"foo".test(/oo$/) === true`                     
-toLowerCase | `"FOO".toLowerCase() === "foo"`                      
-toUpperCase | `"foo".toUpperCase() === "FOO"`                      
+| Name        | Example             |
+| ----------- | ------------------------ |
+| charAt      | `"foo".charAt(2) === "o"`            |
+| concat      | `"foo".concat("bar", "baz") === "foobarbaz"` |
+| endsWith    | `"foo".endsWith("oo")`               |
+| startsWith  | `"foo".startsWith("fo")`        |
+| indexOf     | `"foo".indexOf("oo") === 1`                |
+| join        | `["foo", "bar"].join(",") === "foo,bar"`            |
+| replace     | `"foo".replace("oo", "aa") === "faa"`               |
+| split       | `"foo-bar".split("-") === ["foo", "bar"]`           |
+| substr      | `"foo".substr(1) === "oo"`                 |
+| test        | `"foo".test(/oo$/)`                     |
+| toLowerCase | `"FOO".toLowerCase() === "foo"`                      |
+| toUpperCase | `"foo".toUpperCase() === "FOO"`                      |
 
 ## Built-in Functions
 
-Name        | Example             
------------ | ------------------------
-parseInt    | `parseInt("22aa") === 22`            
-parseFloat  | `parseFloat("3.1") === 3.1`
+| Name        | Example             |
+| ----------- | ------------------------ |
+| parseInt    | `parseInt("22aa") === 22`            |
+| parseFloat  | `parseFloat("3.1") === 3.1` |
 
 ## Supported Operators
 
-Type        | Description              | Operator
------------ | ------------------------ | ----------
-Comparison  | greater than             | >
-Comparison  | greater than or equal to | >=
-Comparison  | less than                | <
-Comparison  | less or equal to         | <=
-Comparison  | equal to                 | ==
-Comparison  | not equal to             | !=
-Comparison  | identical                | ===
-Comparison  | not identical            | !==
-Containment | contains                 | in 
-Containment | does not contain         | not in 
-Logical     | and                      | &&
-Logical     | or                       | \|\|
+| Type        | Description              | Operator |
+| ----------- | ------------------------ | ---------- |
+| Comparison  | greater than             | > |
+| Comparison  | greater than or equal to | >= |
+| Comparison  | less than                | < |
+| Comparison  | less or equal to         | <= |
+| Comparison  | equal to                 | == |
+| Comparison  | not equal to             | != |
+| Comparison  | identical                | === |
+| Comparison  | not identical            | !== |
+| Containment | contains                 | in |
+| Containment | does not contain         | not in |
+| Logical     | and                      | && |
+| Logical     | or                       | \|\| |
+| Arithmetic  | addition                 | + |
+| Arithmetic  | subtraction              | - |
+| Arithmetic  | multiplication           | * |
+| Arithmetic  | division                 | / |
+| Arithmetic  | modulo                   | % |
+| Unary       | negation                 | - |
+| Unary       | logical NOT              | ! |
 
 ## Error Handling
 
-Both, `$rule->isTrue()` and `$rule->isFalse()` will throw an exception if the syntax is invalid. These calls can either be placed inside a `try` / `catch` block, or it can be checked prior using `$rule->isValid()`.
+Both `$rule->isTrue()` and `$rule->isFalse()` will throw an exception if the syntax is invalid. These calls can either be placed inside a `try` / `catch` block, or validity can be checked beforehand using `$rule->isValid()`.
 
 ```php
 $ruleStr = '
@@ -143,18 +205,19 @@ Or alternatively:
 
 ```php
 if (!$rule->isValid()) {
-    echo $rule->getError();
+    echo $rule->error;
 }
 ```
 
-Both will output: `Unexpected token "(" at position 25 on line 3`
+Both will output: `Unexpected "(" at position 28`
 
 ## Syntax Highlighting
- 
+
 A custom syntax highlighter is also provided.
 
 ```php
-use nicoSWD\Rule;
+use nicoSWD\Rule\Highlighter\Highlighter;
+use nicoSWD\Rule\TokenStream\Token\TokenType;
 
 $ruleStr = '
     // This is true
@@ -170,7 +233,7 @@ $ruleStr = '
         bar > 6
     )';
 
-$highlighter = new Rule\Highlighter\Highlighter(new Rule\Tokenizer());
+$highlighter = new Highlighter();
 
 // Optional custom styles
 $highlighter->setStyle(
@@ -185,11 +248,6 @@ Outputs:
 
 ![Syntax preview](https://s3.amazonaws.com/f.cl.ly/items/0y1b0s0J2v2v1u3O1F3M/Screen%20Shot%202015-08-05%20at%2012.15.21.png)
 
-## Notes
-
-- Parentheses can be nested, and will be evaluated from right to left.
-- Only value/variable comparison expressions with optional logical ANDs/ORs, are supported.
-
 ## Security
 
 If you discover any security related issues, please email security@nic0.me instead of using the issue tracker.
@@ -202,26 +260,24 @@ $ composer test
 
 ## Contributing
 
-Pull requests are very welcome! If they include tests, even better. This project follows PSR-2 coding standards, please make sure your pull requests do too.
+Pull requests are very welcome! If they include tests, even better. This project follows [PSR-12](https://www.php-fig.org/psr/psr-12/) coding standards, please make sure your pull requests do too.
 
 ## To Do
 
 - Support for object properties (foo.length)
-- Support for returning actual results, other than true or false
 - Support for array / string dereferencing: "foo"[1]
-- Don't force boolean comparison for tokens that are already booleans. `my_func() && 2 > 1` should work
-- Change regex and implementation for method calls. ".split(" should not be the token
-- Add / implement missing methods
-- Add "typeof" construct
-- Do math (?)
-- Allow string concatenating with "+"
-- Invalid regex modifiers should not result in an unknown token
-- Duplicate regex modifiers should throw an error
+- ~~Support for returning actual results, other than true or false~~
+- ~~Don't force boolean comparison for tokens that are already booleans. `my_func() && 2 > 1` should work~~
+- ~~Allow string concatenating with "+"~~
+- ~~Duplicate regex modifiers should throw an error~~
 - ~~Add support for function calls~~
 - ~~Support for regular expressions~~
 - ~~Fix build on PHP 7 / Nightly~~
 - ~~Allow variables in arrays~~
 - ~~Verify function and method name spelling (.tOuPpErCAse() is currently valid)~~
+- ~~Change regex and implementation for method calls~~
+- ~~Add / implement missing methods~~
+- ~~Invalid regex modifiers should not result in an unknown token~~
 - ...
 
 ## License

composer.json

@@ -33,11 +33,13 @@
     }
   },
   "require": {
-    "php": ">=8.4"
+    "php": ">=8.5",
+    "ext-ctype": "*"
   },
   "require-dev": {
-    "phpunit/phpunit": "^12.3",
-    "mockery/mockery": "^1.6"
+    "phpunit/phpunit": "^13.1",
+    "mockery/mockery": "^1.6",
+    "squizlabs/php_codesniffer": "^4.0"
   },
   "scripts": {
     "test": "vendor/bin/phpunit"

phpunit.xml.dist.bak

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
+         bootstrap="src/autoload.php">
+  <coverage processUncoveredFiles="true">
+    <include>
+      <directory suffix=".php">src</directory>
+    </include>
+  </coverage>
+  <testsuites>
+    <testsuite name="Unit tests">
+      <directory>tests/</directory>
+    </testsuite>
+  </testsuites>
+</phpunit>

src/AST/AdditionNode.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * @license     http://opensource.org/licenses/mit-license.php MIT
+ * @link        https://github.com/nicoSWD
+ * @author      Nicolas Oelgart <hello@nico.es>
+ */
+
+declare(strict_types=1);
+
+namespace nicoSWD\Rule\AST;
+
+final class AdditionNode extends Node
+{
+    public function __construct(
+        public readonly Node $left,
+        public readonly Node $right,
+    ) {
+    }
+
+    public function evaluate(EvaluationContext $context): mixed
+    {
+        $left = $this->left->evaluate($context);
+        $right = $this->right->evaluate($context);
+
+        if (is_string($left) || is_string($right)) {
+            return (string) $left . (string) $right;
+        }
+
+        return $left + $right;
+    }
+}

src/AST/ArrayNode.php

@@ -0,0 +1,34 @@
+<?php
+
+/**
+ * @license     http://opensource.org/licenses/mit-license.php MIT
+ * @link        https://github.com/nicoSWD
+ * @author      Nicolas Oelgart <hello@nico.es>
+ */
+
+declare(strict_types=1);
+
+namespace nicoSWD\Rule\AST;
+
+final class ArrayNode extends Node
+{
+    /** @param Node[] $items */
+    public function __construct(
+        public readonly array $items,
+    ) {
+    }
+
+    /**
+     * @throws \RuntimeException
+     */
+    public function evaluate(EvaluationContext $context): array
+    {
+        $items = [];
+
+        foreach ($this->items as $item) {
+            $items[] = $item->evaluate($context);
+        }
+
+        return $items;
+    }
+}