✨ feat(cli): auto-expand table dicts to markdown nodes in CLI output

harehare · harehare · commit 3649a2fbd405 · 2026-03-24T15:30:33.000+09:00
Table objects returned from table::tables() are now automatically
expanded to markdown nodes when output via the CLI, matching the
existing behavior for section dicts. Users can output table objects
directly without calling table::to_markdown().

Also fixes a bug in table::add_row() where new cells were assigned
the same row index as existing data rows due to missing +1 offset
for the header row.
diff --git a/crates/mq-lang/modules/table.mq b/crates/mq-lang/modules/table.mq
@@ -62,7 +62,7 @@ def add_row(table, row):
   else: do
       var i = 0
       | let cells = foreach (cell, row):
-              to_md_table_cell(cell, len(table[:rows]), i)
+              to_md_table_cell(cell, len(table[:rows]) + 1, i)
               | i += 1
             end
       | set(table, :rows, table[:rows] + [cells])
diff --git a/crates/mq-run/src/cli.rs b/crates/mq-run/src/cli.rs
@@ -736,7 +736,7 @@ impl Cli {
         let type_key = mq_lang::Ident::new("type");
         matches!(
             map.get(&type_key),
-            Some(mq_lang::RuntimeValue::Symbol(s)) if matches!(s.as_str().as_str(), "section")
+            Some(mq_lang::RuntimeValue::Symbol(s)) if matches!(s.as_str().as_str(), "section" | "table")
         )
     }
 
@@ -760,6 +760,21 @@ impl Cli {
                     }
                     Some(nodes)
                 }
+                "table" => {
+                    // Reconstruct table nodes in the same order as table::to_markdown():
+                    // header cells + align row + flattened data rows
+                    let mut nodes = Vec::new();
+                    if let Some(header) = map.get(&mq_lang::Ident::new("header")) {
+                        Self::collect_markdown_nodes(header, &mut nodes);
+                    }
+                    if let Some(align) = map.get(&mq_lang::Ident::new("align")) {
+                        Self::collect_markdown_nodes(align, &mut nodes);
+                    }
+                    if let Some(rows) = map.get(&mq_lang::Ident::new("rows")) {
+                        Self::collect_markdown_nodes(rows, &mut nodes);
+                    }
+                    Some(nodes)
+                }
                 // To add a new expandable type: add a match arm here.
                 _ => None,
             },
diff --git a/crates/mq-run/tests/integration_tests.rs b/crates/mq-run/tests/integration_tests.rs
@@ -141,6 +141,21 @@ In {year}, the snowfall was above average.
     "# Introduction\n\nBody text.\n",
     Some("Body text.\n")
 )]
+#[case::table_auto_expand(
+    vec!["--unbuffered", "-A", r#"import "table" | table::tables()"#],
+    "| Name | Age |\n| ---- | --- |\n| Alice | 30 |\n| Bob | 25 |\n",
+    Some("|Name|Age|\n|---|---|\n|Alice|30|\n|Bob|25|\n")
+)]
+#[case::table_auto_expand_first(
+    vec!["--unbuffered", "-A", r#"import "table" | table::tables() | first()"#],
+    "| Name | Age |\n| ---- | --- |\n| Alice | 30 |\n| Bob | 25 |\n",
+    Some("|Name|Age|\n|---|---|\n|Alice|30|\n|Bob|25|\n")
+)]
+#[case::table_auto_expand_add_row(
+    vec!["--unbuffered", "-A", r#"import "table" | table::tables() | first() | table::add_row(["Charlie", "35"])"#],
+    "| Name | Age |\n| ---- | --- |\n| Alice | 30 |\n",
+    Some("|Name|Age|\n|---|---|\n|Alice|30|\n|Charlie|35|\n")
+)]
 #[case::capture_named_groups(
     vec!["--unbuffered", "-I", "text", r#"capture("(?P<year>\\d{4})-(?P<month>\\d{2})-(?P<day>\\d{2})")"#],
     "2024-01-15",
diff --git a/docs/books/src/start/example.md b/docs/books/src/start/example.md
@@ -391,6 +391,88 @@ Use the tool like this.
 
 **Output**: `["Introduction", "Usage"]`
 
+## Table Operations
+
+The table module provides functions for extracting and transforming Markdown tables.
+
+> **Note**: Table functions need all document nodes at once. Use `-A` on the command line, or `nodes` in inline queries. Unlike the section module, `import "table"` must be written explicitly.
+
+### Extract Tables
+
+**`-A` flag** (command line):
+
+```bash
+$ mq -A 'import "table" | table::tables()' README.md
+```
+
+**`import` + `nodes`** (inline query or script):
+
+```mq
+import "table"
+| nodes
+| table::tables()
+```
+
+Table objects are automatically expanded to Markdown nodes in CLI output, so `to_markdown()` is not needed.
+
+> **Note (code usage)**: When using the table module from Rust or other code (not the CLI), table objects are plain dicts and must be explicitly converted with `table::to_markdown()`:
+>
+> ```mq
+> import "table"
+> | nodes
+> | table::tables()
+> | table::to_markdown()
+> ```
+
+**Input example**:
+
+```markdown
+| Name  | Age |
+| ----- | --- |
+| Alice | 30  |
+| Bob   | 25  |
+```
+
+**Output**:
+
+```markdown
+| Name  | Age |
+| ----- | --- |
+| Alice | 30  |
+| Bob   | 25  |
+```
+
+### Add a Row to a Table
+
+```bash
+$ mq -A 'import "table" | table::tables() | first() | table::add_row(["Charlie", "35"])' README.md
+```
+
+**Input example**:
+
+```markdown
+| Name  | Age |
+| ----- | --- |
+| Alice | 30  |
+```
+
+**Output**:
+
+```markdown
+| Name    | Age |
+| ------- | --- |
+| Alice   | 30  |
+| Charlie | 35  |
+```
+
+### Convert Table to CSV
+
+```bash
+$ mq -A 'import "table" | table::tables() | first() | table::to_csv()' README.md
+```
+
+**Output**: Returns the table as a CSV string.
+
 ## Custom Functions and Programming
 
 ### Define Custom Function
