Added Replace strategy and accompanying tests and updated readme.

Author: Paul

README.md

@@ -37,6 +37,7 @@ Contents
           1. [IfExists](#ifexists)
           1. [Join](#join)
           1. [Merge](#merge)
+          1. [Replace](#replace)
           1. [TakeFirst](#takefirst)
           1. [ToList](#tolist)
           1. [TryCatch](#trycatch)
@@ -301,6 +302,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.
+ - [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.
  - [TryCatch](#trycatch) – Tries the primary strategy and falls back to an expression if an exception is thrown.
@@ -313,9 +315,9 @@ The following strategies ship with Mapper and provide a suite of commonly used f
 
 ### Copy
 
-Copies a portion of input data, or specified data, according to a lookup path. Supports traversing nested arrays.
+Copies a portion of input data, or specified data, according to a lookup path. Supports traversing nested arrays. By default the current record is used as the data source but if the *data* parameter is specified it is used instead.
 
-`Copy` is probably the most common strategy whether used by itself or injected into other strategies. Since both its *path* and *data* parameters can be mapped expressions it is highly versatile and can be combined with other strategies, or even itself, to produce powerful expressions.
+`Copy` is probably the most common strategy whether used by itself or injected into other strategies. Since both its *path* and *data* parameters can be mapped expressions it is highly versatile and can be combined with other strategies, or even itself, to produce powerful transformations.
 
 #### Signature
 
@@ -348,7 +350,7 @@ $data = [
 
 > 123
 
-#### Specified data example
+#### Data override example
 
 When data is specified in the second parameter it is used instead of the data sent from `Mapper`.
 
@@ -361,7 +363,7 @@ When data is specified in the second parameter it is used instead of the data se
 
 > 'baz'
 
-#### Path resolver example
+#### Recursive path resolver example
 
 Since the path can be derived from other strategies we can nest `Copy` instances to look up values referenced by other keys.
 
@@ -729,6 +731,39 @@ Merge(Strategy|Mapping|array|mixed $first, Strategy|Mapping|array|mixed $second)
 
 > [1, 2, 3, 3, 4, 5]
 
+### Replace
+
+Replaces all occurrences one or more substrings.
+
+Any number of searches and replacements can be specified. Searches and replacements are parsed in pairs. If no replacements are specified, all matches are removed instead of replaced. If fewer replacements than searches are specified, the last replacement will be used for the remaining searches. If more replacements than searches are specified, the extra replacements are ignored.
+
+Searches can be specified as either string literals or wrapped in an `Expression` and treated as a regular expression. `Expression` and string searches can be mixed as desired. Regular expression replacements can reference sub-matches, e.g. `$1`.
+
+#### Signature
+
+```php
+Replace(Strategy|Mapping|array|mixed $expression, string|Expression|array $searches, string|string[]|null $replacements)
+```
+
+ 1. `$expression` – Expression to search in.
+ 2. `$searches` – Search string(s).
+ 3. `$replacements` – Optional. Replacement string(s).
+
+#### Example
+
+```php
+(new Mapper)->map(
+    ['Hello World'],
+    new Replace(
+        new Copy(0),
+        ['Hello', new Expression('[\h*world$]i')],
+        ['こんにちは', '世界']
+    )
+)
+```
+
+> 'こんにちは世界'
+
 ### TakeFirst
 
 Takes the first value from a collection one or more times according to the specified depth. If the depth exceeds the number of nesting levels of the collection the last item encountered will be returned.

src/Expression.php

@@ -0,0 +1,20 @@
+<?php
+namespace ScriptFUSION\Mapper;
+
+/**
+ * Represents an expression value.
+ */
+final class Expression
+{
+    private $expression;
+
+    public function __construct($expression)
+    {
+        $this->expression = "$expression";
+    }
+
+    public function __toString()
+    {
+        return $this->expression;
+    }
+}

src/Strategy/Replace.php

@@ -0,0 +1,54 @@
+<?php
+namespace ScriptFUSION\Mapper\Strategy;
+
+use ScriptFUSION\Mapper\Expression;
+use ScriptFUSION\Mapper\Mapping;
+
+/**
+ * Replaces one or more substrings.
+ */
+class Replace extends Delegate
+{
+    private $searches;
+
+    private $replacements;
+
+    /**
+     * Initializes this instance with the specified expression to search in, search strings and replacement strings.
+     *
+     * Any number of searches and replacements can be specified. Searches and replacements are parsed in pairs. If no
+     * replacements are specified, all matches are removed instead of replaced. If fewer replacements than searches are
+     * specified, the last replacement will be used for the remaining searches. If more replacements than searches are
+     * specified, the extra replacements are ignored.
+     *
+     * @param Strategy|Mapping|array|mixed $expression Expression to search in.
+     * @param $searches string|Expression|array Search string(s).
+     * @param $replacements string|string[]|null Optional. Replacement string(s).
+     */
+    public function __construct($expression, $searches, $replacements = null)
+    {
+        parent::__construct($expression);
+
+        $this->searches = is_object($searches) ? [$searches] : (array)$searches;
+        $this->replacements = (array)$replacements;
+    }
+
+    public function __invoke($data, $context = null)
+    {
+        $output = parent::__invoke($data, $context);
+        $replacements = $this->replacements;
+        $replace = null;
+
+        foreach ($this->searches as $search) {
+            $replace = count($replacements) ? array_shift($replacements) : $replace;
+
+            if ($search instanceof Expression) {
+                $output = preg_replace($search, $replace, $output);
+            } else {
+                $output = str_replace($search, $replace, $output);
+            }
+        }
+
+        return $output;
+    }
+}

test/Functional/DocumentationTest.php

@@ -2,6 +2,7 @@
 namespace ScriptFUSIONTest\Functional;
 
 use ScriptFUSION\Mapper\DataType;
+use ScriptFUSION\Mapper\Expression;
 use ScriptFUSION\Mapper\Mapper;
 use ScriptFUSION\Mapper\Strategy\Callback;
 use ScriptFUSION\Mapper\Strategy\Collection;
@@ -16,6 +17,7 @@
 use ScriptFUSION\Mapper\Strategy\IfExists;
 use ScriptFUSION\Mapper\Strategy\Join;
 use ScriptFUSION\Mapper\Strategy\Merge;
+use ScriptFUSION\Mapper\Strategy\Replace;
 use ScriptFUSION\Mapper\Strategy\TakeFirst;
 use ScriptFUSION\Mapper\Strategy\ToList;
 use ScriptFUSION\Mapper\Strategy\TryCatch;
@@ -295,6 +297,21 @@ public function testMerge()
         );
     }
 
+    public function testReplace()
+    {
+        self::assertSame(
+            'こんにちは世界',
+            (new Mapper)->map(
+                ['Hello World'],
+                new Replace(
+                    new Copy(0),
+                    ['Hello', new Expression('[\h*world$]i')],
+                    ['こんにちは', '世界']
+                )
+            )
+        );
+    }
+
     public function testTakeFirst()
     {
         self::assertSame(

test/Unit/Mapper/Strategy/ReplaceTest.php

@@ -0,0 +1,58 @@
+<?php
+namespace ScriptFUSIONTest\Unit\Mapper\Strategy;
+
+use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
+use ScriptFUSION\Mapper\Expression;
+use ScriptFUSION\Mapper\Strategy\Replace;
+use ScriptFUSIONTest\MockFactory;
+
+final class ReplaceTest extends \PHPUnit_Framework_TestCase
+{
+    use MockeryPHPUnitIntegration;
+
+    /**
+     * @dataProvider provideReplacements
+     */
+    public function testReplace($input, $search, $replace, $output)
+    {
+        $replace = (new Replace($input, $search, $replace))->setMapper(MockFactory::mockMapper($input));
+
+        self::assertSame($output, $replace([]));
+    }
+
+    public function provideReplacements()
+    {
+        return [
+            'Single removal' => ['foo', 'o', null, 'f'],
+            'Substring removal' => ['foo', 'oo', null, 'f'],
+
+            'Single replacement' => ['foo', 'f', 'b', 'boo'],
+            'Substring replacement' => ['foo', 'foo', 'bar', 'bar'],
+
+            'Multiple removal' => ['foo', ['f', 'o'], null, ''],
+            'Multiple replacement' => ['foo', ['f', 'o'], ['h', 'a'], 'haa'],
+
+            'Insufficient replacements (uniform types)' => ['foo', ['f', 'o'], ['x'], 'xxx'],
+            'Insufficient replacements (mixed types)' => ['foo', ['f', 'o'], 'x', 'xxx'],
+            'Extra replacements (uniform types)' => ['foo', ['f'], ['b', 'w'], 'boo'],
+            'Extra replacements (mixed types)' => ['foo', 'f', ['b', 'w'], 'boo'],
+
+            'Recursive replacement' => ['foo', ['f', 'b'], ['b', 'w'], 'woo'],
+
+            'Regex single removal' => ['foo', new Expression('[o]'), null, 'f'],
+            'Regex substring removal' => ['foo', new Expression('[oo]'), null, 'f'],
+
+            'Regex single replacement' => ['foo', new Expression('[o$]'), 'x', 'fox'],
+            'Regex substring replacement' => ['foo', new Expression('[^foo$]'), 'bar', 'bar'],
+
+            'Regex multiple removal' => ['foo', [new Expression('[f]'), new Expression('[o]')], null, ''],
+            'Regex multiple replacement' => ['foo', [new Expression('[f]'), new Expression('[o]')], ['h', 'a'], 'haa'],
+
+            'Regex insufficient replacements' => ['foo', [new Expression('[f]'), new Expression('[o]')], ['x'], 'xxx'],
+            'Regex extra replacements' => ['foo', new Expression('[f]'), ['b', 'w'], 'boo'],
+
+            'Mixed mode replacement' => ['foo', ['f', new Expression('[o$]')], ['c', 'x'], 'cox'],
+            'Sub-match replacement' => ['foo', new Expression('[(f)oo]'), 'o$1$1', 'off'],
+        ];
+    }
+}