Added documentation to readme and accompanying DocumentationTest.

Added documentation to strategy docblocks.
Renamed ocurrences of $strategyOrMapping -> $expression.
Renamed InvalidMapperTypeException -> InvalidExpressionException.

Author: Bilge

README.md

@@ -1,6 +1,6 @@
 {
   "name": "scriptfusion/mapper",
-  "description": "Maps data from one format to another using an object composition DSL.",
+  "description": "Transforms arrays using an object composition DSL.",
   "authors": [
     {
       "name": "Bilge",

composer.json

@@ -0,0 +1,10 @@
+<?php
+namespace ScriptFUSION\Mapper;
+
+/**
+ * The exception that is thrown when an invalid expression is specified.
+ */
+class InvalidExpressionException extends \RuntimeException
+{
+    // Intentionally empty.
+}

src/InvalidExpressionException.php

@@ -10,30 +10,30 @@ class Mapper
 {
     /**
      * @param array $record
-     * @param Strategy|Mapping|array|mixed $strategyOrMapping
+     * @param Strategy|Mapping|array|mixed $expression
      * @param mixed $context
      *
      * @return mixed
      *
-     * @throws InvalidMapperTypeException An invalid strategy or mapping object was specified.
+     * @throws InvalidExpressionException An invalid strategy or mapping object was specified.
      */
-    public function map(array $record, $strategyOrMapping, $context = null)
+    public function map(array $record, $expression, $context = null)
     {
         /* Strategy. */
-        if ($strategyOrMapping instanceof Strategy) {
-            return $this->mapStrategy($record, $strategyOrMapping, $context);
+        if ($expression instanceof Strategy) {
+            return $this->mapStrategy($record, $expression, $context);
         } /* Mapping. */
-        elseif ($strategyOrMapping instanceof Mapping) {
-            return $this->mapMapping($record, $strategyOrMapping, $context);
+        elseif ($expression instanceof Mapping) {
+            return $this->mapMapping($record, $expression, $context);
         } /* Mapping fragment. */
-        elseif (is_array($strategyOrMapping)) {
-            return $this->mapFragment($record, $strategyOrMapping, $context);
+        elseif (is_array($expression)) {
+            return $this->mapFragment($record, $expression, $context);
         } /* Scalar values. */
-        elseif (is_scalar($strategyOrMapping)) {
-            return $strategyOrMapping;
+        elseif (is_scalar($expression)) {
+            return $expression;
         }
 
-        throw new InvalidMapperTypeException('Invalid strategy or mapping: "' . get_class($strategyOrMapping) . '".');
+        throw new InvalidExpressionException('Invalid strategy or mapping: "' . get_class($expression) . '".');
     }
 
     /**

src/InvalidMapperTypeException.php

@@ -1,6 +1,9 @@
 <?php
 namespace ScriptFUSION\Mapper\Strategy;
 
+/**
+ * Augments data using the return value of the specified callback.
+ */
 class Callback implements Strategy
 {
     private $callback;

src/Mapper.php

@@ -4,20 +4,19 @@
 use ScriptFUSION\Mapper\Mapping;
 
 /**
- * Decorates a data collection by applying a transformation to each datum.
+ * Decorates a collection of data by applying a transformation to each datum using a callback.
  */
 class Collection extends Delegate
 {
     private $transformation;
 
     /**
-     * Initializes this instance with the specified strategy or mapping that
-     * yields a data collection and the specified strategy or mapping that
-     * describes how to transform each datum in the collection.
+     * Initializes this instance with the specified strategy or mapping that yields a data collection and the specified
+     * strategy or mapping that describes how to transform each datum in the collection.
      *
-     * @param Strategy|Mapping|array|mixed $collection Data collection.
-     * @param Strategy|Mapping|array|mixed $transformation Transformation
-     *     strategy or mapping fragment.
+     * @param Strategy|Mapping|array|mixed $collection Data collection expression that maps to an array
+     * @param Strategy|Mapping|array|mixed $transformation Transformation expression.
+     *     The current datum is passed as context.
      */
     public function __construct($collection, $transformation)
     {

src/Strategy/Callback.php

@@ -1,19 +1,28 @@
 <?php
 namespace ScriptFUSION\Mapper\Strategy;
 
-class Context extends Decorator
+use ScriptFUSION\Mapper\Mapping;
+
+/**
+ * Replaces the context for the specified expression.
+ */
+class Context extends Delegate
 {
-    private $strategyOrMapping;
+    private $expression;
 
-    public function __construct(Strategy $strategy, $strategyOrMapping)
+    /**
+     * @param Strategy|Mapping|array|mixed $expression Expression.
+     * @param Strategy|Mapping|array|mixed $context New context.
+     */
+    public function __construct($expression, $context)
     {
-        parent::__construct($strategy);
+        parent::__construct($expression);
 
-        $this->strategyOrMapping = $strategyOrMapping;
+        $this->expression = $context;
     }
 
     public function __invoke($data, $context = null)
     {
-        return parent::__invoke($data, $this->delegate($this->strategyOrMapping, $data, $context));
+        return parent::__invoke($data, $this->delegate($this->expression, $data, $context));
     }
 }

src/Strategy/Collection.php

@@ -3,6 +3,9 @@
 
 use ScriptFUSION\ArrayWalker\ArrayWalker;
 
+/**
+ * Copies a portion of input data.
+ */
 class Copy implements Strategy
 {
     const PATH_SEPARATOR = '->';
@@ -12,7 +15,7 @@ class Copy implements Strategy
     /**
      * Initializes this instance with the specified path.
      *
-     * @param array|string $path Path.
+     * @param array|string $path Array of path components or string of  `->`-delimited components.
      */
     public function __construct($path)
     {
@@ -27,7 +30,7 @@ public function __construct($path)
      */
     public function __invoke($data, $context = null)
     {
-        if (is_array($data)) {
+        if ($this->path && is_array($data)) {
             return ArrayWalker::walk($data, $this->path);
         }
     }

src/Strategy/Context.php

@@ -1,10 +1,18 @@
 <?php
 namespace ScriptFUSION\Mapper\Strategy;
 
+/**
+ * Copies a portion of context data.
+ */
 class CopyContext extends Copy
 {
     private $walk;
 
+    /**
+     * {@inheritdoc}
+     *
+     * @param array|string $path Array of path components or string of  `->`-delimited components.
+     */
     public function __construct($path = null)
     {
         parent::__construct($path);