tessella 0.3.0

data/doc/getting-started.md

@@ -0,0 +1,121 @@
+# Getting started
+
+## Install
+
+tessella is not on rubygems.org. Install it from a checkout:
+
+```sh
+cd tessella
+make install      # builds the gem, installs it for this user
+```
+
+`make uninstall` removes it. Without installing, `exe/tessella` runs
+straight out of the checkout, and `ruby -I lib` finds the library.
+It needs Ruby 3.4 and nothing else.
+
+## A first chart
+
+Any file of numbers will do. [examples/langs.csv](../examples/langs.csv)
+holds a header and three rows:
+
+```text
+$ cat langs.csv
+lang,loc
+ruby,12
+c,30
+rust,7.5
+```
+
+```text
+$ tessella chart --kind bar --width 30 langs.csv
+        ┌                              ┐
+   ruby ┤██████████▍··············· 12
+      c ┤██████████████████████████ 30
+   rust ┤██████▌··················· 7.5
+        └                              ┘
+```
+
+The same, for a document kept to ASCII:
+
+```text
+$ tessella chart --kind bar --width 30 --ascii langs.csv
+        +                              +
+   ruby |##########................ 12
+      c |########################## 30
+   rust |#######................... 7.5
+        +                              +
+```
+
+## A first diagram
+
+Each diagram reads a small text format from a file or stdin:
+
+<!-- tessella: allow-mixed -->
+```text
+$ printf 'Client -> Server: GET /\nServer --> Client: 200\n' | tessella seq
+┌─────────┐  ┌─────────┐
+│ Client  │  │ Server  │
+└────┬────┘  └────┬────┘
+     │            │
+     │   GET /    │
+     │───────────►│
+     │            │
+     │    200     │
+     │◄┄┄┄┄┄┄┄┄┄┄┄│
+     │            │
+```
+
+## From Ruby
+
+```ruby
+require "tessella"
+
+puts Tessella.bar(%w[ruby c rust], [12, 30, 7.5], width: 30)
+```
+
+Every factory returns an object that prints as the figure, and every
+figure composes with every other: frame it, set it beside another,
+stack, indent or caption it.
+
+```ruby
+# frozen_string_literal: true
+
+# examples/load.rb: a bar chart and a table side by side, framed and
+# captioned -- composition of any two figures.
+require "tessella"
+
+rows = Tessella::Table.parse(File.read("langs.csv"))
+labels = rows.drop(1).map(&:first)
+values = rows.drop(1).map { Integer(it[1], exception: false) || it[1].to_f }
+plot = Tessella.bar(labels, values, width: 20)
+table = Tessella.table(rows, style: :rounded)
+fig = Tessella.beside(plot, table, gap: 2, align: :middle)
+puts Tessella.caption(Tessella.frame(fig, title: "Load"),
+                      text: "Figure 1: lines of code, in thousands")
+```
+
+```text
+$ ruby load.rb
+┌───────────────────── Load ─────────────────────┐
+│                                 ╭──────┬─────╮ │
+│         ┌                    ┐  │ lang │ loc │ │
+│    ruby ┤██████▍········· 12    ├──────┼─────┤ │
+│       c ┤████████████████ 30    │ ruby │  12 │ │
+│    rust ┤████············ 7.5   │ c    │  30 │ │
+│         └                    ┘  │ rust │ 7.5 │ │
+│                                 ╰──────┴─────╯ │
+└────────────────────────────────────────────────┘
+
+      Figure 1: lines of code, in thousands
+```
+
+## Where next
+
+- [Charts](charts.md): the eight kinds, their input, options and
+  canvases.
+- [Composition](composition.md): assembling figures.
+- [Trees](tree.md), [tables](table.md), [bit fields](bitfield.md),
+  [timing diagrams](wave.md), [sequence diagrams](seq.md),
+  [pictures](images.md).
+- [Linting](lint.md): checking figures before they ship.
+- [The command](cli.md) and [the library](library.md), for reference.

data/doc/glyphs.md

@@ -0,0 +1,134 @@
+# Glyph sets and width classes
+
+A figure lines up only if every glyph in it takes the columns the
+author counted. Most do, everywhere. Some do in a Western terminal
+and take two columns in one set up for Chinese, Japanese or Korean:
+the box-drawing lines and the shade blocks among them. tessella names
+the glyph sets it draws with, and says for each which of these
+classes its glyphs fall in.
+
+```ruby
+Tessella::Width.class_of("▒")                  # => :A
+Tessella::Glyphs.fetch(:ramp, :blocks)         # => a GlyphSet
+Tessella::Glyphs.fetch(:ramp, :blocks).mixed?  # => true
+```
+
+```text
+tessella glyphs [KIND [NAME]]
+tessella glyphs --check GLYPHS
+```
+
+## Width classes
+
+Every character has one class, from Unicode 15.1's East Asian Width
+property:
+
+| Class | Name      | Columns                                          |
+|-------|-----------|--------------------------------------------------|
+| `N`   | narrow    | one, everywhere                                  |
+| `A`   | ambiguous | one in Western terminals, two in CJK-configured ones |
+| `W`   | wide      | two, everywhere (CJK ideographs, most emoji)     |
+
+`Tessella::Width.class_of(char)` returns `:N`, `:A` or `:W`. A set
+whose glyphs all share one class keeps its shape in any terminal; a
+set that spans two is *mixed*: right in a Western terminal, but its
+glyphs change width against each other in a CJK one, so a figure
+drawn with it stops lining up there.
+
+## The registry
+
+`tessella glyphs` lists every named set the library draws with: its
+kind, its name, its classes, the [width targets](targets.md) it is
+safe for, and its glyphs. Every set suits `term`; a set suits `cjk`
+when it holds no ambiguous glyph, and `web` when it holds no wide or
+emoji-capable one. A kind narrows the list to one kind:
+
+<!-- tessella: allow-mixed -->
+```text
+$ tessella glyphs border
+border   light              A    term web      ┌┐└┘─│
+border   heavy              A    term web      ┏┓┗┛━┃
+border   double             A    term web      ╔╗╚╝═║
+border   rounded            A    term web      ╭╮╰╯─│
+border   dashed             A    term web      ┌┐└┘┄┆
+border   dashed_fine        A    term web      ┌┐└┘┈┊
+border   heavy_dashed       A    term web      ┏┓┗┛┅┇
+border   heavy_dashed_fine  A    term web      ┏┓┗┛┉┋
+border   double_h           A    term web      ╒╕╘╛═│
+border   double_v           A    term web      ╓╖╙╜─║
+border   ascii              N    term cjk web  ++++-|
+```
+
+A kind and a name list one set glyph by glyph, with code points:
+
+```text
+$ tessella glyphs ramp blocks
+░  U+2591  N
+▒  U+2592  A
+▓  U+2593  A
+█  U+2588  A
+```
+
+The `blocks` ramp is mixed: `░` is narrow, the three others are
+ambiguous. In a CJK terminal its lightest tone is half as wide as the
+others.
+
+From Ruby, `Tessella::Glyphs.fetch(kind, name)` returns a `GlyphSet`
+(`kind`, `name`, `glyphs`, `note`, `classes`, `mixed?`, `targets`),
+`Tessella::Glyphs.targets(glyphs)` the targets any glyphs suit, and
+`Tessella::Glyphs.all` every set. An unknown kind or name raises
+`ArgumentError`, listing the names there are. A name may say `-` for
+`_`.
+
+`--target T` lists only the sets safe for a target, here the meter
+styles a CJK terminal draws as counted:
+
+```text
+$ tessella glyphs --target cjk meter
+meter    arrow              N    term cjk web  ▸▹
+meter    chevron            N    term cjk web  ›
+meter    classic            N    term cjk web  =
+meter    rectangle          N    term cjk web  ▮▯
+meter    wave               N    term cjk web  ~_
+meter    blade              N    term cjk web  ▰▱  (patchy font coverage)
+meter    button             N    term cjk web  ⦿⦾  (patchy font coverage)
+```
+
+### Arrow heads
+
+The registry also holds the arrow heads, as kind `head`, with the rule
+for choosing one in their targets and notes:
+
+```text
+$ tessella glyphs head
+head     full               N+A  term web      ►◄▲▼  mixed  (▴▾ under cjk)
+head     small              N    term cjk web  ▸◂▴▾
+head     emoji              A    term          ▶◀  (+U+FE0E on web)
+```
+
+`full` (`►◄▲▼`) is mixed: `► ◄` are narrow, `▲ ▼` ambiguous, so in a
+CJK terminal use `▴ ▾` for up and down; `tessella lint --target cjk`
+says so when it finds `▲` or `▼` on a row that must line up. `small`
+(`▸◂▴▾`) suits every target. `emoji` (`▶◀`) suits the terminal only,
+and needs U+FE0E after it on the web ([width targets](targets.md#web)).
+
+## Checking a set of one's own
+
+`--check GLYPHS` classifies any glyphs: it prints their class and the
+targets they are safe for, and exits 1 when they are mixed, so a
+build can refuse a glyph set before a figure uses it:
+
+```text
+$ tessella glyphs --check '┌┐└┘─│'
+A
+safe for: term web
+```
+
+```text
+$ tessella glyphs --check '░▒▓█'
+mixed: N A
+safe for: term web
+```
+
+The [lint](lint.md) measures widths with the same tables, so what
+`glyphs` calls narrow, the lint counts as one column.

data/doc/images.md

@@ -0,0 +1,325 @@
+# Pictures
+
+`image` draws a picture as text: a logo for a banner, a plot or a
+screenshot for a terminal, a photograph as a curiosity.
+
+```ruby
+Tessella.image(source, style: :ramp, width: 78, ramp: nil, gamma: 1.0,
+               threshold: 0.5, dither: :fs, invert: false,
+               edge_threshold: 0.3, ascii: false)        # => Block
+```
+
+```text
+tessella image [--style S] [--width N] [--dither M] [--ramp STR|NAME]
+               [--gamma F] [--threshold F] [--edge-threshold F]
+               [--invert] [--ascii] [--max-width N] [file]
+```
+
+## Sources
+
+`source` is a `Tessella::Raster`, an IO, or a String of image bytes.
+The format is told by the bytes' own signature, not a file name:
+
+- **PGM and PPM** (P2, P3, P5, P6) and **PNG** decode with nothing
+  installed, in plain Ruby.
+- **Anything else** (JPEG, GIF, TIFF, WebP, ...) needs the `rmagick`
+  gem. tessella uses it when it is installed and never requires it;
+  without it the image is refused, naming the way round: convert to
+  PGM first.
+
+```text
+$ printf 'GIF89a' | tessella image 2>&1 | fold -s -w 72 | sed 's/ $//'
+tessella image: not a PNM or PNG image, and the rmagick gem is not
+installed: install it, or convert the image first (magick IMAGE pgm:- |
+tessella image)
+```
+
+```sh
+magick photo.jpg pgm:- | tessella image --width 60
+```
+
+Colour becomes grey by Rec. 601 luma, and transparency is laid over
+black, so a transparent pixel is empty.
+
+A `Raster` can also be built in Ruby, from any function: width,
+height, and `width * height` grey values in 0..1, row by row from the
+top, 1.0 the brightest.
+
+```ruby
+# frozen_string_literal: true
+
+# examples/gradient.rb: a Raster built in Ruby -- no image file --
+# drawn in three styles, side by side.
+require "tessella"
+
+w = h = 48
+luma = (0...h).flat_map do |y|
+    (0...w).map { |x| Math.hypot(x - 24, y - 24) < 22 ? x / 47.0 : 0 }
+end
+raster = Tessella::Raster.new(width: w, height: h, luma: luma)
+figs = %i[ramp blocks quadrant].map do |style|
+    Tessella.caption(Tessella.image(raster, style: style, width: 16),
+                     text: style.to_s)
+end
+puts Tessella.beside(*figs, gap: 3)
+```
+
+```text
+$ ruby gradient.rb
+     .:::-:.             ░░░░░░             ▖▖▖▖▖▖
+   .:-==++*#*-        ░░░▒▒▒▒▓▓▓░         ▝▖▚▐▐▞▛▟▙▄
+  .::-==++*##%*      ░░░░▒▒▒▒▓▓▓▓▓       ▘▚▝▞▞▞▞▛▟▟▜▙
+ ..::-==++*##%%-     ░░░░▒▒▒▒▓▓▓▓█░      ▘▖▚▝▞▞▞▛▟▜▛█▌
+ ..::-==++*##%%-     ░░░░▒▒▒▒▓▓▓▓█░     ▘▘▝▖▚▚▚▜▞▛▙██▌
+ ..::-==++*##%#      ░░░░▒▒▒▒▓▓▓▓▓      ▗▝▖▞▐▗▚▚▜▜▙▛▛
+  .::-==++*##+        ░░░▒▒▒▒▓▓▓▒        ▗▗▝▖▌▙▜▚▙▙▀
+    .::--=--            ░░░░▒░░            ▘▘▘▝▝▘▘
+
+      ramp              blocks            quadrant
+```
+
+## Styles
+
+The style trades tone for resolution. `ramp` and `blocks` give one
+tone per character cell; the others pack several on/off pixels into a
+cell, using dithering for tone; `edges` draws outlines.
+
+| Style      | Pixels per cell | Glyphs                          |
+|------------|-----------------|---------------------------------|
+| `ramp`     | 1               | `` .:-=+*#%@`` (or `--ramp`)    |
+| `blocks`   | 1               | ` ░▒▓█`                         |
+| `half`     | 1 × 2           | `▀ ▄ █`                         |
+| `quadrant` | 2 × 2           | `▘▝▀▖▌▞▛▗▚▐▜▄▙▟█`               |
+| `sextant`  | 2 × 3           | Unicode 13 sextants `🬀`…`🬻`      |
+| `braille`  | 2 × 4           | braille patterns                |
+| `octant`   | 2 × 4           | Unicode 16 octants (see below)  |
+| `petscii`  | 4 × 8 tones     | about forty shapes (see below)  |
+| `edges`    | 1               | `─ │ ╱ ╲`, Sobel contours       |
+
+`disc.pgm` is a 64 × 64 grey disc, brightest at its centre:
+
+```text
+$ tessella image --width 24 disc.pgm
+
+        ...::...
+     .::--====---:.
+    :--=+++**+++==-:.
+   :-==+**####**++=-:.
+  .:-=+**#%%%%##*+==:.
+  .:-=+*##%%%%##*+==:.
+  .:-=++**#####*++=-:.
+   .:-==+++***++==-:.
+     .:--======--:.
+       ..::::::..
+```
+
+```text
+$ tessella image --style blocks --width 24 disc.pgm
+
+          ░░░░░
+      ░░░▒▒▒▒▒▒░░░
+    ░░▒▒▒▒▒▒▒▒▒▒▒▒░░
+   ░░▒▒▒▓▓▓▓▓▓▓▓▒▒▒░░
+   ░░▒▒▓▓▓▓██▓▓▓▓▒▒▒░░
+   ░░▒▒▓▓▓▓███▓▓▓▒▒▒░░
+   ░░▒▒▒▓▓▓▓▓▓▓▓▒▒▒░░
+    ░░▒▒▒▒▒▓▓▒▒▒▒▒░░
+      ░░░▒▒▒▒▒▒░░░░
+        ░░░░░░░░
+```
+
+The braille renders on this page line up only in a terminal: on
+GitHub braille is drawn about 1.2 columns wide
+([width targets](targets.md#web)).
+
+```text
+$ tessella image --style braille --width 24 disc.pgm
+
+        ⢀ ⢄⠠⠠⠠⢀⢀
+      ⠄⢌⢢⢡⢱⢸⢘⢜⠔⡔⡨⠠⡀
+    ⠠⠡⡣⡱⡱⡱⣕⢵⣣⡳⣕⢕⡜⡌⡢⢁
+   ⠠⡑⢕⢱⡱⣝⢮⣗⣯⢾⣺⢮⡳⣕⢕⢜⠄⢅
+   ⢅⠪⡪⣪⢺⣺⢽⣾⣻⣿⣽⢯⣞⢮⡣⡣⡃⢅⠐
+   ⠢⡑⢕⢕⣝⢾⢽⡾⣿⢿⣽⣻⣺⢵⡹⡸⡨⢂⠂
+   ⡁⠪⡸⡸⡸⣕⢯⢯⣻⢽⣳⢽⡪⡇⡇⡇⡪⠐
+    ⠡⢂⢕⢱⠱⡍⣗⢵⢫⢎⢧⢣⢣⠣⢊⠐⠈
+     ⠂⠐⠌⡊⡪⠢⠣⡣⢃⠇⢕⠐⠅⠂
+      ⠈ ⠂⠂⠡⠑⠨⠠⠑ ⠁
+```
+
+```text
+$ tessella image --style edges --width 24 disc.pgm
+
+        ────────
+     ╱────────────╲
+    ╱╱╱╱────────╲╲╲╲
+                    ╲
+
+
+                    ╱
+    ╲╲╲╲────────╱╱╱╱
+     ╲────────────╱
+       ──────────
+```
+
+[examples/gallery.sh](../examples/gallery.sh) draws one picture in
+four styles side by side ([output](cli.md#several-figures-one-result)).
+
+The sextant glyphs are recent (Unicode 13, 2020): check that the
+reader's font has them before using `sextant`.
+
+`octant` packs 2 × 4 pixels into a cell, as braille does, but as
+solid blocks rather than dots, so a picture keeps its tone where
+braille turns grey. Its glyphs are Unicode 16 (2024), and only the
+newest terminals draw them (Ghostty and its like); elsewhere each
+cell shows as a box or a blank. That is why this page shows no
+octant render: try `tessella image --style octant disc.pgm` in your
+own terminal.
+
+`petscii` draws as the Commodore character set did: each cell's 4 × 8
+tones are matched to the glyph of least error among about forty
+shapes (halves, quadrants, `▏▕▔▁`, three-quarter blocks `▊ ▆` and
+their kin `▂ 🮊 🮂 🮅`, the triangles `◢◣◤◥`, `╱╲╳`, the shades `░▒▓`,
+lines, corners and tees, `● ○`). `🮊 🮂 🮅` are from Unicode 13's
+Legacy Computing block, so the font caveat on sextants holds here
+too. A soft picture comes out in shades:
+
+```text
+$ tessella image --style petscii --width 24 disc.pgm
+
+         ░░░░░░
+      ░░░▒▒▒▒▒▒░░░
+    ░░▒▒▒▒▒▒▒▒▒▒▒▒░░
+   ░░▒▒▒▓▓▓▓▓▓▓▓▒▒▒░░
+   ░░▒▒▓▓▓▓██▓▓▓▓▒▒▒░░
+   ░░▒▒▓▓▓▓██▓▓▓▓▒▒▒░░
+   ░░▒▒▒▓▓▓▓▓▓▓▓▒▒▒░░
+    ░░▒▒▒▒▒▒▒▒▒▒▒▒░░
+      ░░░▒▒▒▒▒▒░░░░
+         ░░░░░░
+```
+
+Hard edges are where it shows its shapes. `shapes.pgm` is a ring and
+a wedge in black and white:
+
+```text
+$ tessella image --style petscii --width 24 shapes.pgm
+      ▁▁▁▁     🮊███████◤
+   ▗▄██████▆▖  🮊██████▘
+  ◢███▀▀🮂▀▜██▙ 🮊█████▘
+ ▕██▊      ▐██▌🮊████▘
+ ▕██▊      ▐██▌🮊███▘
+  ▜██▙▄▂▂▂▟██▛ 🮊█▛
+   ▝🮅██████🮅▀  🮊▛
+      🮂🮂🮂🮂     ╱
+```
+
+`petscii` takes no dithering, so `--threshold` and `--dither` do not
+apply to it.
+
+## Tone
+
+- `--width N`: the picture's width in cells, 78 by default; the
+  height follows from the image's aspect, a cell being about twice as
+  tall as wide.
+- `--gamma F`: every tone t in 0..1 is drawn as t to the power F;
+  above 1 pushes the mid-tones toward empty, below 1 toward full.
+- `--invert`: tones are drawn as 1 − t. By default a bright pixel
+  gets a dense glyph, which suits light text on a dark terminal;
+  invert for dark text on a light page.
+- `--ramp STR`: the tone glyphs for `ramp`, from empty to full, or
+  the name of a ramp in the [registry](glyphs.md#the-registry):
+  `ramp` (the default), `blocks`, `long` (70 ASCII glyphs, for finer
+  tone) or `hatch`. A name wins over the same letters taken as
+  glyphs.
+- `--threshold F`: the tone at which a pixel is on, in the pixel
+  styles (0.5 by default).
+- `--dither M`: how the pixel styles render tone: `fs`
+  (Floyd-Steinberg, the default), `atkinson`, `bayer` (ordered), or
+  `none` (a plain threshold).
+- `--edge-threshold F`: the gradient strength an `edges` outline
+  needs (0.3 by default).
+
+```text
+$ tessella image --style braille --dither none --width 24 disc.pgm
+
+
+
+       ⢀⣤⣾⣿⣿⣿⣿⣷⣦⡀
+      ⣠⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦
+      ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡆
+      ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇
+      ⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡟
+       ⠈⠻⣿⣿⣿⣿⣿⣿⠿⠋
+          ⠈⠉⠉⠁
+```
+
+```text
+$ tessella image --ramp ' .oO@' --width 20 disc.pgm
+
+       .......
+    ..oooooooo..
+   ..oooOOOOOooo.
+  ..ooOOO@@OOOoo..
+  ..ooOOO@@OOOoo..
+   .oooOOOOOOooo..
+    ..oooooooo..
+      ........
+```
+
+```text
+$ tessella image --ramp long --width 30 disc.pgm
+
+          .`^",:,"`'
+       ',!<_?][[]?-~i;`
+     ':<]{(/fjrrjft\)}_l^
+    ^i-1/rucYUJJJYXvxf(]~I.
+   ^i?1tnzJQOmqqwZ0CYvj([~;.
+  .I+}\xzJ0wdhooakpZLYut)?>^
+  '!-1/nYQmdh#8%WokqOJcj|[~:
+  .l_{\xXCOqba##*hdmQUvf(]<"
+   ">])fuXC0mqddpwZQUcr|}_l.
+    :<](fxcXJCLQLCUzur\}_!`
+     ^l_}(/frxnnnxjt|1?>:.
+       ^l<_]}{11{}[-+i,.
+         .`,;Il!l;:^'
+```
+
+```text
+$ tessella image --ramp hatch --width 20 disc.pgm
+
+       ·······
+    ··∘∘∘∘∘∘∘∘··
+   ··∘∘∘╱╱╱╱╱∘∘∘·
+  ··∘∘╱╱╱╳╳╱╱╱∘∘··
+  ··∘∘╱╱╱╳╳╱╱╱∘∘··
+   ·∘∘∘╱╱╱╱╱╱∘∘∘··
+    ··∘∘∘∘∘∘∘∘··
+      ········
+```
+
+## ASCII
+
+`--ascii` allows only the `ramp` style, with an ASCII ramp:
+
+```text
+$ tessella image --style blocks --ascii disc.pgm
+tessella image: ascii: true allows only style: :ramp, not :blocks
+```
+
+## Errors
+
+A picture that would render blank — `edges` on a flat image, a
+threshold above every tone — is refused, naming what to change,
+rather than printed as nothing (exit 1):
+
+```text
+$ tessella image --style braille --threshold 1 --dither none disc.pgm 2>&1 | \
+    fold -s -w 72 | sed 's/ $//'
+tessella image: the picture renders blank at style braille: lower
+threshold, or try invert or another style
+```
+
+A malformed or truncated image is bad input (exit 1); an unknown
+style or dither, or a style that `--ascii` does not allow, is a usage
+error (exit 2).