Merge pull request #278 from iamgio/feat/subdocuments-own-info

feat: let subdocuments edit their own document metadata

Author: iamgio

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/BaseContext.kt

@@ -106,6 +106,5 @@ open class BaseContext(
             ?: throw LocalizationKeyNotFoundException(tableName, locale, key)
     }
 
-    override fun fork(subdocument: Subdocument): ScopeContext =
-        throw UnsupportedOperationException("Forking is not supported in BaseContext")
+    override fun fork(): ScopeContext = throw UnsupportedOperationException("Forking is not supported in BaseContext")
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/Context.kt

@@ -158,10 +158,9 @@ interface Context {
     ): String
 
     /**
-     * @param subdocument optional subdocument to fork the context for
-     * @return a new scope context, forked from this context, with the same base inherited properties
+     * @return a new scope context, forked from this context, that shares several base properties
      */
-    fun fork(subdocument: Subdocument = this.subdocument): ScopeContext
+    fun fork(): ScopeContext
 }
 
 /**

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/MutableContext.kt

@@ -72,7 +72,7 @@ open class MutableContext(
             it.onComplete = { attributes.functionCalls.remove(call) }
         }
 
-    override fun fork(subdocument: Subdocument): ScopeContext = ScopeContext(parent = this, subdocument)
+    override fun fork(): ScopeContext = ScopeContext(parent = this)
 
     /**
      * Loads a loadable library by name and registers it in the context.

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/ScopeContext.kt

@@ -1,39 +1,18 @@
 package com.quarkdown.core.context
 
-import com.quarkdown.core.document.sub.Subdocument
-import com.quarkdown.core.function.Function
-import com.quarkdown.core.pipeline.Pipeline
-
 /**
  * A context that is the result of a fork from an original parent [Context].
  * All properties are inherited from it, but not all, such as libraries, are shared mutably.
  * @param parent context this scope was forked from
  * @param subdocument the subdocument this context is processing
+ * @see SubdocumentContext to see what's inherited from the parent context
  */
 open class ScopeContext(
-    override val parent: MutableContext,
-    subdocument: Subdocument = parent.subdocument,
-) : MutableContext(
-        flavor = parent.flavor,
-        libraries = emptySet(),
-        subdocument = subdocument,
-    ),
-    ChildContext<MutableContext> {
-    override val attachedPipeline: Pipeline?
-        get() = super.attachedPipeline ?: parent.attachedPipeline
-
+    parent: MutableContext,
+) : SubdocumentContext(
+        parent = parent,
+        subdocument = parent.subdocument,
+    ) {
+    // A scope context shares the parent's document info.
     override var documentInfo by parent::documentInfo
-    override val options by parent::options
-    override val attributes by parent::attributes
-    override val loadableLibraries by parent::loadableLibraries
-    override val localizationTables by parent::localizationTables
-    override val mediaStorage by parent::mediaStorage
-    override var subdocumentGraph by parent::subdocumentGraph
-
-    /**
-     * If no matching function is found among this [ScopeContext]'s own [libraries],
-     * [parent]'s libraries are scanned.
-     * @see Context.getFunctionByName
-     */
-    override fun getFunctionByName(name: String): Function<*>? = super.getFunctionByName(name) ?: parent.getFunctionByName(name)
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/context/SubdocumentContext.kt

@@ -0,0 +1,48 @@
+package com.quarkdown.core.context
+
+import com.quarkdown.core.document.DocumentInfo
+import com.quarkdown.core.document.sub.Subdocument
+import com.quarkdown.core.function.Function
+import com.quarkdown.core.pipeline.Pipeline
+
+/**
+ * A context that is the result of a fork from an original parent [Context].
+ * All properties are inherited from it, but not all, such as libraries, are shared mutably.
+ *
+ * This is mainly designed to be forked for subdocuments, where a new context is needed to process them.
+ * Each subdocument context shares most properties with its parent context, but maintains its own state for certain aspects like document info.
+ *
+ * [ScopeContext] inherits from this class, and shares the parent's document info instead.
+ *
+ * @param parent context this scope was forked from
+ * @param subdocument the subdocument this context is processing
+ */
+open class SubdocumentContext(
+    override val parent: MutableContext,
+    subdocument: Subdocument,
+) : MutableContext(
+        flavor = parent.flavor,
+        libraries = emptySet(),
+        subdocument = subdocument,
+    ),
+    ChildContext<MutableContext> {
+    override val attachedPipeline: Pipeline?
+        get() = super.attachedPipeline ?: parent.attachedPipeline
+
+    // A subdocument inherits the parent's document info, but changes to it are local to this subdocument.
+    override var documentInfo: DocumentInfo = parent.documentInfo
+
+    override val options by parent::options
+    override val attributes by parent::attributes
+    override val loadableLibraries by parent::loadableLibraries
+    override val localizationTables by parent::localizationTables
+    override val mediaStorage by parent::mediaStorage
+    override var subdocumentGraph by parent::subdocumentGraph
+
+    /**
+     * If no matching function is found among this [SubdocumentContext]'s own [libraries],
+     * [parent]'s libraries are scanned.
+     * @see Context.getFunctionByName
+     */
+    override fun getFunctionByName(name: String): Function<*>? = super.getFunctionByName(name) ?: parent.getFunctionByName(name)
+}

quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/stages/ResourceGenerationStage.kt

@@ -1,6 +1,7 @@
 package com.quarkdown.core.pipeline.stages
 
 import com.quarkdown.core.context.MutableContext
+import com.quarkdown.core.context.SubdocumentContext
 import com.quarkdown.core.document.sub.Subdocument
 import com.quarkdown.core.pipeline.Pipeline
 import com.quarkdown.core.pipeline.PipelineHooks
@@ -52,7 +53,7 @@ class ResourceGenerationStage(
             .asSequence()
             .filterIsInstance<Subdocument.Resource>()
             .flatMap { nextSubdocument ->
-                val subContext = context.fork(nextSubdocument)
+                val subContext = SubdocumentContext(parent = context, subdocument = nextSubdocument)
                 pipeline.copy(subContext).executeUnwrapped(nextSubdocument.content)
             }.toSet()
 }

quarkdown-test/src/test/kotlin/com/quarkdown/test/DocumentTest.kt

@@ -167,4 +167,18 @@ class DocumentTest {
             )
         }
     }
+
+    @Test
+    fun `document info modification from scope`() {
+        execute(
+            """
+            .docname {Original Name}
+            
+            .if {yes}
+                .docname {Modified Name}
+            """.trimIndent(),
+        ) {
+            assertEquals("Modified Name", documentInfo.name)
+        }
+    }
 }

quarkdown-test/src/test/kotlin/com/quarkdown/test/EcosystemTest.kt

@@ -38,6 +38,18 @@ class EcosystemTest {
         }
     }
 
+    @Test
+    fun `modify document info from included source`() {
+        execute(
+            """
+            .include {include/document-info-modification.md}
+            """.trimIndent(),
+        ) {
+            assertEquals("Modified Title", documentInfo.name)
+            assertEquals("it", documentInfo.locale?.shortTag)
+        }
+    }
+
     @Test
     fun `include function from source`() {
         execute(

quarkdown-test/src/test/kotlin/com/quarkdown/test/SubdocumentTest.kt

@@ -36,7 +36,9 @@ class SubdocumentTest {
     private val simpleSubdoc = subdoc("subdoc1", content = "Content")
     private val referenceToParentSubdoc = subdoc("subdoc2", content = ".$NON_EXISTENT_FUNCTION")
     private val definitionSubdoc = subdoc("subdoc3", content = ".function {$NON_EXISTENT_FUNCTION}\n\thello")
-    private val thirdPartySubdoc = subdoc("subdoc3", content = ".mermaid\n\tgraph TD\n\t\tA-->B")
+    private val thirdPartySubdoc = subdoc("subdoc4", content = ".mermaid\n\tgraph TD\n\t\tA-->B")
+    private val echoDocumentNameSubdoc = subdoc("subdoc5", content = ".docname")
+    private val modifyAndEchoDocumentNameSubdoc = subdoc("subdoc6", content = ".docname {Changed name}\n\n.docname")
 
     private fun getResource(
         group: OutputResource?,
@@ -125,6 +127,36 @@ class SubdocumentTest {
         ) {}
     }
 
+    @Test
+    fun `subdocument inherits parent's document info`() {
+        execute(
+            ".docname {My doc}",
+            subdocumentGraph = { it.addVertex(echoDocumentNameSubdoc).addEdge(Subdocument.Root, echoDocumentNameSubdoc) },
+            outputResourceHook = { group ->
+                val subdocResource = getResource(group, echoDocumentNameSubdoc, this)
+                assertEquals("My doc", group?.name)
+                assertEquals("My doc", documentInfo.name)
+                assertContains(subdocResource.content, "<title>My doc</title>")
+            },
+        ) {}
+    }
+
+    @Test
+    fun `subdocument should not share document info modifications with parent`() {
+        execute(
+            ".docname {Parent doc}",
+            subdocumentGraph = { it.addVertex(modifyAndEchoDocumentNameSubdoc).addEdge(Subdocument.Root, modifyAndEchoDocumentNameSubdoc) },
+            outputResourceHook = { group ->
+                val mainResource = getResource(group, Subdocument.Root, this)
+                val subdocResource = getResource(group, modifyAndEchoDocumentNameSubdoc, this)
+                assertEquals("Parent doc", group?.name)
+                assertEquals("Parent doc", documentInfo.name)
+                assertContains(mainResource.content, "<title>Parent doc</title>")
+                assertContains(subdocResource.content, "<title>Changed name</title>")
+            },
+        ) {}
+    }
+
     @Test
     fun `simple subdocument from file`() {
         arrayOf(

quarkdown-test/src/test/resources/data/include/document-info-modification.md

@@ -0,0 +1,2 @@
+.docname {Modified Title}
+.doclang {it}