From 7815dfd1efe344c3fba501cdda357e112b50590c Mon Sep 17 00:00:00 2001 From: Leynos Date: Sat, 19 Jul 2025 13:05:41 +0100 Subject: [PATCH 1/2] Clarify rayon usage in roadmap --- README.md | 71 +++++++++++++++++++---------- docs/parallel-processing-roadmap.md | 23 ++++++++++ 2 files changed, 71 insertions(+), 23 deletions(-) create mode 100644 docs/parallel-processing-roadmap.md diff --git a/README.md b/README.md index 926f3050..4404f0bb 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,13 @@ # mdtablefix -`mdtablefix` unb0rks and reflows Markdown tables so that each column has a uniform width. When the `--wrap` option is used, it also wraps paragraphs and list items to 80 columns. +`mdtablefix` unb0rks and reflows Markdown tables so that each column has a +uniform width. When the `--wrap` option is used, it also wraps paragraphs and +list items to 80 columns. -Hyphenated words are treated as indivisible during wrapping, so `very-long-word` will move to the next line intact rather than split at the hyphen. The tool ignores fenced code blocks and respects escaped pipes (`\|`), making it safe to use on Markdown with mixed content. +Hyphenated words are treated as indivisible during wrapping, so +`very-long-word` will move to the next line intact rather than split at the +hyphen. The tool ignores fenced code blocks and respects escaped pipes (`\|`), +making it safe to use on Markdown with mixed content. ## Installation @@ -10,7 +15,7 @@ Install via Cargo: Bash -``` +```bash cargo install mdtablefix ``` @@ -18,7 +23,7 @@ Or clone the repository and build from source: Bash -``` +```bash cargo install --path . ``` @@ -26,23 +31,32 @@ cargo install --path . Bash -``` +```bash mdtablefix [--wrap] [--renumber] [--breaks] [--ellipsis] [--in-place] [FILE...] ``` -- When one or more file paths are provided, the corrected tables are printed to stdout. +- When one or more file paths are provided, the corrected tables are printed to + stdout. - Use `--wrap` to reflow paragraphs and list items to 80 columns. -- Use `--renumber` to rewrite ordered lists with consistent sequential numbering. The renumbering logic correctly handles nested lists by tracking indentation (tabs are interpreted as four spaces) and restarts numbering after a list is interrupted by other content, such as a paragraph at a lower indentation level. +- Use `--renumber` to rewrite ordered lists with consistent sequential + numbering. The renumbering logic correctly handles nested lists by tracking + indentation (tabs are interpreted as four spaces) and restarts numbering + after a list is interrupted by other content, such as a paragraph at a lower + indentation level. -- Use `--breaks` to standardise thematic breaks to a line of 70 underscores (configurable via the `THEMATIC_BREAK_LEN` constant). +- Use `--breaks` to standardise thematic breaks to a line of 70 underscores + (configurable via the `THEMATIC_BREAK_LEN` constant). -- Use `--ellipsis` to replace groups of three dots (`...`) with the ellipsis character (`…`). Longer runs are processed left-to-right, so any leftover dots are preserved. +- Use `--ellipsis` to replace groups of three dots (`...`) with the ellipsis + character (`…`). Longer runs are processed left-to-right, so any leftover + dots are preserved. - Use `--in-place` to modify files in-place. -- If no files are specified, input is read from stdin and output is written to stdout. +- If no files are specified, input is read from stdin and output is written to + stdout. ### Example: Table Reflowing @@ -50,7 +64,7 @@ Before: Markdown -``` +```markdown |Character|Catchphrase|Pizza count| |---|---|---| |Speedy Cerviche|Here come the Samurai Pizza Cats!|lots| |Guido Anchovy|Slice and dice!|tons| |Polly Esther|Cat fight!|many| @@ -60,7 +74,7 @@ After running `mdtablefix`: Markdown -``` +```markdown | Character | Catchphrase | Pizza count | | --------------- | --------------------------------- | ----------- | | Speedy Cerviche | Here come the Samurai Pizza Cats! | lots | @@ -74,7 +88,7 @@ Before: Markdown -``` +```markdown 1. The Big Cheese's evil plans. 4. Jerry Atric's schemes. @@ -90,7 +104,7 @@ After running `mdtablefix --renumber`: Markdown -``` +```markdown 1. The Big Cheese's evil plans. 2. Jerry Atric's schemes. @@ -104,11 +118,12 @@ A brief intermission for pizza. ## Library usage -The crate provides helper functions for embedding the table reflow logic in your own Rust project: +The crate provides helper functions for embedding the table reflow logic in +your own Rust project: Rust -``` +```rust use mdtablefix::{process_stream_opts, rewrite}; use std::path::Path; @@ -125,26 +140,36 @@ fn main() -> std::io::Result<()> { } ``` -- `process_stream_opts(lines: &[String], wrap: bool, ellipsis: bool) -> Vec` rewrites tables in memory, with optional paragraph wrapping and ellipsis substitution. +- `process_stream_opts(lines: &[String], wrap: bool, ellipsis: bool) -> \ + Vec` rewrites tables in memory, with optional paragraph wrapping and + ellipsis substitution. -- `rewrite(path: &Path) -> std::io::Result<()>` modifies a Markdown file on disk in-place. +- `rewrite(path: &Path) -> std::io::Result<()>` modifies a Markdown file on + disk in-place. ## HTML table support -`mdtablefix` recognises basic HTML `` elements embedded in Markdown. These are converted to Markdown in a preprocessing stage using `convert_html_tables`, prior to reflow. +`mdtablefix` recognises basic HTML `
` elements embedded in Markdown. +These are converted to Markdown in a preprocessing stage using +`convert_html_tables`, prior to reflow. -Only simple tables composed of ``, ``, `
`, and `` tags are supported. Tag case and attributes are ignored. After conversion, they are reformatted alongside regular Markdown tables. +Only simple tables composed of `
`, and `` tags are supported. +Tag case and attributes are ignored. After conversion, they are reformatted +alongside regular Markdown tables. See [HTML table support for more details](docs/html-table-support.md). ## Module structure -For an overview of how the crate's internal modules relate to each other, see [Module relationships](docs/module-relationships.md). +For an overview of how the crate's internal modules relate to each other, see +[Module relationships](docs/module-relationships.md). ## Testing -The test suite is structured using the `rstest` crate. See [Rust testing with rstest fixtures](docs/rust-testing-with-rstest-fixtures.md) for details. +The test suite is structured using the `rstest` crate. See [Rust testing with +rstest fixtures](docs/rust-testing-with-rstest-fixtures.md) for details. ## License -This project is licensed under the ISC License. See the [LICENSE](LICENSE) file for full details. +This project is licensed under the ISC License. See the [LICENSE](LICENSE) file +for full details. diff --git a/docs/parallel-processing-roadmap.md b/docs/parallel-processing-roadmap.md new file mode 100644 index 00000000..4ab98234 --- /dev/null +++ b/docs/parallel-processing-roadmap.md @@ -0,0 +1,23 @@ +# Roadmap for Parallel File Processing + +The command-line tool currently processes input files sequentially. The steps +below outline the work required to allow concurrent processing while preserving +serial output order. + +- [ ] **Adopt `rayon` for concurrency** + - Use `rayon` thread pools to spawn work for each file path. + - Ensure the approach integrates cleanly with existing modules. +- [ ] **Add chosen crate to `Cargo.toml`** + - Pin an explicit version and document the decision in `docs/`. +- [ ] **Refactor `main.rs` to launch parallel tasks** + - Spawn a worker for each file path using the concurrency crate. + - Maintain a list of handles so outputs can be gathered in order. +- [ ] **Collect results sequentially** + - Await or join handles in the same order the files were supplied. + - Print each processed file or error message before moving to the next. +- [ ] **Extend tests for parallel execution** + - Use `rstest` to verify that processing many files yields correct results. + - Add tests exercising error handling when some paths are invalid. +- [ ] **Update documentation** + - Document the new flags or behaviour in `README.md` and module docs. + - Note any concurrency caveats or performance implications. From 9ddb933bb897384760516875acb963f991de2c9f Mon Sep 17 00:00:00 2001 From: Leynos Date: Sun, 20 Jul 2025 23:45:35 +0100 Subject: [PATCH 2/2] Update README.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4404f0bb..626daec3 100644 --- a/README.md +++ b/README.md @@ -118,9 +118,8 @@ A brief intermission for pizza. ## Library usage -The crate provides helper functions for embedding the table reflow logic in -your own Rust project: - +The crate exposes helper functions for embedding the table-reflow logic in +Rust projects: Rust ```rust