From 044ebd68c985f141771867602d165368552ce0bb Mon Sep 17 00:00:00 2001
From: Vasil Rangelov <boen.robot@gmail.com>
Date: Sun, 4 Nov 2012 23:04:19 +0200
Subject: [PATCH] Added escape sequences that allow "literal" inline tags in
 descriptions.

---
 .../Reflection/DocBlock/LongDescription.php   | 16 +++-
 .../DocBlock/LongDescriptionTest.php          | 88 ++++++++++++++++---
 2 files changed, 93 insertions(+), 11 deletions(-)

diff --git a/src/phpDocumentor/Reflection/DocBlock/LongDescription.php b/src/phpDocumentor/Reflection/DocBlock/LongDescription.php
index 330cfab..5235d04 100644
--- a/src/phpDocumentor/Reflection/DocBlock/LongDescription.php
+++ b/src/phpDocumentor/Reflection/DocBlock/LongDescription.php
@@ -71,11 +71,14 @@ class LongDescription implements \Reflector
                             # Match nested inline tags.
                             # Because we did not catch the tag delimiters
                             # earlier, we must be explicit with them here.
+                            # Notice that this also matches "{}", as a way to
+                            # later introduce it as an escape sequence.
                             \{(?1)?\}
                             |
                             # "{@}" is not a valid inline tag. This ensures that
                             # having it occur inside an inline tag does not trip
-                            # us up.
+                            # us up. While this is required in any event, notice
+                            # that this is also later an escape sequence.
                             \{\@\}
                             |
                             # If we are not dealing with a nested inline tag,
@@ -98,6 +101,17 @@ class LongDescription implements \Reflector
                     $this->parsedContents[$i]
                 );
             }
+            
+            //In order to allow "literal" inline tags, the otherwise invalid
+            //sequence "{@}" is changed to "@", and "{}" is changed to "}".
+            //See unit tests for examples.
+            for ($i=0, $l = count($this->parsedContents); $i<$l; $i += 2) {
+                $this->parsedContents[$i] = str_replace(
+                    array('{@}', '{}'),
+                    array('@', '}'),
+                    $this->parsedContents[$i]
+                );
+            }
         }
         return $this->parsedContents;
     }
diff --git a/tests/phpDocumentor/Reflection/DocBlock/LongDescriptionTest.php b/tests/phpDocumentor/Reflection/DocBlock/LongDescriptionTest.php
index f0676b3..5fe23c6 100644
--- a/tests/phpDocumentor/Reflection/DocBlock/LongDescriptionTest.php
+++ b/tests/phpDocumentor/Reflection/DocBlock/LongDescriptionTest.php
@@ -103,12 +103,21 @@ LONGDESC;
             $parsedContents[1]
         );
         $this->assertSame('.', $parsedContents[2]);
+
+        $parsedDescription = $parsedContents[1]->getParsedDescription();
+        $this->assertCount(3, $parsedDescription);
+        $this->assertSame("inline tag with\n", $parsedDescription[0]);
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag\LinkTag',
+            $parsedDescription[1]
+        );
+        $this->assertSame(' in it', $parsedDescription[2]);
     }
-    
-    public function testEmptyInlineTag()
+
+    public function testLiteralOpeningDelimiter()
     {
         $fixture = <<<LONGDESC
-This is text for a description with an empty inline tag - {@}.
+This is text for a description containing { that is literal.
 LONGDESC;
         $object = new LongDescription($fixture);
         $this->assertSame($fixture, $object->getContents());
@@ -118,11 +127,11 @@ LONGDESC;
         $this->assertSame($fixture, $parsedContents[0]);
     }
 
-    public function testNestedEmptyInlineTag()
+    public function testNestedLiteralOpeningDelimiter()
     {
         $fixture = <<<LONGDESC
-This is text for a description with an {@internal inline tag with an empty
-inline tag - {@} in it}.
+This is text for a description containing {@internal inline tag that has { that
+is literal}.
 LONGDESC;
         $object = new LongDescription($fixture);
         $this->assertSame($fixture, $object->getContents());
@@ -130,7 +139,7 @@ LONGDESC;
         $parsedContents = $object->getParsedContents();
         $this->assertCount(3, $parsedContents);
         $this->assertSame(
-            'This is text for a description with an ',
+            'This is text for a description containing ',
             $parsedContents[0]
         );
         $this->assertInstanceOf(
@@ -138,9 +147,15 @@ LONGDESC;
             $parsedContents[1]
         );
         $this->assertSame('.', $parsedContents[2]);
+
+        $this->assertSame(
+            array('inline tag that has { that
+is literal'),
+            $parsedContents[1]->getParsedDescription()
+        );
     }
 
-    public function testInlineTagDelimiters()
+    public function testLiteralClosingDelimiter()
     {
         $fixture = <<<LONGDESC
 This is text for a description with {} that is not a tag.
@@ -150,10 +165,13 @@ LONGDESC;
 
         $parsedContents = $object->getParsedContents();
         $this->assertCount(1, $parsedContents);
-        $this->assertSame($fixture, $parsedContents[0]);
+        $this->assertSame(
+            'This is text for a description with } that is not a tag.',
+            $parsedContents[0]
+        );
     }
 
-    public function testNestedInlineTagDelimiters()
+    public function testNestedLiteralClosingDelimiter()
     {
         $fixture = <<<LONGDESC
 This is text for a description with {@internal inline tag with {} that is not an
@@ -173,5 +191,55 @@ LONGDESC;
             $parsedContents[1]
         );
         $this->assertSame('.', $parsedContents[2]);
+
+        $this->assertSame(
+            array('inline tag with } that is not an
+inline tag'),
+            $parsedContents[1]->getParsedDescription()
+        );
+    }
+    
+    public function testInlineTagEscapingSequence()
+    {
+        $fixture = <<<LONGDESC
+This is text for a description with literal {{@}link}.
+LONGDESC;
+        $object = new LongDescription($fixture);
+        $this->assertSame($fixture, $object->getContents());
+
+        $parsedContents = $object->getParsedContents();
+        $this->assertCount(1, $parsedContents);
+        $this->assertSame(
+            'This is text for a description with literal {@link}.',
+            $parsedContents[0]
+        );
+    }
+
+    public function testNestedInlineTagEscapingSequence()
+    {
+        $fixture = <<<LONGDESC
+This is text for a description with an {@internal inline tag with literal
+{{@}link{} in it}.
+LONGDESC;
+        $object = new LongDescription($fixture);
+        $this->assertSame($fixture, $object->getContents());
+
+        $parsedContents = $object->getParsedContents();
+        $this->assertCount(3, $parsedContents);
+        $this->assertSame(
+            'This is text for a description with an ',
+            $parsedContents[0]
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $parsedContents[1]
+        );
+        $this->assertSame('.', $parsedContents[2]);
+
+        $this->assertSame(
+            array('inline tag with literal
+{@link} in it'),
+            $parsedContents[1]->getParsedDescription()
+        );
     }
 }
\ No newline at end of file