Implement missing features for literal string escape sequences (#104)

Author: PrinsFrank

src/Document/ContentStream/PositionedText/PositionedTextElement.php

@@ -2,6 +2,7 @@
 
 namespace PrinsFrank\PdfParser\Document\ContentStream\PositionedText;
 
+use PrinsFrank\PdfParser\Document\Generic\Character\LiteralStringEscapeCharacter;
 use PrinsFrank\PdfParser\Document\Object\Decorator\Font;
 use PrinsFrank\PdfParser\Exception\ParseFailureException;
 
@@ -23,9 +24,7 @@ public function getText(?Font $font): string {
         $string = '';
         foreach ($matches as $match) {
             if (str_starts_with($match['chars'], '(') && str_ends_with($match['chars'], ')')) {
-                $chars = str_replace(['\(', '\)', '\n', '\r'], ['(', ')', "\n", "\r"], substr($match['chars'], 1, -1));
-                $chars = preg_replace_callback('/\\\\([0-7]{3})/', fn (array $matches) => mb_chr((int) octdec($matches[1])), $chars)
-                    ?? throw new ParseFailureException();
+                $chars = LiteralStringEscapeCharacter::unescapeCharacters(substr($match['chars'], 1, -1));
                 if ($font !== null && ($encoding = $font->getEncoding()) !== null) {
                     $chars = $encoding->decodeString($chars);
                 }

src/Document/Generic/Character/LiteralStringEscapeCharacter.php

@@ -3,6 +3,8 @@
 
 namespace PrinsFrank\PdfParser\Document\Generic\Character;
 
+use PrinsFrank\PdfParser\Exception\ParseFailureException;
+
 /**
  * @internal
  *
@@ -17,5 +19,47 @@ enum LiteralStringEscapeCharacter: string {
     case LEFT_PARENTHESIS = '\(';
     case RIGHT_PARENTHESIS = '\)';
     case REVERSE_SOLIDUS = '\\';
-    case CHARACTER_CODE = '\ddd';
+
+    public function getActualCharacter(): string {
+        return match($this) {
+            self::LINE_FEED => "\n",
+            self::CARRIAGE_RETURN => "\r",
+            self::HORIZONTAL_TAB => "\t",
+            self::BACKSPACE => "\x08",
+            self::FORM_FEED => "\x0C",
+            self::LEFT_PARENTHESIS => "(",
+            self::RIGHT_PARENTHESIS => ")",
+            self::REVERSE_SOLIDUS => "\\",
+        };
+    }
+
+    /** @return array{0: list<string>, 1: list<string>} */
+    private static function getReplacementSet(): array {
+        $find = $replace = [];
+        foreach (self::cases() as $case) {
+            $find[] = $case->value;
+            $replace[] = $case->getActualCharacter();
+        }
+
+        return [$find, $replace];
+    }
+
+    public static function unescapeCharacters(string $string): string {
+        $string = str_replace("\\\n", '', $string); // Example 2, 7.3.4.2 newlines preceded by reverse solidus should be handled like single lines
+
+        [$find, $replace] = LiteralStringEscapeCharacter::getReplacementSet();
+
+        return preg_replace_callback(
+            '/\\\\([0-7]{1,3})/',
+            static function (array $matches) {
+                $decimal = octdec($matches[1]);
+                if (!is_int($decimal) || $decimal < 0 || $decimal > 255) {
+                    throw new ParseFailureException(sprintf('Invalid octal value "%s"', $matches[1]));
+                }
+
+                return mb_chr($decimal);
+            },
+            str_replace($find, $replace, $string)
+        ) ?? throw new ParseFailureException();
+    }
 }

tests/Unit/Document/Generic/Character/LiteralStringEscapeCharacterTest.php

@@ -0,0 +1,76 @@
+<?php declare(strict_types=1);
+
+namespace PrinsFrank\PdfParser\Tests\Unit\Document\Generic\Character;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use PrinsFrank\PdfParser\Document\Generic\Character\LiteralStringEscapeCharacter;
+
+#[CoversClass(LiteralStringEscapeCharacter::class)]
+class LiteralStringEscapeCharacterTest extends TestCase {
+    public function testUnescapeCharactersMultilineExample2(): void {
+        static::assertSame(
+            'These two strings are the same.',
+            LiteralStringEscapeCharacter::unescapeCharacters(
+                <<<EOD
+                These \
+                two strings \
+                are the same.
+                EOD
+            )
+        );
+    }
+
+    public function testUnescapeNewlinesExample3(): void {
+        static::assertSame(
+            <<<EOD
+            This string has an end-of-line at the end of it.
+
+            EOD,
+            LiteralStringEscapeCharacter::unescapeCharacters(
+                <<<EOD
+                This string has an end-of-line at the end of it.
+
+                EOD,
+            ),
+        );
+        static::assertSame(
+            <<<EOD
+            So does this one.
+
+            EOD,
+            LiteralStringEscapeCharacter::unescapeCharacters(
+                <<<EOD
+                So does this one.\n
+                EOD,
+            ),
+        );
+    }
+
+    public function testUnescapeOctalCharactersExample4(): void {
+        static::assertSame(
+            'This string contains ¥two octal charactersÇ.',
+            LiteralStringEscapeCharacter::unescapeCharacters('This string contains \245two octal characters\307.')
+        );
+    }
+
+    public function testUnescapeOctalCharactersExample5(): void {
+        static::assertSame('+', LiteralStringEscapeCharacter::unescapeCharacters('\053'));
+        static::assertSame('+', LiteralStringEscapeCharacter::unescapeCharacters('\53'));
+        static::assertSame("\005" . '3', LiteralStringEscapeCharacter::unescapeCharacters('\0053'));
+    }
+
+    public function testUnescapeCharacters(): void {
+        static::assertSame("\n", LiteralStringEscapeCharacter::unescapeCharacters('\n'));
+        static::assertSame("\r", LiteralStringEscapeCharacter::unescapeCharacters('\r'));
+        static::assertSame("\t", LiteralStringEscapeCharacter::unescapeCharacters('\t'));
+        static::assertSame("\x08", LiteralStringEscapeCharacter::unescapeCharacters('\b'));
+        static::assertSame("\x0C", LiteralStringEscapeCharacter::unescapeCharacters('\f'));
+        static::assertSame("(", LiteralStringEscapeCharacter::unescapeCharacters('\('));
+        static::assertSame(")", LiteralStringEscapeCharacter::unescapeCharacters('\)'));
+        static::assertSame("\\", LiteralStringEscapeCharacter::unescapeCharacters('\\'));
+        static::assertSame("\000", LiteralStringEscapeCharacter::unescapeCharacters('\0'));
+        static::assertSame("\005" . '35', LiteralStringEscapeCharacter::unescapeCharacters('\00535'));
+        static::assertSame("\005" . '353', LiteralStringEscapeCharacter::unescapeCharacters('\005353'));
+    }
+}