Text::Diff::Table(3)

🌸 Text::Diff::Table — the manual, but make it cute 🌸

okay so bestie, you found Text::Diff::Table(3), which is the absolute moment — it's a Text::Diff plugin that makes your diffs render as pretty little tables instead of boring raw text. let me walk you through it 💖

---

✨ NAME ✨

Text::Diff::Table — a Text::Diff plugin that generates "table" format output. periodt.

---

🦋 SYNOPSIS 🦋

use Text::Diff;

diff \@a, $b, { STYLE => "Table" };

that's it, that's the whole vibe check. 👑

---

🎀 DESCRIPTION 🎀

so Text::Diff::Table is a plugin output formatter for Text::Diff that generates "table" style diffs — and honestly? it's giving spreadsheet but make it fashion:

+--+----------------------------------+--+------------------------------+
|  |../Test-Differences-0.2/MANIFEST  |  |../Test-Differences/MANIFEST  |
|  |Thu Dec 13 15:38:49 2001          |  |Sat Dec 15 02:09:44 2001      |
+--+----------------------------------+--+------------------------------+
|  |                                  * 1|Changes                       *
| 1|Differences.pm                    | 2|Differences.pm                |
| 2|MANIFEST                          | 3|MANIFEST                      |
|  |                                  * 4|MANIFEST.SKIP                 *
| 3|Makefile.PL                       | 5|Makefile.PL                   |
|  |                                  * 6|t/00escape.t                  *
| 4|t/00flatten.t                     | 7|t/00flatten.t                 |
| 5|t/01text_vs_data.t                | 8|t/01text_vs_data.t            |
| 6|t/10test.t                        | 9|t/10test.t                    |
+--+----------------------------------+--+------------------------------+

and the way this format also goes to some pains to highlight "invisible" characters on differing elements by selectively escaping whitespace? obsessed. 🫶

here's the tea: each element is split into three segments (leading whitespace, body, trailing whitespace). and if the whitespace differs in a segment, that segment gets whitespace escaped. iykyk. ✨

okay here's an example of the selective whitespace in action:

+--+--------------------------+--------------------------+
|  |demo_ws_A.txt             |demo_ws_B.txt             |
|  |Fri Dec 21 08:36:32 2001  |Fri Dec 21 08:36:50 2001  |
+--+--------------------------+--------------------------+
| 1|identical                 |identical                 |
* 2|        spaced in         |        also spaced in    *
* 3|embedded space            |embedded        tab       *
| 4|identical                 |identical                 |
* 5|        spaced in         |\ttabbed in               *
* 6|trailing spaces\s\s\n     |trailing tabs\t\t\n       *
| 7|identical                 |identical                 |
* 8|lf line\n                 |crlf line\r\n             *
* 9|embedded ws               |embedded\tws              *
+--+--------------------------+--------------------------+

and here's why those lines do or do not have whitespace escaped, because i know you were about to ask:

• lines 1, 4, 7 don't differ, no need.
• lines 2, 3 differ in non-whitespace, no need.
• lines 5, 6, 8, 9 all have subtle ws changes.

and whether or not line 3 should have that tab character escaped is a judgement call; so far it's choosing not to. lowkey iconique of it. 💅

---

🌈 UNICODE 🌈

to output the raw unicode chracters, consult the documentation of Text::Diff::Config. you can set the "DIFF_OUTPUT_UNICODE" environment variable to 1 to output it from the command line. for more information, consult this bug: <https://rt.cpan.org/Ticket/Display.html?id=54214> . 🦋

---

💀 LIMITATIONS 💀

ngl bestie, these are the real ones — read them before you commit. 😭

• table formatting requires buffering the entire diff in memory in order to calculate column widths. so this format should only be used for smaller diffs. fr fr, don't come for it with a giant diff.
• assumes tab stops every 8 characters, as $DIETY intended.
• assumes all character codes >= 127 need to be escaped as hex codes, ie that the user's terminal is ASCII, and not even "high bit ASCII", capable. this can be made an option when the need arises.
• assumes that control codes (character codes 0..31) that don't have slash-letter escapes ("\n", "\r", etc) in Perl are best presented as hex escapes ("\x01") instead of octal ("\001") or control-code ("\cA") escapes.

---

👑 AUTHOR 👑

Barrie Slaymaker <barries@slaysys.com>

---

🌸 LICENSE 🌸

Copyright 2001 Barrie Slaymaker, All Rights Reserved.

you may use this software under the terms of the GNU public license, any version, or the Artistic license.

---

and that's the whole page bestie, no cap 🧚

cute lil sign-off: this beauty is from perl v5.42.0, dated 2017-08-19, and it's Text::Diff::Table(3) — go forth and make your diffs iconic 💜