Add MutableConfigurable

Hopefully I do not regret this...

src/MutableConfigurable.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Erusev\Parsedown;
+
+/**
+ * Beware that the values of MutableConfigurables are NOT stable. Values SHOULD
+ * be accessed as close to use as possible. Parsing operations sharing the same
+ * State SHOULD NOT be triggered between where values are read and where they
+ * need to be relied upon.
+ */
+interface MutableConfigurable extends Configurable
+{
+    /**
+     * Objects contained in State can generally be regarded as immutable,
+     * however, when mutability is *required* then isolatedCopy (this method)
+     * MUST be implemented to take a reliable copy of the contained state,
+     * which MUST be fully seperable from the current instance. This is
+     * sometimes referred to as a "deep copy".
+     *
+     * The following assumption is made when you implement
+     * MutableConfigurable:
+     *
+     *   A shared, (more or less) globally writable, instantaniously updating
+     *   (at all parsing levels), single copy of a Configurable is intentional
+     *   and desired.
+     *
+     * As such, Parsedown will use the isolatedCopy method to ensure state
+     * isolation between successive parsing calls (which are considered to be
+     * isolated documents).
+     *
+     * You MUST NOT depend on the method `initial` being called when a clean
+     * parsing state is desired, this will not reliably occur; implement
+     * isolatedCopy properly to allow Parsedown to manage this.
+     *
+     * Failing to implement this method properly can result in unintended
+     * side-effects. If possible, you should design your Configurable to be
+     * immutable, which allows a single copy to be shared safely, and mutations
+     * localised to a heirarchy for which the order of operations is easy to
+     * reason about.
+     *
+     * @return static
+     */
+    public function isolatedCopy();
+}

src/Parsedown.php

@@ -31,7 +31,7 @@ final class Parsedown
     {
         $StateBearer = $StateBearer ?: new State;
 
-        $this->State = $StateBearer->state();
+        $this->State = $StateBearer->state()->isolatedCopy();
     }
 
     /**
@@ -42,7 +42,7 @@ final class Parsedown
     {
         list($StateRenderables, $State) = self::lines(
             Lines::fromTextLines($markdown, 0),
-            $this->State
+            $this->State->isolatedCopy()
         );
 
         $Renderables = $State->applyTo($StateRenderables);

src/State.php

@@ -15,7 +15,7 @@ final class State implements StateBearer
     /**
      * @var array<class-string<Configurable>, Configurable>
      */
-    private static $initialCache;
+    private static $initialCache = [];
 
     /**
      * @param Configurable[] $Configurables
@@ -56,6 +56,22 @@ final class State implements StateBearer
      */
     public function get($className)
     {
+        if (
+            ! isset($this->state[$className])
+            && \is_subclass_of($className, MutableConfigurable::class, true)
+        ) {
+            if (! isset(self::$initialCache[$className])) {
+                /** @var T */
+                self::$initialCache[$className] = $className::initial();
+            }
+
+            /**
+             * @var T
+             * @psalm-suppress PossiblyUndefinedMethod
+             */
+            $this->state[$className] = self::$initialCache[$className]->isolatedCopy();
+        }
+
         /** @var T */
         return (
             $this->state[$className]
@@ -93,4 +109,14 @@ final class State implements StateBearer
     {
         return $this;
     }
+
+    public function isolatedCopy(): self
+    {
+        return new self(\array_map(
+            function ($C) {
+                return $C instanceof MutableConfigurable ? $C->isolatedCopy() : $C;
+            },
+            $this->state
+        ));
+    }
 }