Add find method

The `find` method accepts an array of keys, and iterates over the
returning the value of the first key that matches. This allows for some
itneresting behavior, such as defacto aliases for values or setting
built-in defaults.

Author: alwaysblank

README.md

@@ -20,3 +20,4 @@ If you're interested in the history and motivation of this project, it's an atte
 - Some way to define some properties about arguments:
     - Argument order on output--necessary for methods like `pass` to work, possibly for other reasons.
     - Expected arguments--again necessary for `pass`, but likely useful in other contexts too.
+- Allow for "fallback" keys when using `find` method.

src/Brief.php

@@ -37,9 +37,9 @@ protected static function normalizeInput($items)
             return get_object_vars($items);
         }
 
-	if (null === $items || is_bool($items)) {
-	    return [];
-	}
+        if (null === $items || is_bool($items)) {
+            return [];
+        }
 
         if ( ! is_array($items)) {
             throw new WrongArgumentTypeException("Did not pass array or iterable object.");
@@ -322,4 +322,33 @@ public function passArray(callable $callable, $keyed = true)
 
         return call_user_func($callable, $arg);
     }
+
+    /**
+     * Pass an array of keys, and return the value for the first one that matches.
+     *
+     * @param array $keys
+     *
+     * @return bool
+     */
+    public function find($keys)
+    {
+        // Be friendly
+        if (is_string($keys)) {
+            return $this->getArgument($keys);
+        }
+
+        // ...Otherwise, it has to be an array
+        if ( ! is_array($keys)) {
+            return false;
+        }
+
+        // Prevent infinite recursion
+        if (empty($keys)) {
+            return false;
+        }
+
+        $get = array_shift($keys);
+
+        return $this->getArgument($get) ?: $this->find($keys);
+    }
 }

tests/BriefTest.php

@@ -155,4 +155,50 @@ public function testIfItemIsSetInBrief(): void
         $this->assertTrue(isset($Brief->key1));
         $this->assertFalse(isset($Brief->key3));
     }
+
+    public function testCanFindSingleKey(): void
+    {
+        $Brief =  Brief::make([
+            'key1' => 'value1',
+            'key2' => 'value2',
+        ]);
+        $this->assertEquals('value1', $Brief->find(['key1']));
+    }
+
+    public function testCanFindUnderstandString(): void
+    {
+        $Brief =  Brief::make([
+            'key1' => 'value1',
+            'key2' => 'value2',
+        ]);
+        $this->assertEquals('value1', $Brief->find('key1'));
+    }
+
+    public function testFindReturnsFalseIfNotGivenAnArrayOrString(): void
+    {
+        $Brief =  Brief::make([
+            'key1' => 'value1',
+            'key2' => 'value2',
+        ]);
+        $this->assertFalse($Brief->find(2));
+        $this->assertFalse($Brief->find(new Brief([])));
+    }
+
+    public function testCanFindFallbackKey(): void
+    {
+        $Brief =  Brief::make([
+            'key1' => 'value1',
+            'key2' => 'value2',
+        ]);
+        $this->assertEquals('value2', $Brief->find(['nonexistant', 'key2']));
+    }
+
+    public function testReturnFalseIfCannotFindAnyKey(): void
+    {
+        $Brief =  Brief::make([
+            'key1' => 'value1',
+            'key2' => 'value2',
+        ]);
+        $this->assertFalse($Brief->find(['a', 'b', 'c', 'd']));
+    }
 }