Pre-parsing events

docs/1.4/customization/event-dispatcher.md

@@ -67,6 +67,10 @@ Listeners may call any method on the event to get more information about the eve
 
 This library supports the following default events which you can register listeners for:
 
+### `League\CommonMark\Event\DocumentPreParsedEvent`
+
+This event is dispatched just before any processing is done. It can be used to pre-populate reference map of a document before any processing is performed.
+
 ### `League\CommonMark\Event\DocumentParsedEvent`
 
 This event is dispatched once all other processing is done.  This offers extensions the opportunity to inspect and modify the [Abstract Syntax Tree](/1.4/customization/abstract-syntax-tree/) prior to rendering.

src/DocParser.php

@@ -20,6 +20,7 @@
 use League\CommonMark\Block\Element\Paragraph;
 use League\CommonMark\Block\Element\StringContainerInterface;
 use League\CommonMark\Event\DocumentParsedEvent;
+use League\CommonMark\Event\DocumentPreParsedEvent;
 use League\CommonMark\Exception\UnexpectedEncodingException;
 
 final class DocParser implements DocParserInterface
@@ -79,6 +80,9 @@ private function preProcessInput(string $input): array
     public function parse(string $input): Document
     {
         $document = new Document();
+
+        $this->environment->dispatch(new DocumentPreParsedEvent($document));
+
         $context = new Context($document, $this->environment);
 
         $this->assertValidUTF8($input);

src/Event/DocumentPreParsedEvent.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * This file is part of the league/commonmark package.
+ *
+ * (c) Colin O'Dell <colinodell@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace League\CommonMark\Event;
+
+use League\CommonMark\Block\Element\Document;
+
+/**
+ * Event dispatched when the document is about to be parsed
+ */
+final class DocumentPreParsedEvent extends AbstractEvent
+{
+    /** @var Document */
+    private $document;
+
+    /**
+     * @param Document $document
+     */
+    public function __construct(Document $document)
+    {
+        $this->document = $document;
+    }
+
+    /**
+     * @return Document
+     */
+    public function getDocument(): Document
+    {
+        return $this->document;
+    }
+}

tests/unit/Event/DocumentPreParsedEventTest.php

@@ -0,0 +1,45 @@
+<?php
+
+/*
+ * This file is part of the league/commonmark package.
+ *
+ * (c) Colin O'Dell <colinodell@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace League\CommonMark\Tests\Unit\Event;
+
+use League\CommonMark\Block\Element\Document;
+use League\CommonMark\DocParser;
+use League\CommonMark\Environment;
+use League\CommonMark\Event\DocumentPreParsedEvent;
+use PHPUnit\Framework\TestCase;
+
+final class DocumentPreParsedEventTest extends TestCase
+{
+    public function testGetDocument()
+    {
+        $document = new Document();
+
+        $event = new DocumentPreParsedEvent($document);
+
+        $this->assertSame($document, $event->getDocument());
+    }
+
+    public function testEventDispatchedAtCorrectTime()
+    {
+        $wasCalled = false;
+
+        $environment = Environment::createCommonMarkEnvironment();
+        $environment->addEventListener(DocumentPreParsedEvent::class, function (DocumentPreParsedEvent $event) use (&$wasCalled) {
+            $wasCalled = true;
+        });
+
+        $parser = new DocParser($environment);
+        $parser->parse('hello world');
+
+        $this->assertTrue($wasCalled);
+    }
+}