tessella 0.3.0

data/doc/table.md

@@ -0,0 +1,347 @@
+# Tables
+
+`table` draws rows of text as a framed table, sized to its content,
+with numbers right-aligned.
+
+```ruby
+Tessella.table(rows, header: true, style: nil, ascii: false,
+               align: nil, title: nil, width: nil, min_width: 4,
+               color: false)                     # => Block
+Tessella::Table.parse(text, tsv: false)          # => Array of rows
+```
+
+```text
+tessella table [--tsv] [--no-header] [--style S] [--ascii]
+               [--align SPEC] [--title T] [--max-width N] [file]
+```
+
+## Input
+
+`rows` is an Array of Arrays of Strings or numbers, the first row the
+header unless `header: false`. A number is drawn as written (`12`,
+`7.5`), and a column of them right-aligns; any other value is refused
+by its position: "row 2, column 1: a cell must be a String or a
+number: nil". `Table.parse` reads CSV with RFC 4180 quoting
+(a quoted field may hold commas, doubled quotes and newlines), or
+tab-separated text with `tsv: true`. The command line reads CSV by
+default and TSV with `--tsv`.
+
+```text
+$ cat kinds.csv
+kind,canvas,notes
+line,braille,"joins points, one series per column"
+bar,none,"negative values split at zero"
+stem,none,"back-to-back with two columns"
+```
+
+```text
+$ tessella table kinds.csv
+┌──────┬─────────┬─────────────────────────────────────┐
+│ kind │ canvas  │ notes                               │
+├──────┼─────────┼─────────────────────────────────────┤
+│ line │ braille │ joins points, one series per column │
+│ bar  │ none    │ negative values split at zero       │
+│ stem │ none    │ back-to-back with two columns       │
+└──────┴─────────┴─────────────────────────────────────┘
+```
+
+A column whose every body cell is a number is right-aligned:
+
+```text
+$ tessella table langs.csv
+┌──────┬─────┐
+│ lang │ loc │
+├──────┼─────┤
+│ ruby │  12 │
+│ c    │  30 │
+│ rust │ 7.5 │
+└──────┴─────┘
+```
+
+`--no-header` draws every row as body:
+
+```text
+$ tessella table --tsv --no-header sizes.tsv
+┌──────┬──────┐
+│ name │ size │
+│ lib  │ 7876 │
+│ test │ 5120 │
+└──────┴──────┘
+```
+
+## Alignment and title
+
+`--align` takes one letter per column, `l`, `r` or `c`; the library
+also takes an Array of `:left`, `:right`, `:center`. `--title` adds a
+row above the header, centred across the table.
+
+```text
+$ tessella table --title Kinds --align lcr kinds.csv
+┌──────────────────────────────────────────────────────┐
+│                        Kinds                         │
+├──────┬─────────┬─────────────────────────────────────┤
+│ kind │ canvas  │                               notes │
+├──────┼─────────┼─────────────────────────────────────┤
+│ line │ braille │ joins points, one series per column │
+│ bar  │  none   │       negative values split at zero │
+│ stem │  none   │       back-to-back with two columns │
+└──────┴─────────┴─────────────────────────────────────┘
+```
+
+## Styles
+
+`light` (the default), `heavy`, `double`, `rounded`, the four
+dashed ones (`dashed`, `dashed_fine`, `heavy_dashed`,
+`heavy_dashed_fine`), the two mixed doubles `double_h` and
+`double_v`, `ascii`, `minimal` (dividers only, no outer frame) and
+`markdown` (a GitHub pipe table, ready to paste). The mixed doubles
+bring their own tees, `╤ ╧ ╞ ╪ ╡` and `╥ ╨ ╟ ╫ ╢`:
+
+```text
+$ tessella table --style double_v langs.csv
+╓──────╥─────╖
+║ lang ║ loc ║
+╟──────╫─────╢
+║ ruby ║  12 ║
+║ c    ║  30 ║
+║ rust ║ 7.5 ║
+╙──────╨─────╜
+```
+
+```text
+$ tessella table --style minimal kinds.csv
+       ╷         ╷
+  kind │ canvas  │ notes
+╶──────┼─────────┼─────────────────────────────────────╴
+  line │ braille │ joins points, one series per column
+  bar  │ none    │ negative values split at zero
+  stem │ none    │ back-to-back with two columns
+       ╵         ╵
+```
+
+```text
+$ tessella table --style markdown kinds.csv
+| kind | canvas  | notes                               |
+|------|---------|-------------------------------------|
+| line | braille | joins points, one series per column |
+| bar  | none    | negative values split at zero       |
+| stem | none    | back-to-back with two columns       |
+```
+
+```text
+$ tessella table --style ascii kinds.csv
++------+---------+-------------------------------------+
+| kind | canvas  | notes                               |
++------+---------+-------------------------------------+
+| line | braille | joins points, one series per column |
+| bar  | none    | negative values split at zero       |
+| stem | none    | back-to-back with two columns       |
++------+---------+-------------------------------------+
+```
+
+### Custom borders
+
+`--style` (`style:`) also takes eleven glyphs: a frame's six (`tl tr
+bl br h v`), then the five tees, in the order `top_t bot_t sep_l
+sep_t sep_r` (the tee on the top edge, on the bottom edge, at the
+left end of the header rule, its crossings, its right end):
+
+```text
+$ tessella table --style '╒╕╘╛═│╤╧╞╪╡' langs.csv
+╒══════╤═════╕
+│ lang │ loc │
+╞══════╪═════╡
+│ ruby │  12 │
+│ c    │  30 │
+│ rust │ 7.5 │
+╘══════╧═════╛
+```
+
+Six glyphs are not enough for a table:
+
+<!-- tessella: allow-mixed -->
+```text
+$ tessella table --style '╓╖╙╜─║' langs.csv 2>&1 | \
+    fold -s -w 72 | sed 's/ $//'
+tessella table: a table's border set needs 11 glyphs, its tees after
+the six of a frame: "╓╖╙╜─║"
+Usage: tessella table [options] [file]  (stdin if none)
+    --tsv --no-header --align SPEC --style NAME|GLYPHS --[no-]ascii
+    --title TEXT --max-width N
+```
+
+### ASCII
+
+Under `ascii: true` a named style draws as `ascii`, except `markdown`,
+which is ASCII already and stays a pipe table; a custom set is drawn
+if it is all ASCII and refused if not. A cell or title that is not
+ASCII is refused. In a markdown table a `|` in a cell is written
+`\|`, so it does not split the cell.
+
+```text
+$ tessella table --ascii --style '****=!+++++' langs.csv
+*======+=====*
+! lang ! loc !
++======+=====+
+! ruby !  12 !
+! c    !  30 !
+! rust ! 7.5 !
+*======+=====*
+```
+
+## Multi-line cells, and fitting a width
+
+These two are library options, not command-line flags.
+
+A cell holding `"\n"` draws on several lines within its row,
+top-aligned. `width: N` fits the framed table to N columns. It
+narrows the widest column one column at a time, then whichever is
+widest by then, so wide columns come down together and a narrow one
+is never cut first. The narrowed columns' cells are word-wrapped, a
+word too long for its column breaking inside.
+
+```ruby
+# frozen_string_literal: true
+
+# examples/fit.rb: a table fitted to a width. At 40 columns only the
+# widest column narrows and wraps; at 26 it has come down to the next
+# widest, and both narrow together. A cell holding a newline keeps its
+# own lines. Fitted to 20, the table is refused, naming the width it
+# needs.
+require "tessella"
+
+rows = Tessella::Table.parse(File.read("kinds.csv"))
+rows << ["box", "none", "quartiles\nand whiskers"]
+[40, 26, 20].each do |width|
+    puts Tessella.table(rows, width: width)
+rescue ArgumentError => e
+    puts e.message
+end
+```
+
+```text
+$ ruby fit.rb
+┌──────┬─────────┬─────────────────────┐
+│ kind │ canvas  │ notes               │
+├──────┼─────────┼─────────────────────┤
+│ line │ braille │ joins points, one   │
+│      │         │ series per column   │
+│ bar  │ none    │ negative values     │
+│      │         │ split at zero       │
+│ stem │ none    │ back-to-back with   │
+│      │         │ two columns         │
+│ box  │ none    │ quartiles           │
+│      │         │ and whiskers        │
+└──────┴─────────┴─────────────────────┘
+┌──────┬────────┬────────┐
+│ kind │ canvas │ notes  │
+├──────┼────────┼────────┤
+│ line │ braill │ joins  │
+│      │ e      │ points │
+│      │        │ , one  │
+│      │        │ series │
+│      │        │ per    │
+│      │        │ column │
+│ bar  │ none   │ negati │
+│      │        │ ve     │
+│      │        │ values │
+│      │        │ split  │
+│      │        │ at     │
+│      │        │ zero   │
+│ stem │ none   │ back-t │
+│      │        │ o-back │
+│      │        │ with   │
+│      │        │ two    │
+│      │        │ column │
+│      │        │ s      │
+│ box  │ none   │ quarti │
+│      │        │ les    │
+│      │        │ and    │
+│      │        │ whiske │
+│      │        │ rs     │
+└──────┴────────┴────────┘
+table needs 22 columns at the least (min_width 4)
+```
+
+No column narrows below `min_width:` (4 by default), or below its
+own width when that is smaller. When every column is at that floor
+and the table is still too wide, it is refused rather than drawn
+wider than asked, and the message names the width it needs: the last
+line above.
+
+`min_width:` may also be an Array, one floor per column: a column
+that must stay readable (a name, an identifier) keeps its width, and
+the narrowing falls on the others. Each column's floor is its own
+value, or its natural width when smaller, and the table is refused
+only when every column is at its floor. The command line has no flag
+for it.
+
+```ruby
+# frozen_string_literal: true
+
+# examples/floors.rb: one table fitted to 70 columns twice. With one
+# floor for every column, the variable name is cut with the path; with
+# a floor per column, the names keep their width and the path alone
+# wraps. A list of the wrong length is refused.
+require "tessella"
+
+rows = [
+    %w[name variable path mode size age],
+    ["tado-pairing", "CLIMAT_PAIRING",
+     "/home/user/.config/climat-control/tado-pairing.json", "0600",
+     "1.2 kB", "3 d"]
+]
+puts Tessella.table(rows, width: 70, min_width: 4)
+puts Tessella.table(rows, width: 70, min_width: [12, 14, 12, 4, 6, 7])
+begin
+    Tessella.table(rows, width: 70, min_width: [12, 14])
+rescue ArgumentError => e
+    puts e.message
+end
+```
+
+```text
+$ ruby floors.rb
+┌──────────────┬───────────────┬───────────────┬──────┬────────┬─────┐
+│ name         │ variable      │ path          │ mode │ size   │ age │
+├──────────────┼───────────────┼───────────────┼──────┼────────┼─────┤
+│ tado-pairing │ CLIMAT_PAIRIN │ /home/user/.c │ 0600 │ 1.2 kB │ 3 d │
+│              │ G             │ onfig/climat- │      │        │     │
+│              │               │ control/tado- │      │        │     │
+│              │               │ pairing.json  │      │        │     │
+└──────────────┴───────────────┴───────────────┴──────┴────────┴─────┘
+┌──────────────┬────────────────┬──────────────┬──────┬────────┬─────┐
+│ name         │ variable       │ path         │ mode │ size   │ age │
+├──────────────┼────────────────┼──────────────┼──────┼────────┼─────┤
+│ tado-pairing │ CLIMAT_PAIRING │ /home/user/. │ 0600 │ 1.2 kB │ 3 d │
+│              │                │ config/clima │      │        │     │
+│              │                │ t-control/ta │      │        │     │
+│              │                │ do-pairing.j │      │        │     │
+│              │                │ son          │      │        │     │
+└──────────────┴────────────────┴──────────────┴──────┴────────┴─────┘
+min_width must be a positive Integer or 6 of them: [12, 14]
+```
+
+The `markdown` style refuses multi-line cells and `width:`: a pipe
+table cannot hold either.
+
+## Colour
+
+An ANSI colour code in a cell takes no column. It survives padding,
+and wrapping too: it is closed at the end of each wrapped line and
+reopened on the next, so every line stands on its own. `color: true`
+sets the header in bold.
+
+## Errors
+
+Bad input is refused naming the line (exit 1): an unterminated
+quoted field, a row with a different number of fields from the
+first, a non-ASCII cell or title under `--ascii`, a table wider than
+`--max-width`.
+
+```text
+$ printf 'a,b\nc\n' | tessella table
+tessella table: line 2: expected 2 fields, got 1
+```
+
+An unknown style or a malformed `--align` is a usage error (exit 2).

data/doc/targets.md

@@ -0,0 +1,222 @@
+# Width targets
+
+A figure lines up only if every glyph takes the columns tessella
+counted, and that depends on where the figure is read. tessella can
+draw for three targets:
+
+| Target | Where                        | Widths                                                    |
+|--------|------------------------------|-----------------------------------------------------------|
+| `term` | a Western terminal (default) | ambiguous glyphs 1 column, wide ones (CJK, emoji) 2       |
+| `cjk`  | a CJK-configured terminal    | ambiguous glyphs 2 columns: box drawing, blocks, `·`, `é` |
+| `web`  | a browser                    | as `term`, but some glyphs may turn into wide emoji        |
+
+([Width classes](glyphs.md#width-classes) explains ambiguous and
+wide.)
+
+```text
+tessella --target term|cjk|web COMMAND ...
+TESSELLA_TARGET=cjk tessella COMMAND ...
+```
+
+```ruby
+Tessella.target = :cjk                         # for the rest of the fiber
+Tessella::Target.with(:web) { Tessella.table(rows).to_s }
+```
+
+`--target` wins over `TESSELLA_TARGET`, and an empty variable means
+`term`. An unknown target, or `--target` with no name, is a usage
+error, exit 2, even before `--help`:
+
+```text
+$ tessella --target vt100 table langs.csv
+tessella: unknown target: "vt100" (term, cjk, web)
+```
+
+## term
+
+The default. `cities.csv` holds a CJK label, which takes two columns
+everywhere, and an accented one:
+
+```text
+$ tessella table cities.csv
+┌────────┬─────┐
+│ city   │ pop │
+├────────┼─────┤
+│ 東京   │  14 │
+│ Paris  │   2 │
+│ Zürich │ 0.4 │
+└────────┴─────┘
+```
+
+An emoji sequence, joined by ZWJ (👨‍👩‍👧) or skin-toned (👍🏽), is
+one glyph two columns wide in every target, as terminals draw it.
+
+## cjk
+
+In a CJK-configured terminal box drawing is two columns wide, so a
+Unicode frame cannot line up there. Under `cjk` every module's
+`ascii:` defaults to true: the structure is drawn in ASCII, while the
+text stays as given and is measured with ambiguous glyphs as two
+columns.
+
+```text
+$ tessella --target cjk table cities.csv
++---------+-----+
+| city    | pop |
++---------+-----+
+| 東京    |  14 |
+| Paris   |   2 |
+| Zürich | 0.4 |
++---------+-----+
+```
+
+Read here, in a Western font, the `Zürich` row looks one column
+short: `ü` is ambiguous, and the table gave it the two columns a CJK
+terminal will. There, the row lines up.
+
+`ascii: false` still asks for Unicode structure. A frame and a table
+then round every inner width up to a whole number of border glyphs
+and count their border runs in columns, so each line has one width in
+a CJK terminal and the box closes there. Read in a Western terminal,
+as on this page, the box looks a column too wide here and there.
+Other figures (trees, waves, charts) drawn in Unicode under `cjk` do
+not line up in a CJK terminal: leave them to the ASCII default.
+
+On the command line, `--no-ascii` asks for Unicode under `cjk`;
+without it, a Unicode `--style` is refused rather than quietly drawn
+in ASCII:
+
+```text
+$ tessella --target cjk table --no-ascii --style light cities.csv
+┌─────┬───┐
+│ city     │  pop │
+├─────┼───┤
+│ 東京     │   14 │
+│ Paris    │    2 │
+│ Zürich  │  0.4 │
+└─────┴───┘
+```
+
+```text
+$ tessella --target cjk compose frame --style light note.txt 2>&1 | head -1
+tessella compose: --style light needs --no-ascii under target cjk
+```
+
+From Ruby, `ascii: false`:
+
+```ruby
+# frozen_string_literal: true
+
+# examples/cjk.rb: a table and a frame asked for in Unicode under the
+# cjk target. Their inner widths are rounded up to whole border
+# glyphs, so they close in a CJK terminal; read in a Western one, as
+# here, the boxes look a column wide here and there.
+require "tessella"
+
+Tessella::Target.with(:cjk) do
+    rows = Tessella::Table.parse(File.read("cities.csv"))
+    puts Tessella.table(rows, ascii: false)
+    puts Tessella.frame(File.read("note.txt"), ascii: false)
+end
+```
+
+```text
+$ ruby cjk.rb
+┌─────┬───┐
+│ city     │  pop │
+├─────┼───┤
+│ 東京     │   14 │
+│ Paris    │    2 │
+│ Zürich  │  0.4 │
+└─────┴───┘
+┌─────────┐
+│ ruby is 12 kLOC  │
+│ c is the bulk    │
+└─────────┘
+```
+
+## web
+
+A figure read in a browser (a README on GitHub, a page of docs) is at
+risk where it draws an arrow head. The arrow glyphs fall in three
+groups:
+
+| Glyphs             | On the web                                            |
+|--------------------|-------------------------------------------------------|
+| `▸ ◂ ▴ ▾`          | text glyphs most monospace fonts carry: they line up  |
+| `→ ← ↑ ↓`          | text glyphs most monospace fonts carry: they line up  |
+| `► ◄`              | not emoji-capable, bolder; some fonts lack them       |
+| `▶ ◀ ↔ ↕ ↗ ↘ ↙ ↖`  | emoji-capable: may become a wide colour emoji         |
+
+So on the web, end a drawn line with a small head, `────▸`, or a
+bolder `────►`, and keep `→ ← ↑ ↓` for arrows standing alone. `► ◄`
+never turn into emoji, but a font without them still draws them at a
+fallback width: they trade a little of `▸`'s safety for a head that
+reads at a glance.
+
+tessella's sequence diagrams use the bolder heads in every target,
+terminal included: `►` and `◄` for calls and replies, `►►` and `◄◄`
+for asynchronous messages ([sequence diagrams](seq.md#arrow-heads)).
+`tessella glyphs head` lists the heads with the targets each suits
+([glyph sets](glyphs.md#arrow-heads)).
+
+When a figure does carry an emoji-capable glyph, `--target web` puts
+U+FE0E, the text-presentation selector, right after it. The selector
+is invisible; here it is made visible as `[FE0E]`:
+
+```text
+$ tessella --target web rule --width 24 --ornament '▶ next' | \
+    ruby -pe 'gsub("\u{FE0E}", "[FE0E]")'
+──────── ▶[FE0E] next ────────
+```
+
+It stops the browser drawing the glyph as an emoji, and is the one
+exception to tessella's rule of no invisible characters in its
+output. It does not fix the glyph's width: a glyph the page's
+monospace font lacks is drawn from a fallback font, at that font's
+width. In Chrome on GitHub's code fonts `▶` takes two columns and
+`↗` 1.4, with or without the selector. On a row that must line up,
+the selector is not enough; `▸` is the arrow head that lines up.
+
+The same holds beyond arrows. Measured in Chrome on GitHub's code
+fonts, box drawing, quadrant and half blocks, eighths and shades are
+exactly one column, but braille is about 1.2 and `◆` two. So under
+`--target web` a chart defaults to quadrant blocks instead of braille
+(`--canvas braille` still asks for it), the fill pattern that was `◆`
+is `■`, and `tessella lint --target web` flags a row of braille.
+
+`tessella lint --target web` (the same as `--web`) checks a figure
+for this. It flags a bare emoji-capable glyph, and accepts one
+followed by U+FE0E:
+
+```text
+$ printf 'A ──▶ B\n' | tessella lint --target web
+stdin:1: emoji-capable U+25B6 ▶ (web target)
+```
+
+```text
+$ printf 'A ──▸ B\n' | tessella lint --target web && echo clean
+clean
+```
+
+To add the selector to a figure edited by hand, use a tool rather
+than typing an invisible character:
+
+```sh
+ruby -pi -e 'gsub(/([▶◀])(?!\u{FE0E})/, "\\1\u{FE0E}")' FIGURE.md
+```
+
+## Checking for a target
+
+`tessella lint --target T` measures a figure with the target's widths
+([lint](lint.md#the-target)): under `cjk` it names an ambiguous glyph
+on a row that must line up.
+
+```text
+$ tessella table cities.csv | tessella lint --target cjk
+stdin:6: ambiguous U+00FC ü on aligned row (cjk target: 2 columns)
+```
+
+`tessella glyphs --target T` lists the glyph sets safe for a target,
+and `--check` says which targets a set of one's own suits
+([glyph sets](glyphs.md)).

data/doc/text.md

@@ -0,0 +1,84 @@
+# Text styles
+
+`text` writes letters and digits in one of Unicode's styled
+alphabets: 𝐛𝐨𝐥𝐝, 𝑖𝑡𝑎𝑙𝑖𝑐, 𝔣𝔯𝔞𝔨𝔱𝔲𝔯, ℍ𝕖𝕝𝕝𝕠, Sᴍᴀʟʟ ᴄᴀᴘꜱ, ⓒⓘⓡⓒⓛⓔⓓ and the
+rest. They are characters, not formatting, so they survive where no
+markup does: a terminal banner, a commit subject, a plain-text title.
+
+```ruby
+Tessella.text("Hello", style: :double_struck)   # => "ℍ𝕖𝕝𝕝𝕠"
+Tessella.text("ℍ𝕖𝕝𝕝𝕠", style: :plain)          # => "Hello"
+```
+
+```text
+tessella text --style S [--strict] [TEXT ...]
+tessella text --plain [TEXT ...]
+```
+
+The command styles its arguments, joined by blanks, or stdin when
+there are none:
+
+```text
+$ tessella text --style bold Hello
+𝐇𝐞𝐥𝐥𝐨
+```
+
+```text
+$ tessella text --style double-struck Hello 2024
+ℍ𝕖𝕝𝕝𝕠 𝟚𝟘𝟚𝟜
+```
+
+```text
+$ echo hi | tessella text --style fullwidth
+ｈｉ
+```
+
+## The styles
+
+`bold`, `italic`, `bold-italic`, `script`, `bold-script`, `fraktur`,
+`bold-fraktur`, `double-struck`, `sans`, `sans-bold`, `sans-italic`,
+`sans-bold-italic`, `monospace`, `small-caps`, `superscript`,
+`subscript`, `circled`, `negative-circled`, `parenthesized`,
+`squared`, `negative-squared` and `fullwidth`. In Ruby a style is a
+Symbol with `_` for `-`: `:double_struck`.
+
+The forms come from Unicode's own data; the gaps in the mathematical
+alphabets are filled from Letterlike Symbols (`ℎ`, `ℬ`, `ℂ`, ...), as
+Unicode intends. Capitals keep their case in small caps; `squared`
+and the two negative styles have capitals only. `fullwidth` glyphs
+are two columns wide.
+
+`--plain` (`style: :plain`) turns any of them back into plain
+letters and digits:
+
+```text
+$ tessella text --plain 'ℍ𝕖𝕝𝕝𝕠 𝟚𝟘𝟚𝟜'
+Hello 2024
+```
+
+## Characters without a form
+
+Not every style has every character: digits exist only in `bold`,
+`double-struck`, `sans`, `sans-bold` and `monospace`; small caps have
+no `x`; most letters have no subscript. Such a character passes
+through unchanged, and the command names it on stderr:
+
+```text
+$ tessella text --style small-caps 'Hello x'
+tessella text: no small-caps form for: x
+Hᴇʟʟᴏ x
+```
+
+`--strict` (`strict: true`) refuses the text instead: the command
+prints nothing and exits 1.
+
+```text
+$ tessella text --style small-caps --strict 'Hello x'
+tessella text: no small-caps form for: x
+```
+
+## When not to
+
+Every style is non-ASCII, so `--ascii` refuses them all. And they are
+for a decorative line, not for prose: a screen reader spells them out
+or skips them, and a search for "Hello" does not find "ℍ𝕖𝕝𝕝𝕠".