Feature/definition lists (#43)

div syntax for definition lists

Author: cscheid

crates/quarto-markdown-pandoc/src/pandoc/treesitter_utils/postprocess.rs

@@ -7,7 +7,7 @@ use crate::filters::{
     Filter, FilterReturn::FilterResult, FilterReturn::Unchanged, topdown_traverse,
 };
 use crate::pandoc::attr::{Attr, is_empty_attr};
-use crate::pandoc::block::{Block, Figure, Plain};
+use crate::pandoc::block::{Block, DefinitionList, Div, Figure, Plain};
 use crate::pandoc::caption::Caption;
 use crate::pandoc::inline::{Inline, Inlines, Space, Span, Str, Superscript};
 use crate::pandoc::location::{Range, SourceInfo, empty_range, empty_source_info};
@@ -166,6 +166,99 @@ pub fn coalesce_abbreviations(inlines: Vec<Inline>) -> (Vec<Inline>, bool) {
     (result, did_coalesce)
 }
 
+/// Validate that a div has the structure required for a definition list.
+///
+/// Valid structure:
+/// - Div must have "definition-list" class
+/// - Div must contain exactly one block, which must be a BulletList
+/// - Each item in the BulletList must have:
+///   - Exactly two blocks
+///   - First block must be Plain or Paragraph (contains the term)
+///   - Second block must be a BulletList (contains the definitions)
+///
+/// Returns true if valid, false otherwise.
+fn is_valid_definition_list_div(div: &Div) -> bool {
+    // Check if div has "definition-list" class
+    if !div.attr.1.contains(&"definition-list".to_string()) {
+        return false;
+    }
+
+    // Must contain exactly one block
+    if div.content.len() != 1 {
+        // FUTURE: issue linter warning: "definition-list div must contain exactly one bullet list"
+        return false;
+    }
+
+    // That block must be a BulletList
+    let Block::BulletList(bullet_list) = &div.content[0] else {
+        // FUTURE: issue linter warning: "definition-list div must contain a bullet list"
+        return false;
+    };
+
+    // Check each item in the bullet list
+    for item_blocks in &bullet_list.content {
+        // Each item must have exactly 2 blocks
+        if item_blocks.len() != 2 {
+            // FUTURE: issue linter warning: "each definition list item must have a term and a nested bullet list"
+            return false;
+        }
+
+        // First block must be Plain or Paragraph
+        match &item_blocks[0] {
+            Block::Plain(_) | Block::Paragraph(_) => {}
+            _ => {
+                // FUTURE: issue linter warning: "definition list term must be Plain or Paragraph"
+                return false;
+            }
+        }
+
+        // Second block must be BulletList
+        if !matches!(&item_blocks[1], Block::BulletList(_)) {
+            // FUTURE: issue linter warning: "definitions must be in a nested bullet list"
+            return false;
+        }
+    }
+
+    true
+}
+
+/// Transform a valid definition-list div into a DefinitionList block.
+///
+/// PRECONDITION: div must pass is_valid_definition_list_div() check.
+/// This function uses unwrap() liberally since the structure has been pre-validated.
+fn transform_definition_list_div(div: Div) -> Block {
+    // Extract the bullet list (validated to exist)
+    let Block::BulletList(bullet_list) = div.content.into_iter().next().unwrap() else {
+        panic!("BulletList expected after validation");
+    };
+
+    // Transform each item into (term, definitions) tuple
+    let mut definition_items: Vec<(Inlines, Vec<crate::pandoc::block::Blocks>)> = Vec::new();
+
+    for mut item_blocks in bullet_list.content {
+        // Extract term from first block (Plain or Paragraph)
+        let term_inlines = match item_blocks.remove(0) {
+            Block::Plain(plain) => plain.content,
+            Block::Paragraph(para) => para.content,
+            _ => panic!("Plain or Paragraph expected after validation"),
+        };
+
+        // Extract definitions from second block (BulletList)
+        let Block::BulletList(definitions_list) = item_blocks.remove(0) else {
+            panic!("BulletList expected after validation");
+        };
+
+        // Each item in the definitions bullet list is a definition (Vec<Block>)
+        definition_items.push((term_inlines, definitions_list.content));
+    }
+
+    // Preserve source location from the original div
+    Block::DefinitionList(DefinitionList {
+        content: definition_items,
+        source_info: div.source_info,
+    })
+}
+
 /// Apply post-processing transformations to the Pandoc AST
 pub fn postprocess(doc: Pandoc) -> Result<Pandoc, Vec<String>> {
     let mut errors = Vec::new();
@@ -273,6 +366,14 @@ pub fn postprocess(doc: Pandoc) -> Result<Pandoc, Vec<String>> {
                     true,
                 )
             })
+            // Convert definition-list divs to DefinitionList blocks
+            .with_div(|div| {
+                if is_valid_definition_list_div(&div) {
+                    FilterResult(vec![transform_definition_list_div(div)], false)
+                } else {
+                    Unchanged(div)
+                }
+            })
             .with_shortcode(|shortcode| {
                 FilterResult(vec![Inline::Span(shortcode_to_span(shortcode))], false)
             })

crates/quarto-markdown-pandoc/src/writers/native.rs

@@ -562,6 +562,32 @@ fn write_block<T: std::io::Write>(block: &Block, buf: &mut T) -> std::io::Result
             write!(buf, "] ")?;
             write_native_table_foot(foot, buf)?;
         }
+        Block::DefinitionList(crate::pandoc::DefinitionList { content, .. }) => {
+            write!(buf, "DefinitionList [")?;
+            for (i, (term, definitions)) in content.iter().enumerate() {
+                if i > 0 {
+                    write!(buf, ", ")?;
+                }
+                write!(buf, "(")?;
+                write_inlines(term, buf)?;
+                write!(buf, ", [")?;
+                for (j, def_blocks) in definitions.iter().enumerate() {
+                    if j > 0 {
+                        write!(buf, ", ")?;
+                    }
+                    write!(buf, "[")?;
+                    for (k, block) in def_blocks.iter().enumerate() {
+                        if k > 0 {
+                            write!(buf, ", ")?;
+                        }
+                        write_block(block, buf)?;
+                    }
+                    write!(buf, "]")?;
+                }
+                write!(buf, "])")?;
+            }
+            write!(buf, "]")?;
+        }
         _ => panic!("Unsupported block type in native writer: {:?}", block),
     }
     Ok(())

crates/quarto-markdown-pandoc/tests/snapshots/native/definition-list-basic.qmd

@@ -0,0 +1,6 @@
+::: {.definition-list}
+* term 1
+  - definition 1
+* term 2
+  - definition 2
+:::

crates/quarto-markdown-pandoc/tests/snapshots/native/definition-list-basic.qmd.snapshot

@@ -0,0 +1 @@
+[ DefinitionList [([Str "term", Space, Str "1"], [[Plain [Str "definition", Space, Str "1"]]]), ([Str "term", Space, Str "2"], [[Plain [Str "definition", Space, Str "2"]]])] ]

crates/quarto-markdown-pandoc/tests/snapshots/native/definition-list-complex-term.qmd

@@ -0,0 +1,6 @@
+::: {.definition-list}
+* **term with emphasis**
+  - definition for emphasized term
+* `code term`
+  - definition for code term
+:::

crates/quarto-markdown-pandoc/tests/snapshots/native/definition-list-complex-term.qmd.snapshot

@@ -0,0 +1 @@
+[ DefinitionList [([Strong [Str "term", Space, Str "with", Space, Str "emphasis"]], [[Plain [Str "definition", Space, Str "for", Space, Str "emphasized", Space, Str "term"]]]), ([Code ( "" , [] , [] ) "code term"], [[Plain [Str "definition", Space, Str "for", Space, Str "code", Space, Str "term"]]])] ]

crates/quarto-markdown-pandoc/tests/snapshots/native/definition-list-invalid-empty-div.qmd

@@ -0,0 +1,2 @@
+::: {.definition-list}
+:::

crates/quarto-markdown-pandoc/tests/snapshots/native/definition-list-invalid-empty-div.qmd.snapshot

@@ -0,0 +1 @@
+[ Div ( "" , ["definition-list"] , [] ) [] ]

crates/quarto-markdown-pandoc/tests/snapshots/native/definition-list-invalid-extra-blocks.qmd

@@ -0,0 +1,7 @@
+::: {.definition-list}
+* term
+
+  extra paragraph
+
+  - definition
+:::

crates/quarto-markdown-pandoc/tests/snapshots/native/definition-list-invalid-extra-blocks.qmd.snapshot

@@ -0,0 +1 @@
+[ Div ( "" , ["definition-list"] , [] ) [BulletList [[Para [Str "term"], Para [Str "extra", Space, Str "paragraph"], BulletList [[Plain [Str "definition"]]]]]] ]