feat(to): table also for xlsx and ods (#3580)

jqnatividad · claude · Copilot · web-flow · commit 09c6e3763f93 · 2026-03-05T07:56:16.000-05:00
* feat(to): Also support --table for xlsx/ods and validate names

Add examples to the xlsx/ods help showing --table usage and stdin support. Extend the --table help text to clarify it applies to postgres/sqlite and xlsx/ods and document name rules and limits. Change validation so --table is disallowed for datapackage but allowed for xlsx/ods; add sheet-name checks (xlsx max 31 chars, disallow \ / * [ ] : ?) while keeping postgres/sqlite identifier checks (start with letter/underscore, alnum/_ only, max 63). Wire up apply_table_rename when processing xlsx and ods inputs so provided table/sheet names are applied during conversion.

* tests(to): add tests for to --table for xlsx/ods

Co-Authored-By: Claude &lt;claude@users.noreply.github.com&gt;

* fix(to): enforce 31-char sheet name limit for ODS and use char count

- Apply the 31-character sheet name limit to both xlsx and ods (previously
  xlsx only), matching ODF spec conventions
- Use chars().count() instead of len() for character-based length checking,
  so multi-byte UTF-8 names aren't rejected prematurely
- Add test for ODS sheet name exceeding 31 characters
- Update help text to clarify limit applies to both formats

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

* tests(to): improve to --table test reliability

- Fix xlsx too_long test to use "a".repeat(32) instead of "a]".repeat(16)
  which contained forbidden chars, masking the length validation check
- Add output file existence assertions to xlsx and ods happy-path tests
  to ensure the command actually produces the expected file

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

* docs(to): update help md and TOC

* typo: ODF -&gt; ODS

* refactor(to): addl xlsx/ods validation per Copilot review

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* tests(to): tighten tests per Copilot low-confidence suggestion

* fix(to): avoid double command execution in xlsx/ods happy path tests

`assert_success` and `output` both call `cmd.output()`, running the
command twice. Replace with a single `output()` call followed by an
inline status assertion, eliminating redundant execution and potential
side-effect issues from the second run.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude &lt;claude@users.noreply.github.com&gt;
Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/docs/help/TableOfContents.md b/docs/help/TableOfContents.md
@@ -84,7 +84,7 @@
 🧠: expensive operations are memoized with available inter-session Redis/Disk caching for fetch commands.  
 🗄️: [Extended input support](../../README.md#extended-input-support).  
 🗃️: [Limited Extended input support](../../README.md#limited-extended-input-support).  
-🐻‍❄️: command powered/accelerated by [![polars 0.53.0:802550b](https://img.shields.io/badge/polars-0.53.0:802550b-blue?logo=polars  
+🐻‍❄️: command powered/accelerated by [![polars 0.53.0:9f1a742](https://img.shields.io/badge/polars-0.53.0:9f1a742-blue?logo=polars  
 )](https://github.com/pola-rs/polars/releases/tag/rs-0.53.0) vectorized query engine.  
 🤖: command uses Natural Language Processing or Generative AI.  
 🏎️: multithreaded and/or faster when an index (📇) is available.  
diff --git a/docs/help/to.md b/docs/help/to.md
@@ -135,6 +135,16 @@ Load files listed in the 'ourdata.infile-list' into xlsx file.
 qsv to xlsx output.xlsx ourdata.infile-list
 ```
 
+Load a single CSV into xlsx with a custom sheet name.
+```console
+qsv to xlsx output.xlsx --table "Sales Data" file1.csv
+```
+
+Load from stdin with a custom sheet name.
+```console
+cat data.csv | qsv to xlsx output.xlsx --table "Monthly Report" -
+```
+
 ### ODS
 
 Convert to new ODS (Open Document Spreadsheet) file.
@@ -156,6 +166,16 @@ Load files listed in the 'ourdata.infile-list' into ODS file.
 qsv to ods output.ods ourdata.infile-list
 ```
 
+Load a single CSV into ODS with a custom sheet name.
+```console
+qsv to ods output.ods --table "Sales Data" file1.csv
+```
+
+Load from stdin with a custom sheet name.
+```console
+cat data.csv | qsv to ods output.ods --table "Monthly Report" -
+```
+
 ### Data Package
 
 Generate a datapackage, which contains stats and information about what is in the CSV files.
@@ -215,7 +235,7 @@ qsv to --help
 | &nbsp;`-d,`<br>`--drop`&nbsp; | flag | Drop tables before loading new data into them (postgres/sqlite only). |  |
 | &nbsp;`-e,`<br>`--evolve`&nbsp; | flag | If loading into existing db, alter existing tables so that new data will load. (postgres/sqlite only). |  |
 | &nbsp;`-i,`<br>`--pipe`&nbsp; | flag | Adjust output format for piped data (omits row counts and field format columns). |  |
-| &nbsp;`-t,`<br>`--table`&nbsp; | string | Use this as the table name (postgres/sqlite only). Overrides the default table name derived from the input filename. When reading from stdin, the default table name is "stdin". Only valid with a single input file. Table name must start with a letter or underscore, and contain only alphanumeric characters and underscores. |  |
+| &nbsp;`-t,`<br>`--table`&nbsp; | string | Use this as the table/sheet name (postgres/sqlite/xlsx/ods). Overrides the default name derived from the input filename. When reading from stdin, the default table name is "stdin". Only valid with a single input file. For postgres/sqlite: must start with a letter or underscore, contain only alphanumeric characters and underscores (max 63). For xlsx/ods: used as sheet name (max 31 chars, cannot contain \ / * [ ] : ?). |  |
 | &nbsp;`-p,`<br>`--separator`&nbsp; | string | For xlsx, use this character to help truncate xlsx sheet names. Defaults to space. |  |
 | &nbsp;`-A,`<br>`--all-strings`&nbsp; | flag | Convert all fields to strings. |  |
 | &nbsp;`-j,`<br>`--jobs`&nbsp; | string | The number of jobs to run in parallel. When not set, the number of jobs is set to the number of CPUs detected. |  |
diff --git a/src/cmd/to.rs b/src/cmd/to.rs
@@ -109,6 +109,14 @@ Load files listed in the 'ourdata.infile-list' into xlsx file.
 
   $ qsv to xlsx output.xlsx ourdata.infile-list
 
+Load a single CSV into xlsx with a custom sheet name.
+
+  $ qsv to xlsx output.xlsx --table "Sales Data" file1.csv
+
+Load from stdin with a custom sheet name.
+
+  $ cat data.csv | qsv to xlsx output.xlsx --table "Monthly Report" -
+
 ODS
 ===
 Convert to new ODS (Open Document Spreadsheet) file.
@@ -129,6 +137,14 @@ Load files listed in the 'ourdata.infile-list' into ODS file.
 
   $ qsv to ods output.ods ourdata.infile-list
 
+Load a single CSV into ODS with a custom sheet name.
+
+  $ qsv to ods output.ods --table "Sales Data" file1.csv
+
+Load from stdin with a custom sheet name.
+
+  $ cat data.csv | qsv to ods output.ods --table "Monthly Report" -
+
 DATA PACKAGE
 ============
 Generate a datapackage, which contains stats and information about what is in the CSV files.
@@ -175,12 +191,14 @@ To options:
   -d, --drop              Drop tables before loading new data into them (postgres/sqlite only).
   -e, --evolve            If loading into existing db, alter existing tables so that new data will load. (postgres/sqlite only).
   -i, --pipe              Adjust output format for piped data (omits row counts and field format columns).
-  -t, --table <name>      Use this as the table name (postgres/sqlite only).
-                          Overrides the default table name derived from the input filename.
+  -t, --table <name>      Use this as the table/sheet name (postgres/sqlite/xlsx/ods).
+                          Overrides the default name derived from the input filename.
                           When reading from stdin, the default table name is "stdin".
-                          Only valid with a single input file. Table name must start with
-                          a letter or underscore, and contain only alphanumeric characters
-                          and underscores.
+                          Only valid with a single input file.
+                          For postgres/sqlite: must start with a letter or underscore,
+                          contain only alphanumeric characters and underscores (max 63).
+                          For xlsx/ods: used as sheet name (max 31 chars,
+                          cannot contain \ / * [ ] : ?).
   -p, --separator <arg>   For xlsx, use this character to help truncate xlsx sheet names.
                           Defaults to space.
   -A, --all-strings       Convert all fields to strings.
@@ -276,29 +294,47 @@ pub fn run(argv: &[&str]) -> CliResult<()> {
 
     // validate --table option
     if let Some(ref table_name) = args.flag_table {
-        if args.cmd_xlsx || args.cmd_ods || args.cmd_datapackage {
+        if args.cmd_datapackage {
             return fail_incorrectusage_clierror!(
-                "--table can only be used with postgres or sqlite subcommands."
+                "--table cannot be used with the datapackage subcommand."
             );
         }
         if table_name.is_empty() {
             return fail_incorrectusage_clierror!("--table name must not be empty.");
         }
-        if !table_name.starts_with(|c: char| c.is_alphabetic() || c == '_') {
-            return fail_incorrectusage_clierror!(
-                "--table name must start with a letter or underscore."
-            );
-        }
-        if !table_name.chars().all(|c| c.is_alphanumeric() || c == '_') {
-            return fail_incorrectusage_clierror!(
-                "--table name must contain only alphanumeric characters and underscores."
-            );
-        }
-        // PostgreSQL limits identifiers to 63 characters; cap table names accordingly
-        if table_name.len() > 63 {
-            return fail_incorrectusage_clierror!(
-                "--table name must not exceed 63 characters (PostgreSQL identifier limit)."
-            );
+        if args.cmd_xlsx || args.cmd_ods {
+            // xlsx/ods sheet name validation
+            // Both xlsx (Excel) and ods (ODS) enforce a 31-character limit on sheet names
+            if table_name.chars().count() > 31 {
+                return fail_incorrectusage_clierror!(
+                    "--table sheet name must not exceed 31 characters for xlsx/ods."
+                );
+            }
+            // Also ensure the sheet name is valid when used as a filesystem filename
+            // (Windows-invalid filename characters: < > : \" / \\ | ? *)
+            if table_name.contains(&['\\', '/', '*', '[', ']', ':', '?', '<', '>', '"', '|'][..]) {
+                return fail_incorrectusage_clierror!(
+                    "--table sheet name cannot contain \\ / * [ ] : ? < > \" | characters."
+                );
+            }
+        } else {
+            // postgres/sqlite table name validation
+            if !table_name.starts_with(|c: char| c.is_alphabetic() || c == '_') {
+                return fail_incorrectusage_clierror!(
+                    "--table name must start with a letter or underscore."
+                );
+            }
+            if !table_name.chars().all(|c| c.is_alphanumeric() || c == '_') {
+                return fail_incorrectusage_clierror!(
+                    "--table name must contain only alphanumeric characters and underscores."
+                );
+            }
+            // PostgreSQL limits identifiers to 63 characters; cap table names accordingly
+            if table_name.len() > 63 {
+                return fail_incorrectusage_clierror!(
+                    "--table name must not exceed 63 characters (PostgreSQL identifier limit)."
+                );
+            }
         }
     }
 
@@ -335,13 +371,15 @@ pub fn run(argv: &[&str]) -> CliResult<()> {
     } else if args.cmd_xlsx {
         debug!("converting to Excel XLSX");
         arg_input = process_input(arg_input, &tmpdir, EMPTY_STDIN_ERRMSG)?;
+        apply_table_rename(&args.flag_table, &mut arg_input, &tmpdir)?;
 
         output =
             csvs_to_xlsx_with_options(args.arg_xlsx.expect("checked above"), arg_input, options)?;
         debug!("conversion to Excel XLSX complete");
     } else if args.cmd_ods {
         debug!("converting to ODS");
         arg_input = process_input(arg_input, &tmpdir, EMPTY_STDIN_ERRMSG)?;
+        apply_table_rename(&args.flag_table, &mut arg_input, &tmpdir)?;
 
         output =
             csvs_to_ods_with_options(args.arg_ods.expect("checked above"), arg_input, options)?;
diff --git a/tests/test_to.rs b/tests/test_to.rs
@@ -531,44 +531,154 @@ fn to_ods_dir() {
 }
 
 #[test]
-fn to_table_error_xlsx() {
-    // --table should fail with xlsx subcommand
-    let wrk = Workdir::new("to_table_error_xlsx");
+fn to_table_xlsx_happy_path() {
+    // --table with xlsx should use the custom sheet name
+    let wrk = Workdir::new("to_table_xlsx_happy");
+    wrk.create(
+        "in.csv",
+        vec![svec!["city", "state"], svec!["Boston", "MA"]],
+    );
+
+    let xlsx_file = wrk.path("test.xlsx").to_string_lossy().to_string();
+    let mut cmd = wrk.command("to");
+    cmd.arg("xlsx")
+        .arg("--table")
+        .arg("My Sheet")
+        .arg(&xlsx_file)
+        .arg("in.csv");
+
+    let output = wrk.output(&mut cmd);
+    assert!(
+        output.status.success(),
+        "Command failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("My Sheet"),
+        "Expected sheet name 'My Sheet' in output, got: {stdout}"
+    );
+    assert!(
+        wrk.path("test.xlsx").exists(),
+        "Expected output file test.xlsx to exist"
+    );
+}
+
+#[test]
+fn to_table_error_xlsx_invalid_chars() {
+    // --table with invalid sheet name characters should fail for xlsx
+    let wrk = Workdir::new("to_table_error_xlsx_chars");
     wrk.create("in.csv", vec![svec!["col1"], svec!["a"]]);
 
     let xlsx_file = wrk.path("test.xlsx").to_string_lossy().to_string();
     let mut cmd = wrk.command("to");
     cmd.arg("xlsx")
         .arg("--table")
-        .arg("custom_name")
+        .arg("bad[name")
         .arg(xlsx_file)
         .arg("in.csv");
 
     let stderr = wrk.output_stderr(&mut cmd);
     assert!(
-        stderr.contains("--table can only be used with postgres or sqlite"),
-        "Expected unsupported subcommand error, got: {stderr}"
+        stderr.contains("sheet name cannot contain"),
+        "Expected invalid chars error, got: {stderr}"
+    );
+}
+
+#[test]
+fn to_table_error_xlsx_too_long() {
+    // --table with sheet name > 31 chars should fail for xlsx
+    let wrk = Workdir::new("to_table_error_xlsx_long");
+    wrk.create("in.csv", vec![svec!["col1"], svec!["a"]]);
+
+    let xlsx_file = wrk.path("test.xlsx").to_string_lossy().to_string();
+    let mut cmd = wrk.command("to");
+    cmd.arg("xlsx")
+        .arg("--table")
+        .arg("a".repeat(32))
+        .arg(xlsx_file)
+        .arg("in.csv");
+
+    let stderr = wrk.output_stderr(&mut cmd);
+    assert!(
+        stderr.contains("must not exceed 31 characters"),
+        "Expected length error, got: {stderr}"
     );
 }
 
 #[test]
-fn to_table_error_ods() {
-    // --table should fail with ods subcommand
-    let wrk = Workdir::new("to_table_error_ods");
+fn to_table_error_ods_too_long() {
+    // --table with sheet name > 31 chars should fail for ods
+    let wrk = Workdir::new("to_table_error_ods_long");
     wrk.create("in.csv", vec![svec!["col1"], svec!["a"]]);
 
     let ods_file = wrk.path("test.ods").to_string_lossy().to_string();
     let mut cmd = wrk.command("to");
     cmd.arg("ods")
         .arg("--table")
-        .arg("custom_name")
+        .arg("a".repeat(32))
         .arg(ods_file)
         .arg("in.csv");
 
     let stderr = wrk.output_stderr(&mut cmd);
     assert!(
-        stderr.contains("--table can only be used with postgres or sqlite"),
-        "Expected unsupported subcommand error, got: {stderr}"
+        stderr.contains("must not exceed 31 characters"),
+        "Expected length error, got: {stderr}"
+    );
+}
+
+#[test]
+fn to_table_ods_happy_path() {
+    // --table with ods should use the custom sheet name
+    let wrk = Workdir::new("to_table_ods_happy");
+    wrk.create(
+        "in.csv",
+        vec![svec!["city", "state"], svec!["Boston", "MA"]],
+    );
+
+    let ods_file = wrk.path("test.ods").to_string_lossy().to_string();
+    let mut cmd = wrk.command("to");
+    cmd.arg("ods")
+        .arg("--table")
+        .arg("My Sheet")
+        .arg(&ods_file)
+        .arg("in.csv");
+
+    let output = wrk.output(&mut cmd);
+    assert!(
+        output.status.success(),
+        "Command failed: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("My Sheet"),
+        "Expected sheet name 'My Sheet' in output, got: {stdout}"
+    );
+    assert!(
+        wrk.path("test.ods").exists(),
+        "Expected output file test.ods to exist"
+    );
+}
+
+#[test]
+fn to_table_error_ods_invalid_chars() {
+    // --table with invalid sheet name characters should fail for ods
+    let wrk = Workdir::new("to_table_error_ods_chars");
+    wrk.create("in.csv", vec![svec!["col1"], svec!["a"]]);
+
+    let ods_file = wrk.path("test.ods").to_string_lossy().to_string();
+    let mut cmd = wrk.command("to");
+    cmd.arg("ods")
+        .arg("--table")
+        .arg("bad:name")
+        .arg(ods_file)
+        .arg("in.csv");
+
+    let stderr = wrk.output_stderr(&mut cmd);
+    assert!(
+        stderr.contains("sheet name cannot contain"),
+        "Expected invalid chars error, got: {stderr}"
     );
 }
 
@@ -588,7 +698,7 @@ fn to_table_error_datapackage() {
 
     let stderr = wrk.output_stderr(&mut cmd);
     assert!(
-        stderr.contains("--table can only be used with postgres or sqlite"),
+        stderr.contains("--table cannot be used with the datapackage subcommand"),
         "Expected unsupported subcommand error, got: {stderr}"
     );
 }
