Merge branch 'main' into pagenumbering

Author: sanoakr

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/link/ResolvedLinkUrlProperty.kt

@@ -0,0 +1,43 @@
+package com.quarkdown.core.ast.attributes.link
+
+import com.quarkdown.core.ast.base.LinkNode
+import com.quarkdown.core.context.Context
+import com.quarkdown.core.context.MutableContext
+import com.quarkdown.core.property.Property
+
+/**
+ * [Property], assigned to each image link, that points to a local relative URL (path) that is different from the original.
+ * For instance, an image may have a link to `images/picture.png`,
+ * but if it's loaded from an included document with a different base path, it may be resolved to, for example, `../images/picture.png`.
+ * @see com.quarkdown.core.ast.base.inline.Link
+ * @see com.quarkdown.core.context.hooks.LinkUrlResolverHook for the storing stage
+ */
+data class ResolvedLinkUrlProperty(
+    override val value: String,
+) : Property<String> {
+    companion object : Property.Key<String>
+
+    override val key = ResolvedLinkUrlProperty
+}
+
+/**
+ * @param context context where resolution data is stored
+ * @return the resolved URL of this node within the document handled by [context],
+ * or the regular URL if a resolved one is not registered
+ */
+fun LinkNode.getResolvedUrl(context: Context): String =
+    context.attributes.of(this)[ResolvedLinkUrlProperty]
+        ?: this.url
+
+/**
+ * Registers the resolved path of this node within the document handled by [context].
+ * @param context context where resolution data is stored
+ * @param resolvedUrl resolved URL to set
+ * @see com.quarkdown.core.context.hooks.LinkUrlResolverHook
+ */
+fun LinkNode.setResolvedUrl(
+    context: MutableContext,
+    resolvedUrl: String,
+) {
+    context.attributes.of(this) += ResolvedLinkUrlProperty(resolvedUrl)
+}

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/LinkNode.kt

@@ -2,6 +2,7 @@ package com.quarkdown.core.ast.base
 
 import com.quarkdown.core.ast.InlineContent
 import com.quarkdown.core.ast.Node
+import com.quarkdown.core.context.file.FileSystem
 
 /**
  * A general link node.
@@ -23,4 +24,10 @@ interface LinkNode : Node {
      * Optional title.
      */
     val title: String?
+
+    /**
+     * Optional file system where this link is defined, used for resolving relative paths.
+     * @see com.quarkdown.core.context.hooks.LinkUrlResolverHook
+     */
+    val fileSystem: FileSystem?
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/block/LinkDefinition.kt

@@ -3,18 +3,21 @@ package com.quarkdown.core.ast.base.block
 import com.quarkdown.core.ast.InlineContent
 import com.quarkdown.core.ast.base.LinkNode
 import com.quarkdown.core.ast.base.TextNode
+import com.quarkdown.core.context.file.FileSystem
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
  * Creation of a referenceable link definition.
  * @param label inline content of the displayed label
  * @param url URL this link points to
  * @param title optional title
+ * @param fileSystem optional file system this link is relative to
  */
 class LinkDefinition(
     override val label: InlineContent,
     override val url: String,
     override val title: String?,
+    override val fileSystem: FileSystem? = null,
 ) : LinkNode,
     TextNode {
     override fun <T> accept(visitor: NodeVisitor<T>) = visitor.visit(this)

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/inline/Link.kt

@@ -5,18 +5,21 @@ import com.quarkdown.core.ast.Node
 import com.quarkdown.core.ast.base.LinkNode
 import com.quarkdown.core.ast.base.TextNode
 import com.quarkdown.core.ast.base.block.LinkDefinition
+import com.quarkdown.core.context.file.FileSystem
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
  * A link.
  * @param label inline content of the displayed label
  * @param url URL this link points to
  * @param title optional title
+ * @param fileSystem optional file system where this link is defined, used for resolving relative paths
  */
 class Link(
     override val label: InlineContent,
     override val url: String,
     override val title: String?,
+    override val fileSystem: FileSystem? = null,
 ) : LinkNode,
     TextNode {
     override fun <T> accept(visitor: NodeVisitor<T>) = visitor.visit(this)

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/dsl/InlineAstBuilder.kt

@@ -11,6 +11,7 @@ import com.quarkdown.core.ast.base.inline.Text
 import com.quarkdown.core.ast.quarkdown.inline.InlineCollapse
 import com.quarkdown.core.ast.quarkdown.inline.TextTransform
 import com.quarkdown.core.ast.quarkdown.inline.TextTransformData
+import com.quarkdown.core.context.file.SimpleFileSystem
 import com.quarkdown.core.document.size.Size
 
 /**
@@ -64,7 +65,12 @@ class InlineAstBuilder : AstBuilder() {
         height: Size? = null,
         referenceId: String? = null,
         label: InlineAstBuilder.() -> Unit = {},
-    ) = +Image(Link(buildInline(label), url, title), width, height, referenceId)
+    ) = +Image(
+        Link(buildInline(label), url, title, fileSystem = SimpleFileSystem()),
+        width,
+        height,
+        referenceId,
+    )
 
     /**
      * @see InlineCollapse

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

@@ -1,6 +1,7 @@
 package com.quarkdown.core.context
 
 import com.quarkdown.core.ast.attributes.AstAttributes
+import com.quarkdown.core.ast.attributes.link.getResolvedUrl
 import com.quarkdown.core.ast.base.LinkNode
 import com.quarkdown.core.ast.base.inline.Link
 import com.quarkdown.core.ast.base.inline.ReferenceLink
@@ -74,7 +75,7 @@ open class BaseContext(
     override fun resolve(reference: ReferenceLink): LinkNode? =
         attributes.linkDefinitions
             .firstOrNull { it.label.toPlainText() == reference.reference.toPlainText() }
-            ?.let { Link(reference.label, it.url, it.title) }
+            ?.let { Link(reference.label, it.getResolvedUrl(this), it.title, it.fileSystem) }
             ?.also { link ->
                 reference.onResolve.forEach { action -> action(link) }
             }
@@ -105,5 +106,6 @@ open class BaseContext(
             ?: throw LocalizationKeyNotFoundException(tableName, locale, key)
     }
 
-    override fun fork(subdocument: Subdocument): ScopeContext = ScopeContext(parent = this, subdocument)
+    override fun fork(subdocument: Subdocument): ScopeContext =
+        throw UnsupportedOperationException("Forking is not supported in BaseContext")
 }

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

@@ -0,0 +1,28 @@
+package com.quarkdown.core.context
+
+/**
+ * A [Context] that has a parent context, forming a scope tree.
+ * This context can access its parent's properties and inherit them.
+ * @param C type of the parent context
+ */
+interface ChildContext<C : Context> : Context {
+    /**
+     * The parent context of this context in the scope tree.
+     */
+    val parent: C
+
+    /**
+     * @param predicate condition to match
+     * @return the last context (upwards, towards the root, starting from this context) that matches the [predicate],
+     *         or `null` if no parent in the scope tree matches the given condition
+     */
+    fun lastParentOrNull(predicate: (Context) -> Boolean): Context? =
+        when {
+            // This is the last context to match the condition.
+            predicate(this) && !predicate(parent) -> this
+            // The root context matches the condition.
+            parent !is ChildContext<*> && predicate(parent) -> parent
+            // Scan the parent context.
+            else -> (parent as? ChildContext<*>)?.lastParentOrNull(predicate)
+        }
+}

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

@@ -10,6 +10,7 @@ import com.quarkdown.core.function.call.FunctionCall
 import com.quarkdown.core.function.library.Library
 import com.quarkdown.core.function.library.LibraryRegistrant
 import com.quarkdown.core.graph.VisitableOnceGraph
+import com.quarkdown.core.localization.MutableLocalizationTables
 import com.quarkdown.core.media.storage.MutableMediaStorage
 
 /**
@@ -33,7 +34,7 @@ open class MutableContext(
 
     override val loadableLibraries: MutableSet<Library> = (super.loadableLibraries + loadableLibraries).toMutableSet()
 
-    override val localizationTables = super.localizationTables.toMutableMap()
+    override val localizationTables: MutableLocalizationTables = super.localizationTables.toMutableMap()
 
     override val mediaStorage: MutableMediaStorage
         get() = super.mediaStorage as MutableMediaStorage
@@ -71,6 +72,8 @@ open class MutableContext(
             it.onComplete = { attributes.functionCalls.remove(call) }
         }
 
+    override fun fork(subdocument: Subdocument): ScopeContext = ScopeContext(parent = this, subdocument)
+
     /**
      * Loads a loadable library by name and registers it in the context.
      * After a successful load, the library is removed from [loadableLibraries] and added to [libraries],

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

@@ -1,92 +1,39 @@
 package com.quarkdown.core.context
 
-import com.quarkdown.core.ast.attributes.MutableAstAttributes
-import com.quarkdown.core.ast.quarkdown.FunctionCallNode
-import com.quarkdown.core.document.DocumentInfo
 import com.quarkdown.core.document.sub.Subdocument
 import com.quarkdown.core.function.Function
-import com.quarkdown.core.function.library.Library
-import com.quarkdown.core.graph.VisitableOnceGraph
-import com.quarkdown.core.graph.visitableOnce
-import com.quarkdown.core.media.storage.MutableMediaStorage
 import com.quarkdown.core.pipeline.Pipeline
 
 /**
  * A context that is the result of a fork from an original parent [Context].
- * Several properties are inherited from it.
+ * 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
  */
-class ScopeContext(
-    val 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
 
-    override var documentInfo: DocumentInfo
-        get() = parent.documentInfo
-        set(value) {
-            (parent as? MutableContext)?.documentInfo = value
-        }
-
-    override val options: MutableContextOptions
-        get() = parent.options as? MutableContextOptions ?: MutableContextOptions()
-
-    override val attributes: MutableAstAttributes
-        get() = parent.attributes as? MutableAstAttributes ?: parent.attributes.toMutable()
-
-    override val loadableLibraries: MutableSet<Library>
-        get() = (parent as? MutableContext)?.loadableLibraries ?: super.loadableLibraries
-
-    override val localizationTables
-        get() = (parent as? MutableContext)?.localizationTables ?: parent.localizationTables.toMutableMap()
-
-    override val mediaStorage: MutableMediaStorage
-        get() = parent.mediaStorage as? MutableMediaStorage ?: MutableMediaStorage(options)
-
-    override var subdocumentGraph: VisitableOnceGraph<Subdocument>
-        get() = parent.subdocumentGraph as? VisitableOnceGraph ?: parent.subdocumentGraph.visitableOnce
-        set(value) {
-            (parent as? MutableContext)?.subdocumentGraph = value
-        }
+    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)
-
-    /**
-     * Enqueues a function call to the [parent]'s queue if it is a [MutableContext],
-     * or to this context otherwise.
-     * This lets the registration go up the context tree so that it can be expanded
-     * from the root context in the next stage of the pipeline.
-     * @param functionCall function call to register
-     * @see MutableContext.register
-     */
-    override fun register(functionCall: FunctionCallNode) {
-        (parent as? MutableContext)?.register(functionCall)
-            ?: super.register(functionCall)
-    }
-
-    /**
-     * @param predicate condition to match
-     * @return the last context (upwards, towards the root, starting from this context) that matches the [predicate],
-     *         or `null` if no parent in the scope tree matches the given condition
-     */
-    fun lastParentOrNull(predicate: (Context) -> Boolean): Context? =
-        when {
-            // This is the last context to match the condition.
-            predicate(this) && !predicate(parent) -> this
-            // The root context matches the condition.
-            parent !is ScopeContext && predicate(parent) -> parent
-            // Scan the parent context.
-            else -> (parent as? ScopeContext)?.lastParentOrNull(predicate)
-        }
 }

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

@@ -0,0 +1,32 @@
+package com.quarkdown.core.context
+
+import com.quarkdown.core.context.file.FileSystem
+import com.quarkdown.core.function.Function
+
+/**
+ * A context that shares all of its properties with its parent [MutableContext].
+ * This is useful when a context needs to be forked, for example to update its [fileSystem], but still its state mutably.
+ * @param parent context this shared context was forked from
+ * @param fileSystem file system to use in this context
+ */
+open class SharedContext(
+    override val parent: MutableContext,
+    override val fileSystem: FileSystem = parent.fileSystem,
+) : MutableContext(
+        flavor = parent.flavor,
+        libraries = emptySet(),
+        subdocument = parent.subdocument,
+    ),
+    ChildContext<MutableContext> {
+    override val attachedPipeline by parent::attachedPipeline
+    override var documentInfo by parent::documentInfo
+    override val libraries by parent::libraries
+    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
+
+    override fun getFunctionByName(name: String): Function<*>? = parent.getFunctionByName(name)
+}