Merge pull request #306 from thephpleague/develop

0.17

.styleci.yml

@@ -7,6 +7,7 @@ enabled:
 
 disabled:
   - concat_without_spaces
+  - no_trailing_comma_in_list_call
   - phpdoc_summary
   - post_increment
   - self_accessor

.travis.yml

@@ -3,8 +3,6 @@ language: php
 dist: trusty
 
 php:
-  - 5.4
-  - 5.5
   - 5.6
   - 7.0
   - 7.1
@@ -18,7 +16,7 @@ cache:
 
 matrix:
   include:
-    - php: 5.4
+    - php: 5.6
       env: 'COMPOSER_FLAGS="--prefer-stable --prefer-lowest"'
   fast_finish: true
 

CHANGELOG.md

@@ -4,14 +4,48 @@ Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) princip
 
 ## [Unreleased][unreleased]
 
+## [0.17.0] - 2017-12-30
+
+This release contains several breaking changes and a minimum PHP version bump - see <UPGRADE.md> for more details.
+
+### Added
+
+ - Added new `max_nesting_level` setting (#243)
+ - Added minor performance optimizations to `Cursor`
+
 ### Changed
 
- - References to `InlineContainer` changed to new `InlineContainerInterface` interface
+ - Minimum PHP version is now 5.6.5.
+ - All full and partial regular expressions in `RegexHelper` are now defined as constants instead of being built on-the-fly.
+ - `Cursor::saveState()` now returns an `array` instead of a `CursorState` object.
+ - `Cursor::restoreState()` now accepts an `array` parameter instead of a `CursorState` object.
+ - Saving/restoring the Cursor state no longer tracks things that don't change (like the text content).
+ - `RegexHelper` is now `final`.
+ - References to `InlineContainer` changed to new `InlineContainerInterface` interface.
+ - `MiscExtension::addInlineParser()` and `MiscExtension::addBlockRenderer()` now return `$this` instead of nothing.
+
+### Fixed
+ - Fixed `Reference::normalizeReference()` not properly collapsing whitespace to a single space
 
 ### Deprecated
 
+ - `RegexHelper::getInstance()` and all instance (non-static) methods have been deprecated.
  - The `InlineContainer` interface has been deprecated. Use `InlineContainerInterface` instead.
 
+### Removed
+
+ - Removed support for PHP 5.4 and 5.5.
+ - Removed `CursorState` class
+ - Removed all previous deprecations:
+   - `Cursor::getFirstNonSpacePosition()`
+   - `Cursor::getFirstNonSpaceCharacter()`
+   - `Cursor::advanceWhileMatches()`
+   - `Cursor::advanceToFirstNonSpace()`
+   - `ElementRendererInterface::escape()`
+   - `HtmlRenderer::escape()`
+   - `RegexHelper::REGEX_UNICODE_WHITESPACE`
+   - `RegexHelper::getLinkDestinationRegex()`
+
 ## [0.16.0] - 2017-10-30
 
 This release contains breaking changes, several performance improvements, and two deprecations:
@@ -575,7 +609,8 @@ An unused constant and static method were deprecated and will be removed in a fu
 ### Added
  - Initial commit (compatible with jgm/stmd:spec.txt @ 0275f34)
 
-[unreleased]: https://github.com/thephpleague/commonmark/compare/0.16.0...HEAD
+[unreleased]: https://github.com/thephpleague/commonmark/compare/0.17.0...HEAD
+[0.17.0]: https://github.com/thephpleague/commonmark/compare/0.16.0...0.17.0
 [0.16.0]: https://github.com/thephpleague/commonmark/compare/0.15.7...0.16.0
 [0.15.7]: https://github.com/thephpleague/commonmark/compare/0.15.6...0.15.7
 [0.15.6]: https://github.com/thephpleague/commonmark/compare/0.15.5...0.15.6

UPGRADE.md

@@ -1,8 +1,73 @@
 # Upgrade Instructions
 
-## 0.17.0 (unreleased)
+## 0.17.0
 
-`InlineContainer` was renamed to `InlineContainerInterface`.
+## Minimum PHP version
+
+The minimum PHP version has been increased to 5.6.5.  Users on PHP 5.4 and 5.5 can still use previous versions of this library but will not receive future improvements or bug fixes.
+
+## Removal of deprecated features
+
+Pretty much everything marked as `@deprecated` in 0.16.0 has been removed.
+
+## `RegexHelper`
+
+We're now taking advantage of PHP 5.6's constant expression feature. This removes the need for `RegexHelper` to be a singleton where complex regular expressions are built and referenced using instance methods.  **All regexes are now available as class constants.**
+
+For example, instead of doing this:
+
+```php
+preg_match('/' . RegexHelper::getInstance()->getPartialRegex(RegexHelper::OPENTAG) . '/', $html);
+```
+
+You can now do this:
+
+```php
+preg_match('/' . RegexHelper::PARTIAL_OPENTAG . '/', $html);
+```
+
+(Basically, remove that function call and prefix the constant name with `PARTIAL_`).
+
+Other instance functions like `getLinkTitleRegex()` which returned a regular expression have also been deprecated in favor of pre-defined constants like `PARTIAL_LINK_TITLE`.
+
+The now-deprecated functionality still exists in 0.17.0 **but will be removed in the next major release.**
+
+To summarize:
+
+ - All `REGEX_` constants are fully-formed regexes. Most are unchanged.
+ - All `PARTIAL_` constants need to be wrapped with a `/` on each side before use.
+ - All instance methods are deprecated - use a constant instead.
+
+`RegexHelper` is also `final` now - it only contains constants and static methods and was never intended to be extended.
+
+## Cursor state
+
+`Cursor::saveState()` and `Cursor::restoreState()` provide the ability to rollback the state of a `Cursor`. For example:
+
+```php
+$oldState = $cursor->saveState();
+
+// Made-up example of trying to parse something using calls
+$cursor->advanceToNextNonSpaceOrTab();
+$cursor->match('/foo(bar)?/');
+$cursor->advanceToNextNonSpaceOrTab();
+
+if ($someConditionThatWeDidntExpect) {
+    // Roll back and abort
+    $cursor->restoreState($oldState);
+    return;
+}
+```
+
+This useful feature encapsulated the internal, `private` state of the `Cursor` inside of a `CursorState` object with public methods.  **This was a design mistake** as it meant that any changes to the interal structure of a `Cursor` meant causing BC-breaks on the `CursorState`.
+
+`CursorState` was also never intended for any other usage besides saving/restoring.
+
+For those reasons, we've removed the `CursorState` class entirely and now store the state using an array. **Do not depend on the contents or structure of the array for any reason as it may change in any release without warning!**  If you really need to reference information about the prior state of the cursor, either `clone` it or grab the info you need before manipulating it.
+
+## `InlineContainer` interface
+
+The `InlineContainer` interface was renamed to `InlineContainerInterface`.  The old one still exists as a deprecated interface and will be removed in the next major release.
 
 ## 0.16.0
 

composer.json

@@ -17,7 +17,7 @@
         "colinodell/commonmark-php": "*"
     },
     "require": {
-        "php": ">=5.4.8",
+        "php": ">=5.6.5",
         "ext-mbstring": "*"
     },
     "require-dev": {
@@ -26,8 +26,8 @@
         "commonmark/commonmark.js": "0.28",
         "michelf/php-markdown": "~1.4",
         "mikehaertl/php-shellcommand": "~1.2.0",
-        "phpunit/phpunit": "^4.8.35|~5.7",
-        "symfony/finder": "~2.3|~3.0",
+        "phpunit/phpunit": "~5.7|~6.5",
+        "symfony/finder": "~3.0|~4.0",
         "scrutinizer/ocular": "~1.1"
     },
     "suggest": {
@@ -60,7 +60,7 @@
     "bin": ["bin/commonmark"],
     "extra": {
         "branch-alias": {
-            "dev-master": "0.17-dev"
+            "dev-master": "0.18-dev"
         }
     }
 }

src/Block/Parser/ThematicBreakParser.php

@@ -33,7 +33,7 @@ public function parse(ContextInterface $context, Cursor $cursor)
             return false;
         }
 
-        $match = RegexHelper::matchAt(RegexHelper::getInstance()->getThematicBreakRegex(), $cursor->getLine(), $cursor->getNextNonSpacePosition());
+        $match = RegexHelper::matchAt(RegexHelper::REGEX_THEMATIC_BREAK, $cursor->getLine(), $cursor->getNextNonSpacePosition());
         if ($match === null) {
             return false;
         }

src/Cursor.php

@@ -85,20 +85,6 @@ public function __construct($line)
         $this->lineContainsTabs = preg_match('/\t/', $line) > 0;
     }
 
-    /**
-     * Returns the position of the next character which is not a space (or tab)
-     *
-     * @deprecated Use getNextNonSpacePosition() instead
-     *
-     * @return int
-     */
-    public function getFirstNonSpacePosition()
-    {
-        @trigger_error('Cursor::getFirstNonSpacePosition() will be removed in a future 0.x release.  Use getNextNonSpacePosition() instead. See https://github.com/thephpleague/commonmark/issues/280', E_USER_DEPRECATED);
-
-        return $this->getNextNonSpacePosition();
-    }
-
     /**
      * Returns the position of the next character which is not a space (or tab)
      *
@@ -131,20 +117,6 @@ public function getNextNonSpacePosition()
         return $this->nextNonSpaceCache = $nextNonSpace;
     }
 
-    /**
-     * Returns the next character which isn't a space (or tab)
-     *
-     * @deprecated Use getNextNonSpaceCharacter() instead
-     *
-     * @return string
-     */
-    public function getFirstNonSpaceCharacter()
-    {
-        @trigger_error('Cursor::getFirstNonSpaceCharacter() will be removed in a future 0.x release.  Use getNextNonSpaceCharacter() instead. See https://github.com/thephpleague/commonmark/issues/280', E_USER_DEPRECATED);
-
-        return $this->getNextNonSpaceCharacter();
-    }
-
     /**
      * Returns the next character which isn't a space (or tab)
      *
@@ -309,54 +281,6 @@ public function advanceBySpaceOrTab()
         return false;
     }
 
-    /**
-     * Advances the cursor while the given character is matched
-     *
-     * @param string   $character                  Character to match
-     * @param int|null $maximumCharactersToAdvance Maximum number of characters to advance before giving up
-     *
-     * @return int Number of positions moved (0 if unsuccessful)
-     *
-     * @deprecated Use match() instead
-     */
-    public function advanceWhileMatches($character, $maximumCharactersToAdvance = null)
-    {
-        @trigger_error('Cursor::advanceWhileMatches() will be removed in a future 0.x release.  Use match() instead.', E_USER_DEPRECATED);
-
-        // Calculate how far to advance
-        $start = $this->currentPosition;
-        $newIndex = $start;
-        if ($maximumCharactersToAdvance === null) {
-            $maximumCharactersToAdvance = $this->length;
-        }
-
-        $max = min($start + $maximumCharactersToAdvance, $this->length);
-
-        while ($newIndex < $max && $this->getCharacter($newIndex) === $character) {
-            ++$newIndex;
-        }
-
-        if ($newIndex <= $start) {
-            return 0;
-        }
-
-        $this->advanceBy($newIndex - $start);
-
-        return $this->currentPosition - $this->previousPosition;
-    }
-
-    /**
-     * Parse zero or more space characters, including at most one newline.
-     *
-     * @deprecated Use advanceToNextNonSpaceOrNewline() instead
-     */
-    public function advanceToFirstNonSpace()
-    {
-        @trigger_error('Cursor::advanceToFirstNonSpace() will be removed in a future 0.x release.  Use advanceToNextNonSpaceOrTab() or advanceToNextNonSpaceOrNewline() instead. See https://github.com/thephpleague/commonmark/issues/280', E_USER_DEPRECATED);
-
-        return $this->advanceToNextNonSpaceOrNewline();
-    }
-
     /**
      * Parse zero or more space/tab characters
      *
@@ -460,7 +384,6 @@ public function match($regex)
     {
         $subject = $this->getRemainder();
 
-        $matches = [];
         if (!preg_match($regex, $subject, $matches, PREG_OFFSET_CAPTURE)) {
             return;
         }
@@ -518,7 +441,7 @@ public function restoreState($state)
             $this->nextNonSpaceCache,
             $this->indent,
             $this->column,
-            $this->partiallyConsumedTab
+            $this->partiallyConsumedTab,
           ) = $state;
     }
 

src/DocParser.php

@@ -32,13 +32,19 @@ class DocParser
      */
     private $inlineParserEngine;
 
+    /**
+     * @var int|float
+     */
+    private $maxNestingLevel;
+
     /**
      * @param Environment $environment
      */
     public function __construct(Environment $environment)
     {
         $this->environment = $environment;
         $this->inlineParserEngine = new InlineParserEngine($environment);
+        $this->maxNestingLevel = $environment->getConfig('max_nesting_level', INF);
     }
 
     /**
@@ -83,8 +89,8 @@ public function parse($input)
             $this->incorporateLine($context);
         }
 
-        while ($context->getTip()) {
-            $context->getTip()->finalize($context, count($lines));
+        while ($tip = $context->getTip()) {
+            $tip->finalize($context, count($lines));
         }
 
         $this->processInlines($context, $context->getDocument()->walker());
@@ -142,7 +148,7 @@ private function processDocument(ContextInterface $context)
 
     private function processInlines(ContextInterface $context, NodeWalker $walker)
     {
-        while (($event = $walker->next()) !== null) {
+        while ($event = $walker->next()) {
             if (!$event->isEntering()) {
                 continue;
             }
@@ -197,7 +203,7 @@ private function parseBlocks(ContextInterface $context, Cursor $cursor)
                 }
             }
 
-            if (!$parsed || $context->getContainer()->acceptsLines()) {
+            if (!$parsed || $context->getContainer()->acceptsLines() || $context->getTip()->getDepth() >= $this->maxNestingLevel) {
                 $context->setBlocksParsed(true);
                 break;
             }

src/ElementRendererInterface.php

@@ -30,16 +30,6 @@ interface ElementRendererInterface
      */
     public function getOption($option, $default = null);
 
-    /**
-     * @param string $string
-     * @param bool   $preserveEntities
-     *
-     * @return string
-     *
-     * @deprecated
-     */
-    public function escape($string, $preserveEntities = false);
-
     /**
      * @param AbstractInline[] $inlines
      *

src/Environment.php

@@ -485,6 +485,7 @@ public static function createCommonMarkEnvironment()
             'safe'               => false, // deprecated option
             'html_input'         => self::HTML_INPUT_ALLOW,
             'allow_unsafe_links' => true,
+            'max_nesting_level'  => INF,
         ]);
 
         return $environment;
@@ -533,7 +534,7 @@ private function assertUninitialized($message)
     private function getMiscExtension()
     {
         $lastExtension = end($this->extensions);
-        if ($lastExtension !== false && $lastExtension instanceof MiscExtension) {
+        if ($lastExtension instanceof MiscExtension) {
             return $lastExtension;
         }