Merge pull request #16 from iamgio/renderer-refactor

Refactor: modular architecture for rendering targets

Author: iamgio

README.md

@@ -272,9 +272,13 @@ If you would like to familiarize yourself with Quarkdown instead, `quarkdown rep
 
 - **`--pdf`**: produces a PDF file. Learn more in the wiki's [*PDF export*](https://github.com/iamgio/quarkdown/wiki/pdf-export) page.
 
-- `-o <dir>` or `--output <dir>`: sets the directory of the output files. If unset, defaults to `./output`.
+- `-o <dir>` or `--output <dir>`: sets the directory of the output files. Defaults to `./output`.
 
-- `-l <dir>` or `--libs <dir>`: sets the directory where external libraries can be loaded from. If unset, defaults to `<install dir>/lib/qmd`. [(?)](https://github.com/iamgio/quarkdown/wiki/importing-external-libraries)
+- `-l <dir>` or `--libs <dir>`: sets the directory where external libraries can be loaded from. Defaults to `<install dir>/lib/qmd`. [(?)](https://github.com/iamgio/quarkdown/wiki/importing-external-libraries)
+
+- `-r <renderer>` or `--render <renderer>`: sets the target renderer. Defaults to `html`. Accepted values:
+  - `html`
+  - `html-pdf` (equivalent to `-r html --pdf`)
 
 - `--server-port <port>`: optional customization of the local webserver's port. Defaults to `8089`.
 

quarkdown-cli/build.gradle.kts

@@ -7,9 +7,9 @@ dependencies {
     testImplementation("org.jetbrains.kotlin:kotlin-test")
     testImplementation("org.apache.pdfbox:pdfbox:3.0.4")
     implementation(project(":quarkdown-core"))
+    implementation(project(":quarkdown-html"))
     implementation(project(":quarkdown-server"))
     implementation(project(":quarkdown-interaction"))
-    implementation(project(":quarkdown-pdf"))
     implementation(project(":quarkdown-stdlib"))
     implementation("com.github.ajalt.clikt:clikt:5.0.3")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/CliOptions.kt

@@ -1,5 +1,6 @@
 package com.quarkdown.cli
 
+import com.quarkdown.cli.renderer.RendererRetriever
 import java.io.File
 
 /**
@@ -8,6 +9,7 @@ import java.io.File
  * @param source main source file to process
  * @param outputDirectory the output directory to save resource in, if set
  * @param libraryDirectory the directory to load .qmd library files from
+ * @param rendererName name of the renderer to use to generate the output for
  * @param clean whether to clean the output directory before generating new files
  * @param nodePath path to the Node.js executable
  * @param npmPath path to the npm executable
@@ -16,7 +18,16 @@ data class CliOptions(
     val source: File?,
     val outputDirectory: File?,
     val libraryDirectory: File?,
+    val rendererName: String,
     val clean: Boolean,
-    val nodePath: String?,
-    val npmPath: String?,
-)
+    val nodePath: String,
+    val npmPath: String,
+    val noPdfSandbox: Boolean = false,
+    val generatePdf: Boolean = false,
+) {
+    /**
+     * The rendering target to generate the output for.
+     * For instance HTML or PDF.
+     */
+    val renderer by lazy { RendererRetriever(this).getRenderer() }
+}

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/PipelineInitialization.kt

@@ -1,14 +1,17 @@
 package com.quarkdown.cli
 
+import com.quarkdown.core.context.Context
 import com.quarkdown.core.context.MutableContext
 import com.quarkdown.core.flavor.MarkdownFlavor
+import com.quarkdown.core.flavor.RendererFactory
 import com.quarkdown.core.function.library.Library
 import com.quarkdown.core.function.library.LibraryExporter
 import com.quarkdown.core.log.DebugFormatter
 import com.quarkdown.core.log.Log
 import com.quarkdown.core.pipeline.Pipeline
 import com.quarkdown.core.pipeline.PipelineHooks
 import com.quarkdown.core.pipeline.PipelineOptions
+import com.quarkdown.core.rendering.RenderingComponents
 import com.quarkdown.stdlib.Stdlib
 
 /**
@@ -25,6 +28,7 @@ object PipelineInitialization {
         flavor: MarkdownFlavor,
         loadableLibraryExporters: Set<LibraryExporter>,
         options: PipelineOptions,
+        renderer: (RendererFactory, Context) -> RenderingComponents,
     ): Pipeline {
         // Libraries to load.
         val libraries: Set<Library> = LibraryExporter.exportAll(Stdlib)
@@ -52,7 +56,7 @@ object PipelineInitialization {
             context = MutableContext(flavor, loadableLibraries = loadableLibraries),
             options = options,
             libraries = libraries,
-            renderer = { rendererFactory, context -> rendererFactory.html(context) },
+            renderer = renderer,
             hooks = hooks,
         )
     }

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/creator/command/CreateProjectCommand.kt

@@ -14,7 +14,6 @@ import com.quarkdown.cli.creator.ProjectCreator
 import com.quarkdown.cli.creator.content.DefaultProjectCreatorInitialContentSupplier
 import com.quarkdown.cli.creator.content.EmptyProjectCreatorInitialContentSupplier
 import com.quarkdown.cli.creator.template.DefaultProjectCreatorTemplateProcessorFactory
-import com.quarkdown.cli.util.saveTo
 import com.quarkdown.core.document.DocumentAuthor
 import com.quarkdown.core.document.DocumentInfo
 import com.quarkdown.core.document.DocumentTheme
@@ -23,6 +22,7 @@ import com.quarkdown.core.function.quarkdownName
 import com.quarkdown.core.localization.Locale
 import com.quarkdown.core.localization.LocaleLoader
 import com.quarkdown.core.log.Log
+import com.quarkdown.core.pipeline.output.saveTo
 import java.io.File
 
 /**

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/exec/CompileCommand.kt

@@ -3,19 +3,15 @@ package com.quarkdown.cli.exec
 import com.github.ajalt.clikt.parameters.arguments.argument
 import com.github.ajalt.clikt.parameters.options.flag
 import com.github.ajalt.clikt.parameters.options.option
+import com.github.ajalt.clikt.parameters.options.validate
 import com.github.ajalt.clikt.parameters.types.file
 import com.quarkdown.cli.CliOptions
 import com.quarkdown.cli.exec.strategy.FileExecutionStrategy
 import com.quarkdown.cli.server.WebServerOptions
-import com.quarkdown.core.context.MutableContext
-import com.quarkdown.core.flavor.quarkdown.QuarkdownFlavor
 import com.quarkdown.core.log.Log
 import com.quarkdown.core.pipeline.PipelineOptions
-import com.quarkdown.pdf.PdfExportOptions
-import com.quarkdown.pdf.PdfExporters
 import com.quarkdown.server.browser.DefaultBrowserLauncher
 import java.io.File
-import kotlin.concurrent.thread
 
 /**
  * Command to compile a Quarkdown file into an output.
@@ -42,23 +38,22 @@ class CompileCommand : ExecuteCommand("c") {
     private val noPdfSandbox: Boolean by option(
         "--pdf-no-sandbox",
         help = "(Unsafe) Disable Chrome sandbox for PDF export",
-    ).flag()
-
-    override fun finalizeCliOptions(original: CliOptions) = original.copy(source = source)
-
-    override fun createExecutionStrategy(cliOptions: CliOptions) = FileExecutionStrategy(source)
-
-    /**
-     * Runs the action in parallel if needed.
-     */
-    private fun runParallelizable(action: () -> Unit) {
-        val parallelizeCondition = super.preview
+    ).flag().validate {
         when {
-            parallelizeCondition -> thread { action() }
-            else -> action()
+            it && !exportPdf -> Log.warn("--pdf-no-sandbox flag is ignored because --pdf flag is not set.")
+            it -> Log.warn("Disabling Chrome sandbox for PDF export. This is potentially unsafe.")
         }
     }
 
+    override fun finalizeCliOptions(original: CliOptions) =
+        original.copy(
+            source = source,
+            noPdfSandbox = noPdfSandbox,
+            generatePdf = exportPdf,
+        )
+
+    override fun createExecutionStrategy(cliOptions: CliOptions) = FileExecutionStrategy(source)
+
     override fun postExecute(
         outcome: ExecutionOutcome,
         cliOptions: CliOptions,
@@ -69,16 +64,6 @@ class CompileCommand : ExecuteCommand("c") {
             return
         }
 
-        if (noPdfSandbox) {
-            when {
-                !exportPdf -> Log.warn("--pdf-no-sandbox flag is ignored because --pdf flag is not set.")
-                else -> Log.warn("Disabling Chrome sandbox for PDF export. This is potentially unsafe.")
-            }
-        }
-
-        if (exportPdf) {
-            runParallelizable { exportPdf(outcome.directory) }
-        }
         if (super.preview) {
             launchServer(outcome.directory)
         }
@@ -97,24 +82,4 @@ class CompileCommand : ExecuteCommand("c") {
             ),
         )
     }
-
-    private fun exportPdf(
-        sourceDirectory: File,
-        outDirectory: File = sourceDirectory.parentFile,
-    ) {
-        val out = File(outDirectory, "${sourceDirectory.name}.pdf")
-
-        // Currently, HTML is hardcoded. In the future, more targets can be chosen
-        // and the PDF exporter for the corresponding target should be selected.
-        val html = QuarkdownFlavor.rendererFactory.html(MutableContext(QuarkdownFlavor))
-
-        val options = PdfExportOptions(super.nodePath, super.npmPath, this.noPdfSandbox)
-        val exporter = PdfExporters.getForRenderingTarget(html.postRenderer, options)
-
-        try {
-            exporter.export(sourceDirectory, out)
-        } catch (e: Exception) {
-            Log.error("Failed to export PDF: ${e.message}")
-        }
-    }
 }

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/exec/Execute.kt

@@ -7,7 +7,6 @@ import com.quarkdown.cli.lib.QmdLibraries
 import com.quarkdown.cli.server.WebServerOptions
 import com.quarkdown.cli.server.WebServerStarter
 import com.quarkdown.cli.util.cleanDirectory
-import com.quarkdown.cli.util.saveTo
 import com.quarkdown.core.flavor.MarkdownFlavor
 import com.quarkdown.core.flavor.quarkdown.QuarkdownFlavor
 import com.quarkdown.core.function.error.FunctionRuntimeException
@@ -16,6 +15,7 @@ import com.quarkdown.core.log.Log
 import com.quarkdown.core.pipeline.Pipeline
 import com.quarkdown.core.pipeline.PipelineOptions
 import com.quarkdown.core.pipeline.error.PipelineException
+import com.quarkdown.core.pipeline.output.saveTo
 import com.quarkdown.server.message.Reload
 import com.quarkdown.server.message.ServerMessage
 import kotlin.system.exitProcess
@@ -46,7 +46,7 @@ fun runQuarkdown(
 
     // The pipeline that contains all the stages to go through,
     // from the source input to the final output.
-    val pipeline: Pipeline = PipelineInitialization.init(flavor, libraries, pipelineOptions)
+    val pipeline: Pipeline = PipelineInitialization.init(flavor, libraries, pipelineOptions, cliOptions.renderer)
 
     // Output directory to save the generated resources in.
     val outputDirectory = cliOptions.outputDirectory

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/exec/ExecuteCommand.kt

@@ -78,6 +78,15 @@ abstract class ExecuteCommand(
             canBeDir = true,
         ).default(File(thisExecutableFile?.parentFile, DEFAULT_LIBRARY_DIRECTORY))
 
+    /**
+     * The rendering target to generate output for.
+     */
+    private val renderer: String by option(
+        "-r",
+        "--render",
+        help = "Rendering target to generate output for",
+    ).default("html")
+
     /**
      * When enabled, the rendering stage produces pretty output code.
      */
@@ -128,7 +137,7 @@ abstract class ExecuteCommand(
     /**
      * Path to the Node.js executable, needed for PDF export.
      */
-    protected val nodePath: String by option("--node-path", help = "Path to the Node.js executable")
+    private val nodePath: String by option("--node-path", help = "Path to the Node.js executable")
         .default(NodeJsWrapper.defaultPath)
 
     /**
@@ -146,6 +155,7 @@ abstract class ExecuteCommand(
             source = null,
             outputDirectory,
             libraryDirectory,
+            renderer,
             clean,
             nodePath,
             npmPath,

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/exec/strategy/FileExecutionStrategy.kt

@@ -10,5 +10,5 @@ import java.io.File
 class FileExecutionStrategy(
     private val file: File,
 ) : PipelineExecutionStrategy {
-    override fun execute(pipeline: Pipeline): OutputResource = pipeline.execute(file.readText())
+    override fun execute(pipeline: Pipeline): OutputResource? = pipeline.execute(file.readText())
 }

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/renderer/RendererRetriever.kt

@@ -0,0 +1,50 @@
+package com.quarkdown.cli.renderer
+
+import com.quarkdown.cli.CliOptions
+import com.quarkdown.core.context.Context
+import com.quarkdown.core.flavor.RendererFactory
+import com.quarkdown.core.rendering.RenderingComponents
+import com.quarkdown.rendering.html.extension.html
+import com.quarkdown.rendering.html.extension.htmlPdf
+import com.quarkdown.rendering.html.pdf.HtmlPdfExportOptions
+
+private const val HTML = "html"
+private const val HTML_PDF = "html-pdf"
+
+/**
+ * Given a [CliOptions] instance, retrieves the appropriate renderer (e.g. HTML, PDF) for the pipeline
+ * based on [CliOptions.rendererName] (case-insensitive), [CliOptions.generatePdf] and other options.
+ */
+class RendererRetriever(
+    private val options: CliOptions,
+) {
+    private val name
+        get() = options.rendererName.lowercase()
+
+    /**
+     * Retrieves the rendering target specified by [options].
+     *
+     * Note: the current implementation hardcodes renderer names. In the future an extensible retriever will be implemented.
+     * @return the rendering target for the pipeline, to generate the output for.
+     */
+    fun getRenderer(): (RendererFactory, Context) -> RenderingComponents =
+        { factory, context ->
+            when {
+                isHtmlPdf() -> factory.htmlPdf(context, createHtmlPdfExportOptions())
+                isHtml() -> factory.html(context)
+                else -> throw IllegalArgumentException("Unsupported renderer: '${options.rendererName}'")
+            }
+        }
+
+    private fun isHtml() = name == HTML
+
+    private fun isHtmlPdf() = name == HTML_PDF || (name == HTML && options.generatePdf)
+
+    private fun createHtmlPdfExportOptions() =
+        HtmlPdfExportOptions(
+            outputDirectory = requireNotNull(options.outputDirectory) { "Output directory must be specified for PDF export." },
+            nodeJsPath = options.nodePath,
+            npmPath = options.npmPath,
+            noSandbox = options.noPdfSandbox,
+        )
+}

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/util/IOUtils.kt

@@ -1,7 +1,5 @@
 package com.quarkdown.cli.util
 
-import com.quarkdown.core.pipeline.output.FileResourceExporter
-import com.quarkdown.core.pipeline.output.OutputResource
 import java.io.File
 import kotlin.io.path.ExperimentalPathApi
 import kotlin.io.path.deleteRecursively
@@ -26,10 +24,3 @@ val thisExecutableFile: File?
 fun File.cleanDirectory() {
     listFiles()?.forEach { it.toPath().deleteRecursively() }
 }
-
-/**
- * Saves [this] resource to file in a [directory].
- * @see FileResourceExporter
- * @return the saved file
- */
-fun OutputResource.saveTo(directory: File): File = accept(FileResourceExporter(location = directory))