Merge pull request #56 from ergebnis/feature/never

Enhancement: Implement `Specification::closure()`

CHANGELOG.md

@@ -6,7 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## Unreleased
 
-For a full diff see [`3.0.0...main`][3.0.0...main].
+For a full diff see [`3.1.0...main`][3.1.0...main].
+
+## [`3.1.0`][3.1.0]
+
+For a full diff see [`3.1.0...3.0.0`][2.1.0...3.0.0].
+
+## Added
+
+- Added `Specification::closure()` ([#56]), by [@localheinz]
 
 ## [`3.0.0`][3.0.0]
 
@@ -78,5 +86,6 @@ For a full diff see [`a5ba52c...1.0.0`][a5ba52c...1.0.0].
 [#17]: https://github.com/ergebnis/json-pointer/pull/17
 [#48]: https://github.com/ergebnis/json-pointer/pull/48
 [#53]: https://github.com/ergebnis/json-pointer/pull/53
+[#56]: https://github.com/ergebnis/json-pointer/pull/56
 
 [@localheinz]: https://github.com/localheinz

README.md

@@ -212,7 +212,24 @@ $newJsonPointer->toUriFragmentIdentifierString(); // '#foo/bar/baz'
 
 ### `Specification`
 
-You can create a `Specification` to find out if a `JsonPointer` satisfies it:
+You can create a `Specification` that is satisfied when a closure returns `true` for a `JsonPointer`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Ergebnis\Json\Pointer;
+
+$specification = Pointer\Specification::closure(static function (Pointer\JsonPointer $jsonPointer) {
+    return $jsonPointer->toJsonString() === '/foo/bar';
+});
+
+$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));     // false
+$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // true
+```
+
+You can create a `Specification` that is satisfied when a `JsonPointer` equals another `JsonPointer`:
 
 ```php
 <?php
@@ -237,7 +254,9 @@ declare(strict_types=1);
 use Ergebnis\Json\Pointer;
 
 $specification = Pointer\Specification::anyOf(
-    Pointer\Specification::equals(Pointer\JsonPointer::fromJsonString('/foo/bar')),
+    Pointer\Specification::closure(static function(Pointer\JsonPointer $jsonPointer) {
+        return $jsonPointer->toJsonString() === '/foo/bar';
+    }),
     Pointer\Specification::equals(Pointer\JsonPointer::fromJsonString('/foo/baz')),
 );
 

src/Specification.php

@@ -48,6 +48,14 @@ public static function anyOf(self ...$specifications): self
         });
     }
 
+    /**
+     * @param \Closure(JsonPointer):bool $closure
+     */
+    public static function closure(\Closure $closure): self
+    {
+        return new self($closure);
+    }
+
     public static function equals(JsonPointer $other): self
     {
         return new self(static function (JsonPointer $jsonPointer) use ($other): bool {

test/Unit/SpecificationTest.php

@@ -65,6 +65,28 @@ public function testAnyOfIsNotSatisfiedByJsonPointerWhenAnyOfTheSpecificationsIs
         self::assertTrue($specification->isSatisfiedBy($jsonPointer));
     }
 
+    public function testClosureIsNotSatisfiedWhenClosureReturnsFalse(): void
+    {
+        $jsonPointer = JsonPointer::fromJsonString('/foo/bar');
+
+        $specification = Specification::closure(static function (): bool {
+            return false;
+        });
+
+        self::assertFalse($specification->isSatisfiedBy($jsonPointer));
+    }
+
+    public function testClosureIsSatisfiedWhenClosureReturnsTrue(): void
+    {
+        $jsonPointer = JsonPointer::fromJsonString('/foo/bar');
+
+        $specification = Specification::closure(static function (): bool {
+            return true;
+        });
+
+        self::assertTrue($specification->isSatisfiedBy($jsonPointer));
+    }
+
     public function testEqualsIsNotSatisfiedByJsonPointerWhenJsonPointerDoesNotEqualOther(): void
     {
         $jsonPointer = JsonPointer::fromJsonString('/foo/bar/baz');