Added Regex strategy.

Author: Bilge

.gitignore

@@ -2,3 +2,4 @@
 !/.github/
 /vendor/
 /composer.lock
+*.cache

README.md

@@ -37,6 +37,7 @@ Contents
           1. [IfExists](#ifexists)
           1. [Join](#join)
           1. [Merge](#merge)
+          1. [Regex](#regex)
           1. [Replace](#replace)
           1. [TakeFirst](#takefirst)
           1. [ToList](#tolist)
@@ -227,16 +228,8 @@ class BarBucketAddressToAddresesMapping extends Mapping
     {
         return [
             'line1' => new Copy('Addresses->0->1'),
-            'city' => new Callback(
-                function (array $data) {
-                    return $this->extractCity($data['Addresses'][0][2]);
-                }
-            ),
-            'postcode' => new Callback(
-                function (array $data) {
-                    return $this->extractZipCode($data['Addresses'][0][2]);
-                }
-            ),
+            'city' => new Callback(fn (array $data) => $this->extractCity($data['Addresses'][0][2])),
+            'postcode' => new Regex(new Copy('Addresses->0->2'), '[.*\b(\d{5})]', 1),
             'country' => 'US',
         ];
     }
@@ -245,19 +238,12 @@ class BarBucketAddressToAddresesMapping extends Mapping
     {
         return explode(',', $line, 2)[0];
     }
-
-    private function extractZipCode($line)
-    {
-        if (preg_match('[.*\b(\d{5})]', $line, $matches)) {
-            return $matches[1];
-        }
-    }
 }
 ```
 
 *Line1* can be copied straight from the input data and *country* can be hard-coded with a constant value because we assume it does not change.
 
-City and postcode must be extracted from the last line of the address. For this we use `Callback` strategies that indirectly point to private methods of our mapping. Callbacks are only necessary because there are currently no included strategies to perform string splitting or regular expression matching.
+City and postcode must be extracted from the last line of the address. For _city_, we use the `Callback` strategy that points to a private method of our mapping. A callback is necessary because there are currently no included strategies to perform string splitting. For _postcode_, we can use the [`Regex`](#regex) strategy.
 
 The anonymous function wrapper picks the relevant part of the input data to pass to our methods. The weakness of this solution is dereferencing non-existent values will cause PHP to generate *undefined index* notices whereas injecting `Copy` strategies would gracefully resolve to `null` if any part of the path does not exist. Therefore, the most elegant solution would be to create custom strategies to promote code reuse and avoid errors, but is beyond the scope of this demonstration. For more information see [writing strategies](#writing-strategies).
 
@@ -302,6 +288,7 @@ The following strategies ship with Mapper and provide a suite of commonly used f
  - [IfExists](#ifexists) – Delegates to one expression or another depending on whether the specified condition maps to null.
  - [Join](#join) – Joins sub-string expressions together with a glue string.
  - [Merge](#merge) – Merges two data sets together giving precedence to the latter if keys collide.
+ - [Regex](#regex) – Captures a portion of a string using regular expression matching.
  - [Replace](#replace) – Replaces one or more substrings.
  - [TakeFirst](#takefirst) – Takes the first value from a collection one or more times.
  - [ToList](#tolist) – Converts data to a single-element list unless it is already a list.
@@ -740,6 +727,35 @@ Merge(Strategy|Mapping|array|mixed $first, Strategy|Mapping|array|mixed $second)
 
 > [1, 2, 3, 3, 4, 5]
 
+### Regex
+
+Captures a portion of a string using regular expression matching.
+
+#### Signature
+
+```php
+Regex(Strategy|Mapping|array|mixed $expression, string $regex, int $capturingGroup = 0)
+```
+
+1. `$expression` – Expression to search in.
+2. `$regex` – Regular expression, including delimiters.
+3. `$capturingGroup` – Optional. Capturing group index to return. Defaults to whole matched expression.
+
+#### Example
+
+```php
+(new Mapper)->map(
+    ['foo bar baz'],
+    new Replace(
+        new Copy(0),
+        '[\h(.+)\h]',
+        1,
+    )
+)
+```
+
+> 'bar'
+
 ### Replace
 
 Replaces all occurrences of one or more substrings.

src/Strategy/Join.php

@@ -1,6 +1,8 @@
 <?php
 namespace ScriptFUSION\Mapper\Strategy;
 
+use ScriptFUSION\Mapper\Mapping;
+
 /**
  * Joins sub-string expressions together with a glue string.
  */
@@ -12,7 +14,8 @@ class Join extends Delegate
      * Initializes this instance with the specified glue to join the specified expressions together.
      *
      * @param string $glue Glue.
-     * @param array ...$expressions Expressions to join or a single expression that resolves to an array to join.
+     * @param Strategy|Mapping|string[]|string ...$expressions Expressions to join or a single expression that resolves
+     *     to an array to join.
      */
     public function __construct($glue, ...$expressions)
     {

src/Strategy/Regex.php

@@ -0,0 +1,22 @@
+<?php
+declare(strict_types=1);
+
+namespace ScriptFUSION\Mapper\Strategy;
+
+/**
+ * Captures a portion of a string using regular expression matching.
+ */
+final class Regex extends Delegate
+{
+    public function __construct($expression, private readonly string $regex, private readonly int $capturingGroup = 0)
+    {
+        parent::__construct($expression);
+    }
+
+    public function __invoke($data, $context = null)
+    {
+        if (preg_match($this->regex, parent::__invoke($data, $context), $matches)) {
+            return $matches[$this->capturingGroup];
+        }
+    }
+}

test/Fixture/BarBucketAddressToAddresesMapping.php

@@ -4,23 +4,16 @@
 use ScriptFUSION\Mapper\Mapping;
 use ScriptFUSION\Mapper\Strategy\Callback;
 use ScriptFUSION\Mapper\Strategy\Copy;
+use ScriptFUSION\Mapper\Strategy\Regex;
 
 class BarBucketAddressToAddresesMapping extends Mapping
 {
     protected function createMapping()
     {
         return [
             'line1' => new Copy('Addresses->0->1'),
-            'city' => new Callback(
-                function (array $data) {
-                    return $this->extractCity($data['Addresses'][0][2]);
-                }
-            ),
-            'postcode' => new Callback(
-                function (array $data) {
-                    return $this->extractZipCode($data['Addresses'][0][2]);
-                }
-            ),
+            'city' => new Callback(fn (array $data) => $this->extractCity($data['Addresses'][0][2])),
+            'postcode' => new Regex(new Copy('Addresses->0->2'), '[.*\b(\d{5})]', 1),
             'country' => 'US',
         ];
     }
@@ -29,11 +22,4 @@ private function extractCity($line)
     {
         return explode(',', $line, 2)[0];
     }
-
-    private function extractZipCode($line)
-    {
-        if (preg_match('[.*\b(\d{5})]', $line, $matches)) {
-            return $matches[1];
-        }
-    }
 }

test/Functional/DocumentationTest.php

@@ -18,6 +18,7 @@
 use ScriptFUSION\Mapper\Strategy\IfExists;
 use ScriptFUSION\Mapper\Strategy\Join;
 use ScriptFUSION\Mapper\Strategy\Merge;
+use ScriptFUSION\Mapper\Strategy\Regex;
 use ScriptFUSION\Mapper\Strategy\Replace;
 use ScriptFUSION\Mapper\Strategy\TakeFirst;
 use ScriptFUSION\Mapper\Strategy\ToList;
@@ -306,6 +307,21 @@ public function testMerge()
         );
     }
 
+    public function testRegex(): void
+    {
+        self::assertSame(
+            'bar',
+            (new Mapper)->map(
+                ['foo bar baz'],
+                new Regex(
+                    new Copy(0),
+                    '[\h(.+)\h]',
+                    1,
+                )
+            )
+        );
+    }
+
     public function testReplace()
     {
         self::assertSame(

test/MockFactory.php

@@ -3,30 +3,19 @@
 
 use Mockery\MockInterface;
 use ScriptFUSION\Mapper\Mapper;
-use ScriptFUSION\Mapper\Strategy\Strategy;
 use ScriptFUSION\StaticClass;
 
 final class MockFactory
 {
     use StaticClass;
 
-    /**
-     * @param mixed $data
-     *
-     * @return Strategy|MockInterface
-     */
-    public static function mockStrategy($data)
+    public static function mockMapper(mixed $data): Mapper&MockInterface
     {
-        return \Mockery::mock(Strategy::class)->shouldReceive('__invoke')->andReturn($data)->getMock();
+        return \Mockery::mock(Mapper::class)->shouldReceive('map')->andReturn($data)->getMock();
     }
 
-    /**
-     * @param mixed $data
-     *
-     * @return Mapper|MockInterface
-     */
-    public static function mockMapper($data)
+    public static function mockMapperEcho(): Mapper&MockInterface
     {
-        return \Mockery::mock(Mapper::class)->shouldReceive('map')->andReturn($data)->getMock();
+        return \Mockery::mock(Mapper::class)->expects('map')->andReturnArg(1)->getMock();
     }
 }

test/Unit/Mapper/Strategy/RegexTest.php

@@ -0,0 +1,25 @@
+<?php
+declare(strict_types=1);
+
+namespace ScriptFUSIONTest\Unit\Mapper\Strategy;
+
+use PHPUnit\Framework\TestCase;
+use ScriptFUSION\Mapper\Strategy\Regex;
+use ScriptFUSIONTest\MockFactory;
+
+final class RegexTest extends TestCase
+{
+    public function testRegexMatch(): void
+    {
+        $regex = (new Regex('Alfa Beta Charlie', '[\h(.+)\h]', 1))->setMapper(MockFactory::mockMapperEcho());
+
+        self::assertSame('Beta', $regex([]));
+    }
+
+    public function testRegexNonMatch(): void
+    {
+        $regex = (new Regex('Alfa', '[Beta]'))->setMapper(MockFactory::mockMapperEcho());
+
+        self::assertNull($regex([]));
+    }
+}