From 487b336261bbbc547e3b3e60b924b22970ad71ad Mon Sep 17 00:00:00 2001 From: Sebastiano Poggi Date: Fri, 26 Jul 2024 15:18:56 +0200 Subject: [PATCH] Rename optimizeEdits to editorMode in MarkdownProcessor (#485) Also improve the documentation --- .../markdown/processing/MarkdownProcessor.kt | 30 +++++++++++-------- .../MarkdownProcessorOptimizeEditsTest.kt | 24 +++++++-------- .../view/markdown/MarkdownPreview.kt | 2 +- 3 files changed, 31 insertions(+), 25 deletions(-) diff --git a/markdown/core/src/main/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessor.kt b/markdown/core/src/main/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessor.kt index 289aecfba..3b41bb0ba 100644 --- a/markdown/core/src/main/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessor.kt +++ b/markdown/core/src/main/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessor.kt @@ -35,15 +35,21 @@ import org.commonmark.node.ListBlock as CMListBlock * * @param extensions Extensions to use when processing the Markdown (e.g., * to support parsing custom block-level Markdown). - * @param optimizeEdits Indicates whether the processing should only update - * the changed blocks by keeping a previous state in memory. Default is - * `false`; set this to `true` if this parser will be used in an editor - * scenario, where the raw Markdown is only ever going to change - * slightly but frequently (e.g., as the user types). Setting this to - * `true` has a memory cost, and can be a performance regression if the - * parse input is not always small variations of the same basic text. - * When this is `true`, the instance of [MarkdownProcessor] is **not** - * thread-safe! + * @param editorMode Indicates whether the processor should be optimized + * for an editor/preview scenario, where it assumes small incremental + * changes as performed by a user typing. This means it will only update + * the changed blocks by keeping state in memory. + * + * Default is `false`; set this to `true` if this parser will be used in + * an editor scenario, where the raw Markdown is only ever going to + * change slightly but frequently (e.g., as the user types). + * + * **Attention:** do **not** reuse or share an instance of + * [MarkdownProcessor] that is in [editorMode]. Processing entirely + * different Markdown strings will defeat the purpose of the + * optimization. When in editor mode, the instance of + * [MarkdownProcessor] is **not** thread-safe! + * * @param commonMarkParser The CommonMark [Parser] used to parse the * Markdown. By default it's a vanilla instance provided by the * [MarkdownParserFactory], but you can provide your own if you need to @@ -54,8 +60,8 @@ import org.commonmark.node.ListBlock as CMListBlock @ExperimentalJewelApi public class MarkdownProcessor( private val extensions: List = emptyList(), - private val optimizeEdits: Boolean = false, - private val commonMarkParser: Parser = MarkdownParserFactory.create(optimizeEdits, extensions), + private val editorMode: Boolean = false, + private val commonMarkParser: Parser = MarkdownParserFactory.create(editorMode, extensions), ) { private var currentState = State(emptyList(), emptyList(), emptyList()) @@ -76,7 +82,7 @@ public class MarkdownProcessor( @Language("Markdown") rawMarkdown: String, ): List { val blocks = - if (optimizeEdits) { + if (editorMode) { processWithQuickEdits(rawMarkdown) } else { parseRawMarkdown(rawMarkdown) diff --git a/markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessorOptimizeEditsTest.kt b/markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessorOptimizeEditsTest.kt index e57717cec..e54329ebe 100644 --- a/markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessorOptimizeEditsTest.kt +++ b/markdown/core/src/test/kotlin/org/jetbrains/jewel/markdown/processing/MarkdownProcessorOptimizeEditsTest.kt @@ -45,7 +45,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `first blocks stay the same`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits( @@ -80,7 +80,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `first block edited`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits( @@ -136,7 +136,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `last block edited`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits( @@ -195,7 +195,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `middle block edited`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits( @@ -256,7 +256,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `blocks merged`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits( @@ -313,7 +313,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `blocks split`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits( @@ -371,7 +371,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `blocks deleted`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits( @@ -423,7 +423,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `blocks added`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondDocument = """ @@ -491,7 +491,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `no changes`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits(rawMarkdown) assertHtmlEquals( @@ -523,7 +523,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `empty line added`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) val firstRun = processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits("\n" + rawMarkdown) assertHtmlEquals( @@ -557,7 +557,7 @@ class MarkdownProcessorOptimizeEditsTest { /** Regression https://github.com/JetBrains/jewel/issues/344 */ @Test fun `content if empty`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) processor.processWithQuickEdits(rawMarkdown) val secondRun = processor.processWithQuickEdits("") assertHtmlEquals( @@ -570,7 +570,7 @@ class MarkdownProcessorOptimizeEditsTest { @Test fun `chained changes`() { - val processor = MarkdownProcessor(optimizeEdits = true) + val processor = MarkdownProcessor(editorMode = true) processor.processWithQuickEdits( """ # Header 0 diff --git a/samples/standalone/src/main/kotlin/org/jetbrains/jewel/samples/standalone/view/markdown/MarkdownPreview.kt b/samples/standalone/src/main/kotlin/org/jetbrains/jewel/samples/standalone/view/markdown/MarkdownPreview.kt index 6c1bd4996..c0de6bb2d 100644 --- a/samples/standalone/src/main/kotlin/org/jetbrains/jewel/samples/standalone/view/markdown/MarkdownPreview.kt +++ b/samples/standalone/src/main/kotlin/org/jetbrains/jewel/samples/standalone/view/markdown/MarkdownPreview.kt @@ -56,7 +56,7 @@ internal fun MarkdownPreview( // We are doing this here for the sake of simplicity. // In a real-world scenario you would be doing this outside your Composables, // potentially involving ViewModels, dependency injection, etc. - val processor = remember { MarkdownProcessor(extensions, optimizeEdits = true) } + val processor = remember { MarkdownProcessor(extensions, editorMode = true) } LaunchedEffect(rawMarkdown) { // TODO you may want to debounce or drop on backpressure, in real usages. You should also not do this