Merge pull request #4 from ergebnis/fix/rename

Fix: Rename methods

CHANGELOG.md

@@ -6,7 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## Unreleased
 
-For a full diff see [`1.0.0...main`][1.0.0...main].
+For a full diff see [`2.0.0...main`][2.0.0...main].
+
+## [`2.0.0`][2.0.0]
+
+For a full diff see [`1.0.0...2.0.0`][1.0.0...2.0.0].
+
+## Changed
+
+- Renamed named constructors and accessors of `Exception\InvalidJsonPointer`, `JsonPointer`, and `ReferenceToken` ([#4]), by [@localheinz]
+
+  - `Exception\InvalidJsonPointer::fromString()` to `JsonPointer::fromJsonString()`
+  - `JsonPointer::fromString()` to `JsonPointer::fromJsonString()`
+  - `JsonPointer::toString()` to `JsonPointer::toJsonString()`
+  - `ReferenceToken::fromEscapedString()` to `ReferenceToken::fromJsonString()`
+  - `ReferenceToken::fromUnescapedString()` to `ReferenceToken::fromString()`
+  - `ReferenceToken::toEscapedString()` to `ReferenceToken::toJsonString()`
+  - `ReferenceToken::toUnescapedString()` to `ReferenceToken::toString()`
 
 ## [`1.0.0`][1.0.0]
 
@@ -19,8 +35,10 @@ For a full diff see [`a5ba52c...1.0.0`][a5ba52c...1.0.0].
 
 [a5ba52c...1.0.0]: https://github.com/ergebnis/json-pointer/compare/a5ba52c...1.0.0
 [1.0.0...main]: https://github.com/ergebnis/json-pointer/compare/1.0.0...main
+[2.0.0...main]: https://github.com/ergebnis/json-pointer/compare/2.0.0...main
 
 [#1]: https://github.com/ergebnis/json-pointer/pull/1
 [#2]: https://github.com/ergebnis/json-pointer/pull/2
+[#4]: https://github.com/ergebnis/json-pointer/pull/4
 
 [@localheinz]: https://github.com/localheinz

README.md

@@ -25,7 +25,7 @@ composer require ergebnis/json-pointer
 
 ### `ReferenceToken`
 
-You can create a `ReferenceToken` from an unescaped `string` value:
+You can create a `ReferenceToken` from a `string` value:
 
 ```php
 <?php
@@ -34,13 +34,13 @@ declare(strict_types=1);
 
 use Ergebnis\Json\Pointer;
 
-$referenceToken = Pointer\ReferenceToken::fromUnescapedString('foo/bar');
+$referenceToken = Pointer\ReferenceToken::fromString('foo/bar');
 
-$referenceToken->toEscapedString();    // 'foo~1bar'
-$referenceToken->toUnescapedString();  // 'foo/bar'
+$referenceToken->toJsonString(); // 'foo~1bar'
+$referenceToken->toString();     // 'foo/bar'
 ```
 
-You can create a `ReferenceToken` from an escaped `string` value:
+You can create a `ReferenceToken` from a [JSON `string` value](https://datatracker.ietf.org/doc/html/rfc6901#section-5):
 
 ```php
 <?php
@@ -49,10 +49,10 @@ declare(strict_types=1);
 
 use Ergebnis\Json\Pointer;
 
-$referenceToken = Pointer\ReferenceToken::fromEscapedString('foo~1bar');
+$referenceToken = Pointer\ReferenceToken::fromJsonString('foo~1bar');
 
-$referenceToken->toEscapedString();    // 'foo~1bar'
-$referenceToken->toUnescapedString();  // 'foo/bar'
+$referenceToken->toJsonString(); // 'foo~1bar'
+$referenceToken->toString();     // 'foo/bar'
 ```
 
 You can create a `ReferenceToken` from an `int` value:
@@ -66,8 +66,8 @@ use Ergebnis\Json\Pointer;
 
 $referenceToken = Pointer\ReferenceToken::fromInt(9001);
 
-$referenceToken->toEscapedString();    // '9001'
-$referenceToken->toUnescapedString();  // '9001'
+$referenceToken->toJsonString(); // '9001'
+$referenceToken->toString();     // '9001'
 ```
 
 You can compare `ReferenceToken`s:
@@ -79,8 +79,8 @@ declare(strict_types=1);
 
 use Ergebnis\Json\Pointer;
 
-$one = Pointer\ReferenceToken::fromUnescapedString('foo/bar');
-$two = Pointer\ReferenceToken::fromEscapedString('foo~1bar');
+$two = Pointer\ReferenceToken::fromJsonString('foo~1bar');
+$one = Pointer\ReferenceToken::fromString('foo/bar');
 
 $one->equals($two); // true
 ```
@@ -98,10 +98,10 @@ use Ergebnis\Json\Pointer;
 
 $jsonPointer = Pointer\JsonPointer::document();
 
-$jsonPointer->toString(); // ''
+$jsonPointer->toJsonString(); // ''
 ```
 
-You can create a `JsonPointer` from a `string` value:
+You can create a `JsonPointer` from a [JSON `string` representation](https://datatracker.ietf.org/doc/html/rfc6901#section-5) value:
 
 ```php
 <?php
@@ -110,9 +110,9 @@ declare(strict_types=1);
 
 use Ergebnis\Json\Pointer;
 
-$jsonPointer = Pointer\JsonPointer::fromString('/foo/bar');
+$jsonPointer = Pointer\JsonPointer::fromJsonString('/foo/bar');
 
-$jsonPointer->toString(); // '/foo/bar'
+$jsonPointer->toJsonString(); // '/foo/bar'
 ```
 
 You can compare `JsonPointer`s:
@@ -124,8 +124,8 @@ declare(strict_types=1);
 
 use Ergebnis\Json\Pointer;
 
-$one = Pointer\JsonPointer::fromString('/foo/bar');
-$two = Pointer\JsonPointer::fromString('/foo~1bar');
+$one = Pointer\JsonPointer::fromJsonString('/foo/bar');
+$two = Pointer\JsonPointer::fromJsonString('/foo~1bar');
 
 $one->equals($two); // false
 ```
@@ -139,13 +139,13 @@ declare(strict_types=1);
 
 use Ergebnis\Json\Pointer;
 
-$jsonPointer = Pointer\JsonPointer::fromString('/foo/bar');
+$jsonPointer = Pointer\JsonPointer::fromJsonString('/foo/bar');
 
-$referenceToken = Pointer\ReferenceToken::fromUnescapedString('baz');
+$referenceToken = Pointer\ReferenceToken::fromString('baz');
 
 $newJsonPointer = $jsonPointer->append($referenceToken);
 
-$newJsonPointer->toString(); // '/foo/bar/baz'
+$newJsonPointer->toJsonString(); // '/foo/bar/baz'
 ```
 
 ## Changelog

src/Exception/InvalidJsonPointer.php

@@ -15,10 +15,10 @@
 
 final class InvalidJsonPointer extends \InvalidArgumentException implements Exception
 {
-    public static function fromString(string $value): self
+    public static function fromJsonString(string $value): self
     {
         return new self(\sprintf(
-            'Value "%s" does not appear to be a valid JSON Pointer.',
+            'Value "%s" does not appear to be a valid JSON string representation of a JSON Pointer.',
             $value,
         ));
     }

src/JsonPointer.php

@@ -20,22 +20,23 @@
  */
 final class JsonPointer
 {
-    private string $value;
+    private string $jsonStringValue;
 
-    private function __construct(string $value)
+    private function __construct(string $jsonStringValue)
     {
-        $this->value = $value;
+        $this->jsonStringValue = $jsonStringValue;
     }
 
     /**
      * @see https://datatracker.ietf.org/doc/html/rfc6901#section-3
+     * @see https://datatracker.ietf.org/doc/html/rfc6901#section-5
      *
      * @throws Exception\InvalidJsonPointer
      */
-    public static function fromString(string $value): self
+    public static function fromJsonString(string $value): self
     {
         if (1 !== \preg_match('/^(\/(?P<referenceToken>((?P<unescaped>[\x00-\x2E]|[\x30-\x7D]|[\x7F-\x{10FFFF}])|(?P<escaped>~[01]))*))*$/u', $value, $matches)) {
-            throw Exception\InvalidJsonPointer::fromString($value);
+            throw Exception\InvalidJsonPointer::fromJsonString($value);
         }
 
         return new self($value);
@@ -50,18 +51,18 @@ public function append(ReferenceToken $referenceToken): self
     {
         return new self(\sprintf(
             '%s/%s',
-            $this->value,
-            $referenceToken->toEscapedString(),
+            $this->jsonStringValue,
+            $referenceToken->toJsonString(),
         ));
     }
 
-    public function toString(): string
+    public function toJsonString(): string
     {
-        return $this->value;
+        return $this->jsonStringValue;
     }
 
     public function equals(self $other): bool
     {
-        return $this->value === $other->value;
+        return $this->jsonStringValue === $other->jsonStringValue;
     }
 }

src/ReferenceToken.php

@@ -20,11 +20,11 @@
  */
 final class ReferenceToken
 {
-    private string $escapedValue;
+    private string $jsonStringValue;
 
-    private function __construct(string $escapedValue)
+    private function __construct(string $jsonStringValue)
     {
-        $this->escapedValue = $escapedValue;
+        $this->jsonStringValue = $jsonStringValue;
     }
 
     /**
@@ -40,9 +40,11 @@ public static function fromInt(int $value): self
     }
 
     /**
+     * @see https://datatracker.ietf.org/doc/html/rfc6901#section-5
+     *
      * @throws Exception\InvalidReferenceToken
      */
-    public static function fromEscapedString(string $value): self
+    public static function fromJsonString(string $value): self
     {
         if (1 !== \preg_match('/^(?P<referenceToken>((?P<unescaped>[\x00-\x2E]|[\x30-\x7D]|[\x7F-\x{10FFFF}])|(?P<escaped>~[01]))*)$/u', $value)) {
             throw Exception\InvalidReferenceToken::fromString($value);
@@ -51,9 +53,9 @@ public static function fromEscapedString(string $value): self
         return new self($value);
     }
 
-    public static function fromUnescapedString(string $value): self
+    public static function fromString(string $value): self
     {
-        return self::fromEscapedString(\str_replace(
+        return self::fromJsonString(\str_replace(
             [
                 '~',
                 '/',
@@ -66,12 +68,12 @@ public static function fromUnescapedString(string $value): self
         ));
     }
 
-    public function toEscapedString(): string
+    public function toJsonString(): string
     {
-        return $this->escapedValue;
+        return $this->jsonStringValue;
     }
 
-    public function toUnescapedString(): string
+    public function toString(): string
     {
         return \str_replace(
             [
@@ -82,12 +84,12 @@ public function toUnescapedString(): string
                 '/',
                 '~',
             ],
-            $this->escapedValue,
+            $this->jsonStringValue,
         );
     }
 
     public function equals(self $other): bool
     {
-        return $this->escapedValue === $other->escapedValue;
+        return $this->jsonStringValue === $other->jsonStringValue;
     }
 }

test/Unit/Exception/InvalidJsonPointerTest.php

@@ -26,14 +26,14 @@ final class InvalidJsonPointerTest extends Framework\TestCase
 {
     use Test\Util\Helper;
 
-    public function testFromValueReturnsInvalidJsonPointerException(): void
+    public function testFromJsonStringReturnsInvalidJsonPointerException(): void
     {
         $value = self::faker()->sentence();
 
-        $exception = Exception\InvalidJsonPointer::fromString($value);
+        $exception = Exception\InvalidJsonPointer::fromJsonString($value);
 
         $message = \sprintf(
-            'Value "%s" does not appear to be a valid JSON Pointer.',
+            'Value "%s" does not appear to be a valid JSON string representation of a JSON Pointer.',
             $value,
         );