Enhancement: Implement Specification::not()

CHANGELOG.md

@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 For a full diff see [`3.1.0...main`][3.1.0...main].
 
+## Added
+
+- Added `Specification::not()` ([#120]), by [@localheinz]
+
 ## Changed
 
 - Dropped support for PHP 7.4 ([#119]), by [@localheinz]
@@ -99,5 +103,6 @@ For a full diff see [`a5ba52c...1.0.0`][a5ba52c...1.0.0].
 [#57]: https://github.com/ergebnis/json-pointer/pull/57
 [#58]: https://github.com/ergebnis/json-pointer/pull/58
 [#119]: https://github.com/ergebnis/json-pointer/pull/119
+[#120]: https://github.com/ergebnis/json-pointer/pull/120
 
 [@localheinz]: https://github.com/localheinz

README.md

@@ -273,6 +273,21 @@ $specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));
 $specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // false
 ```
 
+You can create a `Specification` that is satisfied when another `Specification` is not satisfied by a `JsonPointer`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use Ergebnis\Json\Pointer;
+
+$specification = Pointer\Specification::not(Pointer\Specification::equals(Pointer\JsonPointer::fromJsonString('/foo/bar')));
+
+$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo'));     // true
+$specification->isSatisfiedBy(Pointer\JsonPointer::fromJsonString('/foo/bar')); // false
+```
+
 You can compose `Specification`s to find out if a `JsonPointer` satisfies any of them:
 
 ```php

src/Specification.php

@@ -72,4 +72,11 @@ public static function never(): self
             return false;
         });
     }
+
+    public static function not(self $specification): self
+    {
+        return new self(static function (JsonPointer $jsonPointer) use ($specification): bool {
+            return !$specification->isSatisfiedBy($jsonPointer);
+        });
+    }
 }

test/Unit/SpecificationTest.php

@@ -126,4 +126,22 @@ public function testNeverIsNotSatisfiedByAnyJsonPointer(): void
 
         self::assertFalse($specification->isSatisfiedBy($jsonPointer));
     }
+
+    public function testNotIsNotSatisfiedByJsonPointerWhenJsonPointerSatisfiesSpecification(): void
+    {
+        $jsonPointer = JsonPointer::fromJsonString('/foo/bar/baz');
+
+        $specification = Specification::not(Specification::always());
+
+        self::assertFalse($specification->isSatisfiedBy($jsonPointer));
+    }
+
+    public function testNotIsSatisfiedByJsonPointerWhenJsonPointerDoesNotSatisfySpecification(): void
+    {
+        $jsonPointer = JsonPointer::fromJsonString('/foo/bar');
+
+        $specification = Specification::not(Specification::never());
+
+        self::assertTrue($specification->isSatisfiedBy($jsonPointer));
+    }
 }