Match cases scalar function (#1720)

* Match cases scalar function

* Renamed DSL functions accordingly to community preferences

Author: norberttech

src/core/etl/src/Flow/ETL/DSL/functions.php

@@ -80,7 +80,8 @@
 use Flow\ETL\Extractor\SequenceGenerator\{DatePeriodSequenceGenerator, NumberSequenceGenerator};
 use Flow\ETL\Filesystem\{SaveMode};
 use Flow\ETL\Formatter\AsciiTableFormatter;
-use Flow\ETL\Function\{All,
+use Flow\ETL\Function\{
+    All,
     Any,
     ArrayGet,
     ArrayGetCollection,
@@ -114,6 +115,7 @@
     Least,
     ListFunctions,
     Literal,
+    MatchCases,
     Max,
     Min,
     Not,
@@ -145,10 +147,12 @@
     ToUpper,
     Ulid,
     Uuid,
-    When};
+    When
+};
 use Flow\ETL\Function\ArrayExpand\ArrayExpand;
 use Flow\ETL\Function\ArraySort\Sort;
 use Flow\ETL\Function\Between\Boundary;
+use Flow\ETL\Function\MatchCases\MatchCase;
 use Flow\ETL\Loader\{ArrayLoader, CallbackLoader, MemoryLoader, StreamLoader, TransformerLoader};
 use Flow\ETL\Loader\BranchingLoader;
 use Flow\ETL\Loader\StreamLoader\Output;
@@ -2031,3 +2035,15 @@ function analyze() : Analyze
 {
     return new Analyze();
 }
+
+#[DocumentationDSL(module: Module::CORE, type: DSLType::SCALAR_FUNCTION)]
+function match_cases(array $cases, mixed $default = null) : MatchCases
+{
+    return new MatchCases($cases, $default);
+}
+
+#[DocumentationDSL(module: Module::CORE, type: DSLType::SCALAR_FUNCTION)]
+function match_condition(mixed $condition, mixed $then) : MatchCase
+{
+    return new MatchCase($condition, $then);
+}

src/core/etl/src/Flow/ETL/Function/MatchCases.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\ETL\Function;
+
+use Flow\ETL\Exception\RuntimeException;
+use Flow\ETL\Function\MatchCases\MatchCase;
+use Flow\ETL\Row;
+
+final class MatchCases extends ScalarFunctionChain
+{
+    /**
+     * @param array<MatchCase> $cases
+     * @param MatchCase $default
+     */
+    public function __construct(private readonly array $cases, private readonly mixed $default = null)
+    {
+
+    }
+
+    public function eval(Row $row) : mixed
+    {
+        foreach ($this->cases as $condition) {
+            if ($condition->valid($row)) {
+                return $condition->eval($row);
+            }
+        }
+
+        if ($this->default) {
+            return $this->default->eval($row);
+        }
+
+        throw new RuntimeException(
+            'Not a single case matches row, consider using default parameter, row: '
+            . \json_encode($row->toArray(), JSON_THROW_ON_ERROR)
+        );
+    }
+}

src/core/etl/src/Flow/ETL/Function/MatchCases/MatchCase.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\ETL\Function\MatchCases;
+
+use Flow\ETL\Function\{Parameter, ScalarFunction};
+use Flow\ETL\Row;
+
+final readonly class MatchCase implements ScalarFunction
+{
+    public function __construct(
+        private mixed $condition,
+        private mixed $then,
+    ) {
+    }
+
+    public function eval(Row $row) : mixed
+    {
+        return (new Parameter($this->then))->eval($row);
+    }
+
+    public function valid(Row $row) : bool
+    {
+        return (new Parameter($this->condition))->asBoolean($row);
+    }
+}

src/core/etl/tests/Flow/ETL/Tests/Integration/Function/MatchCasesTest.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\ETL\Tests\Integration\Function;
+
+use function Flow\ETL\DSL\{df, from_rows, lit, match_cases, match_condition, ref, row, rows, string_entry};
+use function Flow\Types\DSL\type_integer;
+use Flow\ETL\Tests\FlowTestCase;
+
+final class MatchCasesTest extends FlowTestCase
+{
+    public function test_case_match() : void
+    {
+        $rows = rows(
+            row(string_entry('string', 'string-with-dashes')),
+            row(string_entry('string', '123')),
+            row(string_entry('string', '14%')),
+            row(string_entry('string', '+14')),
+            row(string_entry('string', ''))
+        );
+
+        $output = df()
+            ->read(from_rows($rows))
+            ->withEntry(
+                'string',
+                match_cases(
+                    [
+                        match_condition(ref('string')->contains('-'), ref('string')->strReplace('-', ' ')),
+                        match_condition(ref('string')->call('is_numeric'), ref('string')->cast(type_integer())),
+                        match_condition(ref('string')->endsWith('%'), ref('string')->strReplace('%', '')->cast(type_integer())),
+                        match_condition(ref('string')->startsWith('+'), ref('string')->strReplace('+', '')->cast(type_integer())),
+                    ],
+                    default: lit('DEFAULT')
+                )
+            )
+            ->fetch()
+            ->toArray();
+
+        self::assertSame(
+            [
+                ['string' => 'string with dashes'],
+                ['string' => 123],
+                ['string' => 14],
+                ['string' => 14],
+                ['string' => 'DEFAULT'],
+            ],
+            $output
+        );
+    }
+}

src/core/etl/tests/Flow/ETL/Tests/Unit/Function/MatchCasesTest.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\ETL\Tests\Unit\Function;
+
+use function Flow\ETL\DSL\{lit, match_cases, match_condition, ref, row, str_entry};
+use Flow\ETL\Tests\FlowTestCase;
+
+final class MatchCasesTest extends FlowTestCase
+{
+    public function test_case_match() : void
+    {
+        $match = match_cases([
+            match_condition(ref('string')->contains('_'), ref('string')->strReplace('_', ' ')),
+            match_condition(ref('string')->contains('-'), ref('string')->strReplace('-', ' ')),
+        ]);
+
+        self::assertSame(
+            'this is slug',
+            $match->eval(row(str_entry('string', 'this-is-slug')))
+        );
+        self::assertSame(
+            'this is slug',
+            $match->eval(row(str_entry('string', 'this_is_slug')))
+        );
+    }
+
+    public function test_not_matching_anything() : void
+    {
+        $match = match_cases([
+            match_condition(ref('string')->contains('_'), ref('string')->strReplace('_', ' ')),
+            match_condition(ref('string')->contains('-'), ref('string')->strReplace('-', ' ')),
+        ]);
+
+        $this->expectExceptionMessage('Not a single case matches row, consider using default parameter, row: {"string":"weirdstring"}');
+
+        $match->eval(row(str_entry('string', 'weirdstring')));
+    }
+
+    public function test_not_matching_anything_with_default() : void
+    {
+        $match = match_cases(
+            [
+                match_condition(ref('string')->contains('_'), ref('string')->strReplace('_', ' ')),
+                match_condition(ref('string')->contains('-'), ref('string')->strReplace('-', ' ')),
+            ],
+            default: lit('normal string')
+        );
+
+        self::assertEquals(
+            'normal string',
+            $match->eval(row(str_entry('string', 'weirdstring')))
+        );
+    }
+}