Added escape sequences that allow "literal" inline tags in descriptions.

Author: boenrobot

src/phpDocumentor/Reflection/DocBlock/LongDescription.php

@@ -71,11 +71,14 @@ public function getParsedContents()
                             # 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 @@ public function getParsedContents()
                     $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;
     }

tests/phpDocumentor/Reflection/DocBlock/LongDescriptionTest.php

@@ -103,12 +103,21 @@ public function testNestedInlineTagParsing()
             $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,29 +127,35 @@ public function testEmptyInlineTag()
         $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());
 
         $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(
             __NAMESPACE__ . '\Tag',
             $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 @@ public function testInlineTagDelimiters()
 
         $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 @@ public function testNestedInlineTagDelimiters()
             $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()
+        );
     }
 }