Merge branch 'release/0.5.0'

eloquent · Oct 27, 2013 · 9ce5c33 · 9ce5c33
2 parents 723452b + df9ca46
commit 9ce5c33
Show file tree

Hide file tree

Showing 18 changed files with 311 additions and 12 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,16 @@
 # Pathogen changelog
 
+## 0.5.0 (2013-10-28)
+
+- **[NEW]** All paths now implement `atomAt()` and `atomAtDefault()` ([#28]).
+
+[#28]: https://github.com/eloquent/pathogen/issues/28
+
 ## 0.4.0 (2013-10-18)
 
-- **[NEW]** All paths now implement `toAbsolute()` and `toRelative()`.
+- **[NEW]** All paths now implement `toAbsolute()` and `toRelative()` ([#27]).
+
+[#27]: https://github.com/eloquent/pathogen/issues/27
 
 ## 0.3.0 (2013-09-27)
 

diff --git a/src/Eloquent/Pathogen/AbstractPath.php b/src/Eloquent/Pathogen/AbstractPath.php
@@ -69,6 +69,42 @@ public function atoms()
         return $this->atoms;
     }
 
+    /**
+     * Get a single path atom by index.
+     *
+     * @param integer $index The index to search for.
+     *
+     * @return string                               The path atom.
+     * @throws Exception\UndefinedPathAtomException If the index does not exist in this path's atoms.
+     */
+    public function atomAt($index)
+    {
+        $atom = $this->atomAtDefault($index);
+        if (null === $atom) {
+            throw new Exception\UndefinedPathAtomException($index);
+        }
+
+        return $atom;
+    }
+
+    /**
+     * Get a single path atom by index.
+     *
+     * @param integer $index   The index to search for.
+     * @param mixed   $default The default value to return if no atom is defined for the supplied index.
+     *
+     * @return mixed The path atom, or $default if no atom is defined for the supplied index.
+     */
+    public function atomAtDefault($index, $default = null)
+    {
+        $atoms = $this->atoms();
+        if (array_key_exists($index, $atoms)) {
+            return $atoms[$index];
+        }
+
+        return $default;
+    }
+
     /**
      * Get a subset of the atoms of this path.
      *

diff --git a/src/Eloquent/Pathogen/Exception/AbstractInvalidPathAtomException.php b/src/Eloquent/Pathogen/Exception/AbstractInvalidPathAtomException.php
@@ -24,7 +24,7 @@ abstract class AbstractInvalidPathAtomException extends Exception
      * Construct a new invalid path atom exception.
      *
      * @param string         $atom     The invalid path atom.
-     * @param Exception|null $previous The previous exception, if available.
+     * @param Exception|null $previous The cause, if available.
      */
     public function __construct($atom, Exception $previous = null)
     {

diff --git a/src/Eloquent/Pathogen/Exception/EmptyPathAtomException.php b/src/Eloquent/Pathogen/Exception/EmptyPathAtomException.php
@@ -21,7 +21,7 @@ final class EmptyPathAtomException extends AbstractInvalidPathAtomException
     /**
      * Construct a new empty path atom exception.
      *
-     * @param Exception|null $previous The previous exception, if available.
+     * @param Exception|null $previous The cause, if available.
      */
     public function __construct(Exception $previous = null)
     {

diff --git a/src/Eloquent/Pathogen/Exception/EmptyPathException.php b/src/Eloquent/Pathogen/Exception/EmptyPathException.php
@@ -12,17 +12,16 @@
 namespace Eloquent\Pathogen\Exception;
 
 use Exception;
-use LogicException;
 
 /**
  * No path atoms were supplied when constructing a new relative path.
  */
-final class EmptyPathException extends LogicException
+final class EmptyPathException extends Exception
 {
     /**
      * Construct a new empty path exception.
      *
-     * @param Exception|null $previous The previous exception, if available.
+     * @param Exception|null $previous The cause, if available.
      */
     public function __construct(Exception $previous = null)
     {

diff --git a/src/Eloquent/Pathogen/Exception/InvalidPathAtomCharacterException.php b/src/Eloquent/Pathogen/Exception/InvalidPathAtomCharacterException.php
@@ -23,7 +23,7 @@ final class InvalidPathAtomCharacterException extends AbstractInvalidPathAtomExc
      *
      * @param string         $atom      The invalid path atom.
      * @param string         $character The invalid character.
-     * @param Exception|null $previous  The previous exception, if available.
+     * @param Exception|null $previous  The cause, if available.
      */
     public function __construct($atom, $character, Exception $previous = null)
     {

diff --git a/src/Eloquent/Pathogen/Exception/InvalidPathStateException.php b/src/Eloquent/Pathogen/Exception/InvalidPathStateException.php
@@ -12,18 +12,17 @@
 namespace Eloquent\Pathogen\Exception;
 
 use Exception;
-use LogicException;
 
 /**
  * An attempt was made to construct a new path in an invalid state.
  */
-final class InvalidPathStateException extends LogicException
+final class InvalidPathStateException extends Exception
 {
     /**
      * Construct a new invalid path state exception.
      *
      * @param string         $reason   The reason message.
-     * @param Exception|null $previous The previous exception, if available.
+     * @param Exception|null $previous The cause, if available.
      */
     public function __construct($reason, Exception $previous = null)
     {

diff --git a/src/Eloquent/Pathogen/Exception/UndefinedPathAtomException.php b/src/Eloquent/Pathogen/Exception/UndefinedPathAtomException.php
@@ -0,0 +1,52 @@
+<?php
+
+/*
+ * This file is part of the Pathogen package.
+ *
+ * Copyright © 2013 Erin Millard
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Eloquent\Pathogen\Exception;
+
+use Exception;
+
+/**
+ * An undefined path atom was requested.
+ */
+final class UndefinedPathAtomException extends Exception
+{
+    /**
+     * Construct a new undefined path atom exception.
+     *
+     * @param integer        $index    The requested atom index.
+     * @param Exception|null $previous The cause, if available.
+     */
+    public function __construct($index, Exception $previous = null)
+    {
+        $this->index = $index;
+
+        parent::__construct(
+            sprintf(
+                'No path atom defined for index %s.',
+                var_export($index, true)
+            ),
+            0,
+            $previous
+        );
+    }
+
+    /**
+     * Get the requested atom index.
+     *
+     * @return string The requested index.
+     */
+    public function index()
+    {
+        return $this->index;
+    }
+
+    private $index;
+}
diff --git a/src/Eloquent/Pathogen/PathInterface.php b/src/Eloquent/Pathogen/PathInterface.php
@@ -26,6 +26,26 @@ interface PathInterface
      */
     public function atoms();
 
+    /**
+     * Get a single path atom by index.
+     *
+     * @param integer $index The index to search for.
+     *
+     * @return string                               The path atom.
+     * @throws Exception\UndefinedPathAtomException If the index does not exist in this path's atoms.
+     */
+    public function atomAt($index);
+
+    /**
+     * Get a single path atom by index.
+     *
+     * @param integer $index   The index to search for.
+     * @param mixed   $default The default value to return if no atom is defined for the supplied index.
+     *
+     * @return mixed The path atom, or $default if no atom is defined for the supplied index.
+     */
+    public function atomAtDefault($index, $default = null);
+
     /**
      * Get a subset of the atoms of this path.
      *

diff --git a/src/Eloquent/Pathogen/Windows/Exception/DriveMismatchException.php b/src/Eloquent/Pathogen/Windows/Exception/DriveMismatchException.php
@@ -23,7 +23,7 @@ final class DriveMismatchException extends Exception
      *
      * @param string         $leftDrive  The left-hand drive specifier.
      * @param string         $rightDrive The right-hand drive specifier.
-     * @param Exception|null $previous   The previous exception, if available.
+     * @param Exception|null $previous   The cause, if available.
      */
     public function __construct(
         $leftDrive,

diff --git a/src/Eloquent/Pathogen/Windows/Exception/InvalidDriveSpecifierException.php b/src/Eloquent/Pathogen/Windows/Exception/InvalidDriveSpecifierException.php
@@ -22,7 +22,7 @@ final class InvalidDriveSpecifierException extends Exception
      * Constructs a new invalid drive specifier exception.
      *
      * @param string         $drive    The invalid drive specifier.
-     * @param Exception|null $previous The previous exception, if available.
+     * @param Exception|null $previous The cause, if available.
      */
     public function __construct($drive, Exception $previous = null)
     {

diff --git a/test/suite/Eloquent/Pathogen/AbsolutePathTest.php b/test/suite/Eloquent/Pathogen/AbsolutePathTest.php
@@ -81,6 +81,32 @@ public function testConstructorFailureEmptyAtom()
         new AbsolutePath(array(''));
     }
 
+    public function testAtomAt()
+    {
+        $path = $this->factory->create('/foo/bar');
+
+        $this->assertSame('foo', $path->atomAt(0));
+        $this->assertSame('bar', $path->atomAt(1));
+    }
+
+    public function testAtomAtFailure()
+    {
+        $path = $this->factory->create('/foo/bar');
+
+        $this->setExpectedException(__NAMESPACE__ . '\Exception\UndefinedPathAtomException');
+        $path->atomAt(2);
+    }
+
+    public function testAtomAtDefault()
+    {
+        $path = $this->factory->create('/foo/bar');
+
+        $this->assertSame('foo', $path->atomAtDefault(0, 'baz'));
+        $this->assertSame('bar', $path->atomAtDefault(1, 'baz'));
+        $this->assertSame('baz', $path->atomAtDefault(2, 'baz'));
+        $this->assertNull($path->atomAtDefault(2));
+    }
+
     public function sliceAtomsData()
     {
         //                                  path                 index  length  expectedResult

diff --git a/test/suite/Eloquent/Pathogen/Exception/UndefinedPathAtomExceptionTest.php b/test/suite/Eloquent/Pathogen/Exception/UndefinedPathAtomExceptionTest.php
@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the Pathogen package.
+ *
+ * Copyright © 2013 Erin Millard
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Eloquent\Pathogen\Exception;
+
+use Exception;
+use PHPUnit_Framework_TestCase;
+
+class UndefinedPathAtomExceptionTest extends PHPUnit_Framework_TestCase
+{
+    public function testException()
+    {
+        $previous = new Exception;
+        $exception = new UndefinedPathAtomException(111, $previous);
+
+        $this->assertSame(111, $exception->index());
+        $this->assertSame('No path atom defined for index 111.', $exception->getMessage());
+        $this->assertSame(0, $exception->getCode());
+        $this->assertSame($previous, $exception->getPrevious());
+    }
+}
diff --git a/test/suite/Eloquent/Pathogen/RelativePathTest.php b/test/suite/Eloquent/Pathogen/RelativePathTest.php
@@ -89,6 +89,32 @@ public function testConstructorFailureEmptyPath()
         new RelativePath(array());
     }
 
+    public function testAtomAt()
+    {
+        $path = $this->factory->create('foo/bar');
+
+        $this->assertSame('foo', $path->atomAt(0));
+        $this->assertSame('bar', $path->atomAt(1));
+    }
+
+    public function testAtomAtFailure()
+    {
+        $path = $this->factory->create('foo/bar');
+
+        $this->setExpectedException(__NAMESPACE__ . '\Exception\UndefinedPathAtomException');
+        $path->atomAt(2);
+    }
+
+    public function testAtomAtDefault()
+    {
+        $path = $this->factory->create('foo/bar');
+
+        $this->assertSame('foo', $path->atomAtDefault(0, 'baz'));
+        $this->assertSame('bar', $path->atomAtDefault(1, 'baz'));
+        $this->assertSame('baz', $path->atomAtDefault(2, 'baz'));
+        $this->assertNull($path->atomAtDefault(2));
+    }
+
     public function sliceAtomsData()
     {
         //                                  path                index  length  expectedResult

diff --git a/test/suite/Eloquent/Pathogen/Unix/AbsoluteUnixPathTest.php b/test/suite/Eloquent/Pathogen/Unix/AbsoluteUnixPathTest.php
@@ -83,6 +83,32 @@ public function testConstructorFailureEmptyAtom()
         new AbsoluteUnixPath(array(''));
     }
 
+    public function testAtomAt()
+    {
+        $path = $this->factory->create('/foo/bar');
+
+        $this->assertSame('foo', $path->atomAt(0));
+        $this->assertSame('bar', $path->atomAt(1));
+    }
+
+    public function testAtomAtFailure()
+    {
+        $path = $this->factory->create('/foo/bar');
+
+        $this->setExpectedException('Eloquent\Pathogen\Exception\UndefinedPathAtomException');
+        $path->atomAt(2);
+    }
+
+    public function testAtomAtDefault()
+    {
+        $path = $this->factory->create('/foo/bar');
+
+        $this->assertSame('foo', $path->atomAtDefault(0, 'baz'));
+        $this->assertSame('bar', $path->atomAtDefault(1, 'baz'));
+        $this->assertSame('baz', $path->atomAtDefault(2, 'baz'));
+        $this->assertNull($path->atomAtDefault(2));
+    }
+
     public function sliceAtomsData()
     {
         //                                  path                 index  length  expectedResult

diff --git a/test/suite/Eloquent/Pathogen/Unix/RelativeUnixPathTest.php b/test/suite/Eloquent/Pathogen/Unix/RelativeUnixPathTest.php
@@ -91,6 +91,32 @@ public function testConstructorFailureEmptyPath()
         new RelativeUnixPath(array());
     }
 
+    public function testAtomAt()
+    {
+        $path = $this->factory->create('foo/bar');
+
+        $this->assertSame('foo', $path->atomAt(0));
+        $this->assertSame('bar', $path->atomAt(1));
+    }
+
+    public function testAtomAtFailure()
+    {
+        $path = $this->factory->create('foo/bar');
+
+        $this->setExpectedException('Eloquent\Pathogen\Exception\UndefinedPathAtomException');
+        $path->atomAt(2);
+    }
+
+    public function testAtomAtDefault()
+    {
+        $path = $this->factory->create('foo/bar');
+
+        $this->assertSame('foo', $path->atomAtDefault(0, 'baz'));
+        $this->assertSame('bar', $path->atomAtDefault(1, 'baz'));
+        $this->assertSame('baz', $path->atomAtDefault(2, 'baz'));
+        $this->assertNull($path->atomAtDefault(2));
+    }
+
     public function sliceAtomsData()
     {
         //                                  path                index  length  expectedResult