Merge pull request #19 from iamgio/numbered-fix

iamgio · web-flow · commit daa1d56269b2 · 2025-05-23T13:04:57.000+02:00
Fix `.numbered` errors
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/location/LocationLabelProperty.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/location/LocationLabelProperty.kt
@@ -11,7 +11,7 @@ import com.quarkdown.core.property.Property
  * Examples of these nodes are figures and tables. For instance, depending on the document's [NumberingFormat],
  * an element may be labeled as `1.1`, `1.2`, `1.3`, `2.1`, etc.
  * @param value the formatted label
- * @see com.quarkdown.core.context.hooks.LocationAwareLabelStorerHook for the storing stage
+ * @see com.quarkdown.core.context.hooks.location.LocationAwareLabelStorerHook for the storing stage
  */
 data class LocationLabelProperty(
     override val value: String,
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/location/LocationTrackableNode.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/location/LocationTrackableNode.kt
@@ -30,7 +30,7 @@ fun LocationTrackableNode.getLocation(context: Context): SectionLocation? = cont
  * Registers the location of this node within the document handled by [context].
  * @param context context where location data is stored
  * @param location location to set
- * @see com.quarkdown.core.context.hooks.LocationAwarenessHook
+ * @see com.quarkdown.core.context.hooks.location.LocationAwarenessHook
  */
 fun LocationTrackableNode.setLocation(
     context: MutableContext,
@@ -52,7 +52,7 @@ fun LocationTrackableNode.getLocationLabel(context: Context): String? = context.
  * according to [this] node's [NumberingFormat].
  * @param context context where location data is stored
  * @param label formatted location to set
- * @see com.quarkdown.core.context.hooks.LocationAwareLabelStorerHook
+ * @see com.quarkdown.core.context.hooks.location.LocationAwareLabelStorerHook
  */
 fun LocationTrackableNode.setLocationLabel(
     context: MutableContext,
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/location/SectionLocationProperty.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/attributes/location/SectionLocationProperty.kt
@@ -6,7 +6,7 @@ import com.quarkdown.core.property.Property
  * [Property] that is assigned to each node that requests its location to be tracked ([LocationTrackableNode]).
  * It contains the node's location in the document, in terms of section indices.
  * @see SectionLocation
- * @see com.quarkdown.core.context.hooks.LocationAwarenessHook for the storing stage
+ * @see com.quarkdown.core.context.hooks.location.LocationAwarenessHook for the storing stage
  */
 data class SectionLocationProperty(
     override val value: SectionLocation,
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/quarkdown/block/Numbered.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/quarkdown/block/Numbered.kt
@@ -1,5 +1,6 @@
 package com.quarkdown.core.ast.quarkdown.block
 
+import com.quarkdown.core.ast.NestableNode
 import com.quarkdown.core.ast.Node
 import com.quarkdown.core.ast.attributes.location.LocationTrackableNode
 import com.quarkdown.core.ast.attributes.location.SectionLocation
@@ -9,14 +10,31 @@ import com.quarkdown.core.visitor.node.NodeVisitor
 /**
  * Node that can be numbered depending on its location in the document
  * and the amount of occurrences according to its [key].
+ *
+ * This node is peculiar, as it's the only node whose children are not evaluated directly during the function call expansion stage,
+ * but rather during the AST traversal.
+ *
+ * This is because in order to evaluate the children, we need to know the location of the node in the document,
+ * which is not known until the AST is fully traversed by [com.quarkdown.core.context.hooks.location.LocationAwareLabelStorerHook].
+ *
+ * After the traversal, the [com.quarkdown.core.context.hooks.location.NumberedEvaluatorHook] will evaluate and assign the [children] of this node, ready to be rendered.
+ *
+ * Since the evaluation does not happen within [com.quarkdown.core.function.call.FunctionCallNodeExpander],
+ * errors thrown during the evaluation will have to be caught externally. This is handled by the hook itself,
+ * which appends an error box (the same produced from the expander) to [children].
+ * From the user's perspective, this does not have any effect.
  * @param key name to group (and count) numbered nodes
- * @param children supplier of the node content given the evaluated [SectionLocation], formatted according to the active [DocumentNumbering]
- * @see com.quarkdown.core.context.hooks.LocationAwareLabelStorerHook for storing locations
+ * @param childrenSupplier supplier of the node content given the evaluated [SectionLocation], formatted according to the active [DocumentNumbering]
+ * @see com.quarkdown.core.context.hooks.location.LocationAwareLabelStorerHook for storing locations
+ * @see com.quarkdown.core.context.hooks.location.NumberedEvaluatorHook for evaluating [childrenSupplier]
  * @see com.quarkdown.core.document.numbering.NumberingFormat
  */
 class Numbered(
     val key: String,
-    val children: (location: String) -> List<Node>,
-) : LocationTrackableNode {
+    internal val childrenSupplier: (location: String) -> List<Node>,
+) : NestableNode,
+    LocationTrackableNode {
+    override var children: List<Node> = emptyList()
+
     override fun <T> accept(visitor: NodeVisitor<T>): T = visitor.visit(this)
 }
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/location/LocationAwareLabelStorerHook.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/location/LocationAwareLabelStorerHook.kt
@@ -1,4 +1,4 @@
-package com.quarkdown.core.context.hooks
+package com.quarkdown.core.context.hooks.location
 
 import com.quarkdown.core.ast.attributes.location.LocationTrackableNode
 import com.quarkdown.core.ast.attributes.location.SectionLocation
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/location/LocationAwarenessHook.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/location/LocationAwarenessHook.kt
@@ -1,4 +1,4 @@
-package com.quarkdown.core.context.hooks
+package com.quarkdown.core.context.hooks.location
 
 import com.quarkdown.core.ast.attributes.location.LocationTrackableNode
 import com.quarkdown.core.ast.attributes.location.SectionLocation
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/location/NumberedEvaluatorHook.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/context/hooks/location/NumberedEvaluatorHook.kt
@@ -0,0 +1,33 @@
+package com.quarkdown.core.context.hooks.location
+
+import com.quarkdown.core.ast.attributes.location.getLocationLabel
+import com.quarkdown.core.ast.iterator.AstIteratorHook
+import com.quarkdown.core.ast.iterator.ObservableAstIterator
+import com.quarkdown.core.ast.quarkdown.block.Numbered
+import com.quarkdown.core.context.Context
+import com.quarkdown.core.pipeline.error.PipelineException
+import com.quarkdown.core.pipeline.error.asNode
+
+/**
+ * Hook that evaluates the [Numbered] nodes in the document.
+ * If the evaluation fails, it attaches an error box, as in a regular function call expansion.
+ * This needs to be attached **after** the [LocationAwareLabelStorerHook] has populated the location labels.
+ * @param context context to retrieve the location label from
+ * @see Numbered to understand why it needs evaluation
+ */
+class NumberedEvaluatorHook(
+    private val context: Context,
+) : AstIteratorHook {
+    override fun attach(iterator: ObservableAstIterator) {
+        iterator.on<Numbered> { node ->
+            val label = node.getLocationLabel(context) ?: ""
+            node.children =
+                try {
+                    node.childrenSupplier(label)
+                } catch (e: PipelineException) {
+                    // Set an error box as the node's child if the evaluation fails.
+                    listOf(e.asNode(context))
+                }
+        }
+    }
+}
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/flavor/quarkdown/QuarkdownTreeIteratorFactory.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/flavor/quarkdown/QuarkdownTreeIteratorFactory.kt
@@ -2,10 +2,11 @@ package com.quarkdown.core.flavor.quarkdown
 
 import com.quarkdown.core.ast.iterator.ObservableAstIterator
 import com.quarkdown.core.context.MutableContext
-import com.quarkdown.core.context.hooks.LocationAwareLabelStorerHook
-import com.quarkdown.core.context.hooks.LocationAwarenessHook
 import com.quarkdown.core.context.hooks.MediaStorerHook
 import com.quarkdown.core.context.hooks.TableOfContentsGeneratorHook
+import com.quarkdown.core.context.hooks.location.LocationAwareLabelStorerHook
+import com.quarkdown.core.context.hooks.location.LocationAwarenessHook
+import com.quarkdown.core.context.hooks.location.NumberedEvaluatorHook
 import com.quarkdown.core.flavor.TreeIteratorFactory
 import com.quarkdown.core.flavor.base.BaseMarkdownTreeIteratorFactory
 
@@ -18,6 +19,7 @@ class QuarkdownTreeIteratorFactory : TreeIteratorFactory {
             .default(context)
             .attach(LocationAwarenessHook(context))
             .attach(LocationAwareLabelStorerHook(context))
+            .attach(NumberedEvaluatorHook(context))
             .attach(TableOfContentsGeneratorHook(context))
             .apply {
                 if (context.attachedPipeline?.options?.enableMediaStorage == true) {
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/call/FunctionCallNodeExpander.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/call/FunctionCallNodeExpander.kt
@@ -2,13 +2,12 @@ package com.quarkdown.core.function.call
 
 import com.quarkdown.core.ast.Node
 import com.quarkdown.core.ast.quarkdown.FunctionCallNode
-import com.quarkdown.core.ast.quarkdown.block.Box
 import com.quarkdown.core.context.MutableContext
-import com.quarkdown.core.function.error.FunctionException
 import com.quarkdown.core.function.value.output.OutputValueVisitorFactory
 import com.quarkdown.core.function.value.output.node.NodeOutputValueVisitorFactory
 import com.quarkdown.core.pipeline.error.PipelineErrorHandler
 import com.quarkdown.core.pipeline.error.PipelineException
+import com.quarkdown.core.pipeline.error.asNode
 
 /**
  * Given a [FunctionCallNode] from the AST, this expander resolves its referenced function, executes it
@@ -48,18 +47,8 @@ class FunctionCallNodeExpander(
             val outputNode = call.execute().accept(mapper)
             appendOutput(node, outputNode)
         } catch (e: PipelineException) {
-            // If the function call is invalid.
-
-            // The function that the error originated from.
-            // Note that sourceFunction might be different from call.function if the error comes from a nested function call down the stack.
-            val sourceFunction = (e as? FunctionException)?.function
-
-            // The error is handled by the error handler strategy.
-            errorHandler.handle(e, sourceFunction) {
-                // Shows an error message box in the final document.
-                // If the exception is linked to a function, its name appears in the error title.
-                appendOutput(node, Box.error(e.richMessage, title = sourceFunction?.name))
-            }
+            // If the function call is invalid, shows an error box.
+            appendOutput(node, e.asNode(errorHandler))
         }
     }
 
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/value/AdaptableValue.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/value/AdaptableValue.kt
@@ -4,7 +4,8 @@ package com.quarkdown.core.function.value
  * If a [Value] subclass is adaptable, it can be converted to another [Value]
  * in case the parameter of the function it is passed to expects a different type.
  *
- * For example, a [DictionaryValue] can be adapted to an [IterableValue].
+ * For example, a [DictionaryValue] can be adapted to an [IterableValue],
+ * and a [MarkdownContentValue] can be adapted to a [NodeValue].
  *
  * @param T type of the value to adapt to
  */
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/value/MarkdownContentValue.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/value/MarkdownContentValue.kt
@@ -7,7 +7,9 @@ import com.quarkdown.core.function.expression.visitor.ExpressionVisitor
 /**
  * A sub-AST that contains Markdown nodes. This is usually accepted in 'body' parameters.
  */
-data class MarkdownContentValue(override val unwrappedValue: MarkdownContent) : InputValue<MarkdownContent> {
+data class MarkdownContentValue(
+    override val unwrappedValue: MarkdownContent,
+) : InputValue<MarkdownContent> {
     override fun <T> accept(visitor: ExpressionVisitor<T>): T = visitor.visit(this)
 
     /**
@@ -29,7 +31,9 @@ fun MarkdownContent.wrappedAsValue() = MarkdownContentValue(this)
 /**
  * A sub-AST that contains Markdown nodes. This is usually accepted in 'body' parameters.
  */
-data class InlineMarkdownContentValue(override val unwrappedValue: InlineMarkdownContent) : InputValue<InlineMarkdownContent> {
+data class InlineMarkdownContentValue(
+    override val unwrappedValue: InlineMarkdownContent,
+) : InputValue<InlineMarkdownContent> {
     override fun <T> accept(visitor: ExpressionVisitor<T>): T = visitor.visit(this)
 
     /**
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/value/NodeValue.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/value/NodeValue.kt
@@ -1,5 +1,6 @@
 package com.quarkdown.core.function.value
 
+import com.quarkdown.core.ast.MarkdownContent
 import com.quarkdown.core.ast.Node
 import com.quarkdown.core.function.expression.Expression
 import com.quarkdown.core.function.expression.visitor.ExpressionVisitor
@@ -11,10 +12,13 @@ import com.quarkdown.core.function.value.output.OutputValueVisitor
 data class NodeValue(
     override val unwrappedValue: Node,
 ) : OutputValue<Node>,
-    Expression {
+    Expression,
+    AdaptableValue<MarkdownContentValue> {
     override fun <O> accept(visitor: OutputValueVisitor<O>): O = visitor.visit(this)
 
     override fun <T> accept(visitor: ExpressionVisitor<T>): T = visitor.visit(this)
+
+    override fun adapt(): MarkdownContentValue = MarkdownContentValue(MarkdownContent(listOf(unwrappedValue)))
 }
 
 /**
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/value/data/Lambda.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/function/value/data/Lambda.kt
@@ -6,6 +6,7 @@ import com.quarkdown.core.function.error.InvalidLambdaArgumentCountException
 import com.quarkdown.core.function.library.Library
 import com.quarkdown.core.function.reflect.DynamicValueConverter
 import com.quarkdown.core.function.reflect.FromDynamicType
+import com.quarkdown.core.function.value.AdaptableValue
 import com.quarkdown.core.function.value.Destructurable
 import com.quarkdown.core.function.value.DynamicValue
 import com.quarkdown.core.function.value.NoneValue
@@ -134,10 +135,11 @@ open class Lambda(
         // Invoke the lambda action and convert the result to a static type.
         val result = invokeDynamic(*values)
 
-        return if (result is DynamicValue) {
-            DynamicValueConverter(result).convertTo(T::class, parentContext)
-        } else {
-            result
+        return when (result) {
+            is V -> result
+            is DynamicValue -> DynamicValueConverter(result).convertTo(T::class, parentContext)
+            is AdaptableValue<*> -> result.adapt()
+            else -> result
         } as? V
             ?: throw IllegalArgumentException("Unexpected lambda result: expected ${V::class}, found ${result::class}")
     }
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/error/BasePipelineErrorHandler.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/error/BasePipelineErrorHandler.kt
@@ -7,14 +7,13 @@ import com.quarkdown.core.log.Log
  * Simple pipeline error handler that logs the error message.
  */
 class BasePipelineErrorHandler : PipelineErrorHandler {
-    override fun handle(
+    override fun <T> handle(
         error: PipelineException,
         sourceFunction: Function<*>?,
-        action: () -> Unit,
-    ) {
+        action: () -> T,
+    ): T {
         val message = error.message ?: "Unknown error"
         Log.error(message)
-
-        action()
+        return action()
     }
 }
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/error/PipelineErrorHandler.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/error/PipelineErrorHandler.kt
@@ -13,10 +13,11 @@ interface PipelineErrorHandler {
      * @param action additional custom error handler
      * @see BasePipelineErrorHandler
      * @see StrictPipelineErrorHandler
+     * @return the result of the action
      */
-    fun handle(
+    fun <T> handle(
         error: PipelineException,
         sourceFunction: Function<*>?,
-        action: () -> Unit,
-    )
+        action: () -> T,
+    ): T
 }
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/error/PipelineException.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/error/PipelineException.kt
@@ -1,7 +1,11 @@
 package com.quarkdown.core.pipeline.error
 
 import com.quarkdown.core.ast.InlineContent
+import com.quarkdown.core.ast.Node
 import com.quarkdown.core.ast.dsl.buildInline
+import com.quarkdown.core.ast.quarkdown.block.Box
+import com.quarkdown.core.context.Context
+import com.quarkdown.core.function.error.FunctionException
 import com.quarkdown.core.util.toPlainText
 
 /**
@@ -10,6 +14,34 @@ import com.quarkdown.core.util.toPlainText
  * @param code error code. If the program is running in strict mode and thus is killed,
  *             it defines the process exit code
  */
-open class PipelineException(val richMessage: InlineContent, val code: Int) : Exception(richMessage.toPlainText()) {
+open class PipelineException(
+    val richMessage: InlineContent,
+    val code: Int,
+) : Exception(richMessage.toPlainText()) {
     constructor(message: String, code: Int) : this(buildInline { text(message) }, code)
 }
+
+/**
+ * Converts [this] exception to a renderable [Node], and performs the error handling provided by the [errorHandler] strategy.
+ * @param errorHandler strategy to handle the error
+ * @return [this] exception as a renderable [Node]
+ */
+fun PipelineException.asNode(errorHandler: PipelineErrorHandler): Node {
+    // The function that the error originated from, if any.
+    val sourceFunction = (this as? FunctionException)?.function
+
+    return errorHandler.handle(this, sourceFunction) {
+        Box.error(richMessage, title = sourceFunction?.name)
+    }
+}
+
+/**
+ * @param context context to use to retrieve the error handler from
+ * @throws [this] exception if the context does not have an attached pipeline to retrieve the error handler from
+ * @see asNode
+ */
+fun PipelineException.asNode(context: Context): Node =
+    context.attachedPipeline
+        ?.options
+        ?.errorHandler
+        ?.let(::asNode) ?: throw this
diff --git a/quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/error/StrictPipelineErrorHandler.kt b/quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/error/StrictPipelineErrorHandler.kt
@@ -8,11 +8,11 @@ import com.quarkdown.core.log.Log
  * In a regular pipeline, this will cause the program to exit (see `QuarkdownCli` from the `cli` module).
  */
 class StrictPipelineErrorHandler : PipelineErrorHandler {
-    override fun handle(
+    override fun <T> handle(
         error: PipelineException,
         sourceFunction: Function<*>?,
-        action: () -> Unit,
-    ) {
+        action: () -> T,
+    ): Nothing {
         Log.error("An error occurred while in strict mode (error code ${error.code})")
         sourceFunction?.let { Log.error("Originated from function: ${it.name}") }
         throw error
diff --git a/quarkdown-core/src/test/kotlin/com/quarkdown/core/LambdaTest.kt b/quarkdown-core/src/test/kotlin/com/quarkdown/core/LambdaTest.kt
diff --git a/quarkdown-core/src/test/kotlin/com/quarkdown/core/TreeTraversalTest.kt b/quarkdown-core/src/test/kotlin/com/quarkdown/core/TreeTraversalTest.kt
diff --git a/quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/HtmlTagBuilder.kt b/quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/HtmlTagBuilder.kt
diff --git a/quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/extension/HtmlRendererFactoryVisitor.kt b/quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/extension/HtmlRendererFactoryVisitor.kt
diff --git a/quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/node/BaseHtmlNodeRenderer.kt b/quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/node/BaseHtmlNodeRenderer.kt
diff --git a/quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/node/QuarkdownHtmlNodeRenderer.kt b/quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/node/QuarkdownHtmlNodeRenderer.kt
diff --git a/quarkdown-test/src/test/kotlin/com/quarkdown/test/NumberingTest.kt b/quarkdown-test/src/test/kotlin/com/quarkdown/test/NumberingTest.kt

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-package com.quarkdown.core.context.hooks`
	`1`	`+package com.quarkdown.core.context.hooks.location`
`2`	`2`
`3`	`3`	`import com.quarkdown.core.ast.attributes.location.LocationTrackableNode`
`4`	`4`	`import com.quarkdown.core.ast.attributes.location.SectionLocation`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,8 @@ package com.quarkdown.core.function.value`
`4`	`4`	`* If a [Value] subclass is adaptable, it can be converted to another [Value]`
`5`	`5`	`* in case the parameter of the function it is passed to expects a different type.`
`6`	`6`	`*`
`7`		`- * For example, a [DictionaryValue] can be adapted to an [IterableValue].`
	`7`	`+ * For example, a [DictionaryValue] can be adapted to an [IterableValue],`
	`8`	`+ * and a [MarkdownContentValue] can be adapted to a [NodeValue].`
`8`	`9`	`*`
`9`	`10`	`* @param T type of the value to adapt to`
`10`	`11`	`*/`