Skip to content

Commit

Permalink
Rename optimizeEdits to editorMode in MarkdownProcessor (#485)
Browse files Browse the repository at this point in the history
Also improve the documentation
  • Loading branch information
rock3r authored Jul 26, 2024
1 parent 3c32f82 commit 487b336
Show file tree
Hide file tree
Showing 3 changed files with 31 additions and 25 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -54,8 +60,8 @@ import org.commonmark.node.ListBlock as CMListBlock
@ExperimentalJewelApi
public class MarkdownProcessor(
private val extensions: List<MarkdownProcessorExtension> = 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())

Expand All @@ -76,7 +82,7 @@ public class MarkdownProcessor(
@Language("Markdown") rawMarkdown: String,
): List<MarkdownBlock> {
val blocks =
if (optimizeEdits) {
if (editorMode) {
processWithQuickEdits(rawMarkdown)
} else {
parseRawMarkdown(rawMarkdown)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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 =
"""
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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(
Expand All @@ -570,7 +570,7 @@ class MarkdownProcessorOptimizeEditsTest {

@Test
fun `chained changes`() {
val processor = MarkdownProcessor(optimizeEdits = true)
val processor = MarkdownProcessor(editorMode = true)
processor.processWithQuickEdits(
"""
# Header 0
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 487b336

Please sign in to comment.