tessella 0.3.0

data/doc/tree.md

@@ -0,0 +1,108 @@
+# Trees
+
+`tree` draws an indented outline as a box-drawing tree: a directory
+layout, a class hierarchy, a table of contents.
+
+```ruby
+Tessella.tree(outline, style: nil, ascii: false, root: nil)  # => Block
+```
+
+```text
+tessella tree [--style S] [--ascii] [--root NAME] [--max-width N] [file]
+```
+
+## The outline
+
+One node per line; depth is the leading spaces. The indent unit is
+whatever the first indented line uses, and every indent must be a
+whole multiple of it.
+
+```text
+$ cat outline.txt
+tessella
+  lib            # the library
+    tessella.rb  # the entry
+    tessella
+      cli
+  exe
+    tessella     # the command
+  test
+```
+
+- A leading `- ` or `* ` bullet is dropped, so a Markdown list reads
+  as is.
+- Two or more spaces then `#` start a note. Notes are lined up in one
+  column across the whole tree.
+- A line may go at most one level deeper than the line above it.
+
+```text
+$ tessella tree outline.txt
+tessella
+├── lib              # the library
+│   ├── tessella.rb  # the entry
+│   └── tessella
+│       └── cli
+├── exe
+│   └── tessella     # the command
+└── test
+```
+
+## Styles
+
+`--style light` (the default), `heavy` or `rounded`; `--ascii` draws
+`|--` and `` `-- `` instead, and allows no other style.
+
+```text
+$ tessella tree --style rounded outline.txt
+tessella
+├── lib              # the library
+│   ├── tessella.rb  # the entry
+│   ╰── tessella
+│       ╰── cli
+├── exe
+│   ╰── tessella     # the command
+╰── test
+```
+
+```text
+$ tessella tree --ascii outline.txt
+tessella
+|-- lib              # the library
+|   |-- tessella.rb  # the entry
+|   `-- tessella
+|       `-- cli
+|-- exe
+|   `-- tessella     # the command
+`-- test
+```
+
+## Forests and roots
+
+Several lines at the top level are a forest: each is drawn as a root
+of its own. `--root NAME` (`root: "NAME"`) gathers them under one
+root instead:
+
+<!-- tessella: allow-mixed -->
+```text
+$ printf -- '- lib\n- exe\n- test\n' | tessella tree --root tessella
+tessella
+├── lib
+├── exe
+└── test
+```
+
+## Errors
+
+Bad input raises `ArgumentError` naming the line (exit 1 on the
+command line): a tab, an indent that is not a whole multiple of the
+unit, a line two levels deeper than the one before it, an empty
+label, no node at all, and a non-ASCII label under `--ascii`.
+
+```text
+$ printf 'a\n   b\n  c\n' | tessella tree
+tessella tree: line 3: indentation is not a multiple of 3
+```
+
+An unknown style, or a style other than the default with `--ascii`,
+is a usage error (exit 2). `--max-width N` refuses (exit 1) a tree
+wider than N columns, naming the node that overflows.

data/doc/wave.md

@@ -0,0 +1,122 @@
+# Timing diagrams
+
+`wave` draws digital signals over time from a WaveDrom-like text: one
+signal per line, one character per time step.
+
+```ruby
+Tessella.wave(text, period: 4, ascii: false, ruler: false)  # => Block
+```
+
+```text
+tessella wave [--period N] [--ascii] [--ruler] [--max-width N] [file]
+```
+
+## Input
+
+Each line is `name: wave`, optionally followed by `| label label ...`
+naming the bus values in order. A lone `---` line draws an empty row
+between groups of signals.
+
+| Char | Step                                    |
+|------|-----------------------------------------|
+| `0`  | low                                     |
+| `1`  | high                                    |
+| `p`  | a clock period, starting high           |
+| `n`  | a clock period, starting low            |
+| `x`  | unknown (shaded)                        |
+| `z`  | high impedance (dotted)                 |
+| `=`  | a bus value, labelled by the next label |
+| `.`  | the previous state continues            |
+
+```text
+$ cat spi.txt
+clk:  p.......
+cs:   10.....1
+mosi: x=.=.=.x | A0 D0 D1
+miso: z..=.=.z | R0 R1
+---
+irq:  0....1.0
+```
+
+```text
+$ tessella wave spi.txt
+     ──┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐ ┌─┐
+clk    └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─
+
+     ────┐                       ┌───
+cs       └───────────────────────┘
+
+     ▒▒▒▒╳       ╳       ╳       ▒▒▒▒
+mosi ▒▒▒▒╳──A0───╳──D0───╳──D1───▒▒▒▒
+
+     ┄┄┄┄┄┄┄┄┄┄┄┄╳       ╳       ┄┄┄┄
+miso ┄┄┄┄┄┄┄┄┄┄┄┄╳──R0───╳──R1───┄┄┄┄
+
+
+                         ┌───────┐
+irq  ────────────────────┘       └───
+```
+
+## Options
+
+`--period N` (`period:`) is the number of columns per step, 4 by
+default; it must be 2 or more, since a clock needs a column to rise
+and one to fall. `--ruler` numbers the steps under the diagram.
+
+```text
+$ tessella wave --period 3 --ruler spi.txt
+     ─┐ ┌┐ ┌┐ ┌┐ ┌┐ ┌┐ ┌┐ ┌┐
+clk   └─┘└─┘└─┘└─┘└─┘└─┘└─┘└─
+
+     ───┐                 ┌──
+cs      └─────────────────┘
+
+     ▒▒▒╳     ╳     ╳     ▒▒▒
+mosi ▒▒▒╳─A0──╳─D0──╳─D1──▒▒▒
+
+     ┄┄┄┄┄┄┄┄┄╳     ╳     ┄┄┄
+miso ┄┄┄┄┄┄┄┄┄╳─R0──╳─R1──┄┄┄
+
+
+                    ┌─────┐
+irq  ───────────────┘     └──
+
+     0  1  2  3  4  5  6  7
+```
+
+`--ascii` draws `_ | X` and `x`, `-` for unknown and high impedance:
+
+```text
+$ tessella wave --ascii spi.txt
+     __   _   _   _   _   _   _   _
+clk    |_| |_| |_| |_| |_| |_| |_| |_
+
+     ____                         ___
+cs       |_______________________|
+
+     xxxx                        xxxx
+mosi xxxxX__A0___X__D0___X__D1___xxxx
+
+     ------------                ----
+miso ------------X__R0___X__R1___----
+
+
+                          _______
+irq  ____________________|       |___
+```
+
+A diagram that ends on `---` does not keep that last blank row: no
+block ends with a blank line.
+
+## Errors
+
+An unknown wave character, a line without `name:`, labels that do
+not match the `=` steps one for one, or a non-ASCII name or label
+under `--ascii` exits 1, naming the line:
+
+```text
+$ printf 'clk: pq\n' | tessella wave
+tessella wave: line 1: unknown wave character q
+```
+
+A `--period` below 2 is a usage error (exit 2).

data/examples/README.md

@@ -0,0 +1,103 @@
+# tessella examples
+
+Input files and Ruby scripts the documentation in [doc/](../doc/)
+draws its figures from. Run them from this directory, with tessella
+installed (`make install`), or from a checkout:
+
+```sh
+cd examples
+RUBYLIB=../lib ruby load.rb
+../exe/tessella chart --kind bar langs.csv
+```
+
+## Ruby scripts
+
+| Script           | Shows                                              | In                                  |
+|------------------|----------------------------------------------------|-------------------------------------|
+| `calibration.rb` | a line chart with measured points marked on it     | [charts](../doc/charts.md)          |
+| `load.rb`        | a bar chart beside a table, framed and captioned   | [composition](../doc/composition.md) |
+| `datasheet.rb`   | a register layout stacked over its timing diagram  | [composition](../doc/composition.md) |
+| `comment.rb`     | an ASCII tree indented as a source comment         | [composition](../doc/composition.md) |
+| `fit.rb`         | a table fitted to a width, with a multi-line cell  | [table](../doc/table.md)            |
+| `floors.rb`      | a table's per-column width floors, against one     | [table](../doc/table.md)            |
+| `gradient.rb`    | a `Raster` built in Ruby, drawn in three styles    | [images](../doc/images.md)          |
+| `refusals.rb`    | what the library refuses, and its messages         | [library](../doc/library.md)        |
+| `cjk.rb`         | a Unicode table and frame drawn for a CJK terminal | [targets](../doc/targets.md)        |
+| `lint.rb`        | the lint's findings and rulers, from Ruby          | [lint](../doc/lint.md)              |
+
+## Shell scripts
+
+POSIX sh, for FreeBSD and GNU/Linux alike; each finds its inputs
+from any directory. `tessella` must be on `PATH`:
+`PATH=../exe:$PATH sh report.sh` from a checkout.
+
+| Script       | Shows                                                    |
+|--------------|----------------------------------------------------------|
+| `trig.sh`    | awk's output piped into a chart                          |
+| `report.sh`  | a chart and a table from one CSV, composed via temp files |
+| `gallery.sh` | one picture in four styles, captioned, side by side      |
+| `comment.sh` | an ASCII tree as a C block comment, held to 72 columns   |
+| `rfc.sh`     | an RFC-style figure: seq and bitfield, ASCII, indented   |
+| `status.sh`  | exit 1 (bad data) told apart from exit 2 (bad call)      |
+| `disks.sh`   | one meter per input line, titles aligned, framed         |
+| `gauges.sh`  | upright meters side by side, one per input line          |
+| `dashboard.sh` | a chart, a table, meters, a sparkline in a framed grid |
+
+All are shown with their output in
+[doc/cli.md](../doc/cli.md#scripts).
+
+## Inputs
+
+| File           | For                     | Holds                                         |
+|----------------|-------------------------|-----------------------------------------------|
+| `langs.csv`    | `chart`, `table`        | three labels and values, with a header        |
+| `trig.txt`     | `chart`                 | `x sin cos`, 101 rows for x in 0..10          |
+| `cpu.txt`      | `chart --area`          | 60 load samples between 10 and 90             |
+| `temps.txt`    | `chart --xdate`         | a month of daily temperatures, ISO dates      |
+| `dose.txt`     | `chart --yerr`          | x, y and an error per point                   |
+| `os.csv`       | `chart --kind pie`      | nine shares, for the legend under the disc    |
+| `cities.csv`   | `--target cjk`          | a CJK label and an accented one               |
+| `ohlc.txt`     | `chart --kind candlestick` | a week of open/high/low/close prices       |
+| `growth.txt`   | `chart --xscale`        | x over four decades                           |
+| `hosts.csv`    | `chart --kind bar`      | three series per label, for grouped/stacked   |
+| `week.txt`     | `chart --kind heatmap`  | a load per day and per three hours            |
+| `neg.csv`      | `chart --kind bar`      | negative, positive and zero values            |
+| `normal.txt`   | `chart --kind histogram`| 200 roughly normal samples                    |
+| `samples.txt`  | `chart --kind box`      | three columns of samples                      |
+| `stem.txt`     | `chart --kind stem`     | one column of values                          |
+| `ages.txt`     | `chart --kind stem`     | two columns, for the back-to-back form        |
+| `bad.csv`      | `status.sh`             | a CSV with a value that is not a number       |
+| `plot.txt`     | `compose`               | a bar chart, as `tessella chart` printed it   |
+| `disks.txt`    | `disks.sh`              | mount points and how full each is             |
+| `boxes.txt`    | `compose fill`          | two hand-drawn boxes joined by a line         |
+| `note.txt`     | `compose`               | two lines of text                             |
+| `outline.txt`  | `tree`                  | an indented outline with notes                |
+| `kinds.csv`    | `table`                 | CSV with quoted fields holding commas         |
+| `sizes.tsv`    | `table --tsv`           | tab-separated rows                            |
+| `ipv4.txt`     | `bitfield`              | the IPv4 header, up to the source address     |
+| `ethernet.txt` | `bitfield`              | fields longer than a row                      |
+| `icmp.txt`     | `bitfield`              | a 32-bit ICMP header                           |
+| `spi.txt`      | `wave`                  | an SPI transfer: clock, select, buses, an IRQ |
+| `login.txt`    | `seq`                   | a login exchange with a self call and a note  |
+| `broken.txt`   | `lint`                  | a tab, a trailing blank, a wandering box side |
+| `drift.txt`    | `lint --border`         | a frame in a custom set, one side moved       |
+| `table-drift.txt` | `lint --ruler`       | a table whose verticals drift on one row      |
+| `notes.md`     | `lint --fences`         | Markdown: a table, prose, a flawed diagram    |
+| `notes-fixed.md` | `lint --target web`  | `notes.md`'s diagram redrawn for the web      |
+| `figure.c`     | `lint --forbid`         | a diagram in a C comment, holding `*/`        |
+| `wide.txt`     | `lint --no-wide`        | a CJK label                                   |
+| `shapes.pgm`   | `image --style petscii` | a ring and a wedge, black and white, 96 × 64  |
+| `disc.pgm`     | `image`                 | a 64 × 64 grey disc, bright at its centre     |
+
+`trig.txt`, `normal.txt`, `cpu.txt` and `temps.txt` were generated:
+
+```sh
+ruby -e 'puts "x sin cos"; 0.step(10, 0.1) { puts [it.round(1),
+    Math.sin(it), Math.cos(it)].join(" ") }' > trig.txt
+ruby -e 'srand 7; 200.times {
+    puts (Array.new(12) { rand }.sum - 6).round(3) }' > normal.txt
+ruby -e '60.times { puts (50 + (40 * Math.sin(it / 6.0))).round }' > cpu.txt
+ruby -e 't = Time.utc(2026, 10, 1); puts "date temp"; 30.times { |i|
+    puts "#{(t + (i * 86400)).strftime("%Y-%m-%d")} " \
+         "#{(12 + (6 * Math.sin(i / 4.0))).round(1)}" }' > temps.txt
+```

data/examples/ages.txt

@@ -0,0 +1,9 @@
+men women
+12 18
+15 22
+21 25
+23 31
+27 33
+34 36
+38 41
+45 44

data/examples/bad.csv

@@ -0,0 +1,3 @@
+lang,loc
+ruby,12
+c,many

data/examples/boxes.txt

@@ -0,0 +1,3 @@
+┌────┐  ┌────┐
+│    │──│ ok │
+└────┘  └────┘

data/examples/broken.txt

@@ -0,0 +1,4 @@
+a	b
+┌──┐ 
+│ab │
+└──┘

data/examples/calibration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# examples/calibration.rb: measured points marked on a fitted line.
+require "tessella"
+
+xs = (0..20).map { it * 0.5 }
+fit = Tessella.line(xs, xs.map { (0.5 * it) + 1 },
+                    name: "fit", width: 30, height: 6, title: "calibration",
+                    canvas: :block)
+fit.add([1, 3, 4.5, 7, 9], [1.4, 2.7, 3.0, 4.9, 5.4],
+        name: "measured", mark: "●")
+puts fit

data/examples/cities.csv

@@ -0,0 +1,4 @@
+city,pop
+東京,14
+Paris,2
+Zürich,0.4

data/examples/cjk.rb

@@ -0,0 +1,13 @@
+# 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

data/examples/comment.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# examples/comment.rb: a tree, in ASCII, as a comment block for a
+# source file kept to ASCII.
+require "tessella"
+
+outline = File.read("outline.txt")
+puts Tessella.indent(Tessella.tree(outline, ascii: true),
+                     prefix: "# ", ascii: true)

data/examples/comment.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+# examples/comment.sh -- a tree as a C block comment, for a header
+# kept to ASCII and 72 columns: --max-width fails the build (exit 1)
+# rather than let the figure wrap.
+# usage: sh comment.sh
+set -eu
+
+cd -- "$(dirname -- "$0")" || exit 1
+
+printf '/*\n'
+tessella tree --ascii --max-width 69 outline.txt |
+    tessella compose indent --ascii --prefix ' * ' -
+printf ' */\n'

data/examples/cpu.txt

@@ -0,0 +1,60 @@
+50
+57
+63
+69
+75
+80
+84
+87
+89
+90
+90
+89
+86
+83
+79
+74
+68
+62
+56
+49
+42
+36
+30
+24
+20
+16
+13
+11
+10
+10
+12
+14
+17
+22
+27
+33
+39
+45
+52
+59
+65
+71
+76
+81
+85
+88
+89
+90
+90
+88
+85
+82
+78
+72
+66
+60
+54
+47
+40
+34

data/examples/dashboard.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+# examples/dashboard.sh -- a dashboard: a chart, a table, meters and a
+# sparkline, each drawn to a file and laid out two to a row by
+# `compose grid`, then framed.
+# usage: sh dashboard.sh
+set -eu
+
+cd -- "$(dirname -- "$0")" || exit 1
+
+tmpdir=
+cleanup() { [ -z "$tmpdir" ] || rm -rf -- "$tmpdir"; }
+trap cleanup EXIT INT HUP TERM
+tmpdir=$(mktemp -d "${TMPDIR:-/tmp}/dashboard.XXXXXX") || exit 1
+
+tessella chart --kind bar --width 16 langs.csv > "$tmpdir/1"
+tessella table --style rounded langs.csv > "$tmpdir/2"
+{
+    tessella meter --width 12 --title cpu --title-width 4 0.62
+    tessella meter --width 12 --title disk --title-width 4 0.87
+} > "$tmpdir/3"
+tessella sparkline --width 20 < cpu.txt |
+    tessella compose caption --text 'cpu, last hour' - > "$tmpdir/4"
+tessella compose grid --columns 2 --gap 3 --align middle \
+    "$tmpdir/1" "$tmpdir/2" "$tmpdir/3" "$tmpdir/4" |
+    tessella compose frame --title status -

data/examples/datasheet.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# examples/datasheet.rb: a register layout over its timing, as a
+# datasheet draws them, stacked under one rule.
+require "tessella"
+
+register = Tessella.bitfield([["MODE", 4], ["DIV", 8], ["EN", 4]],
+                             word: 16)
+timing = Tessella.wave(<<~WAVE, period: 4)
+    sclk: p.......
+    cs:   10.....1
+    mosi: x=.=.=.x | CMD ADDR DATA
+WAVE
+puts Tessella.stack(Tessella.caption(register, text: "CTRL (0x04)",
+                                               above: true),
+                    timing, gap: 1, rule: "─")

data/examples/disks.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# examples/disks.sh -- one meter per line of "name fraction", their
+# titles padded to one width so the bars line up, framed: a small
+# status board.
+# usage: sh disks.sh [file]   (default disks.txt)
+set -eu
+
+cd -- "$(dirname -- "$0")" || exit 1
+input=${1:-disks.txt}
+
+while read -r name fraction; do
+    case $name in
+        '' | '#'*) continue ;;
+    esac
+    tessella meter --width 16 --title "$name" --title-width 6 \
+        -- "$fraction"
+done < "$input" |
+    tessella compose frame --title disks -

data/examples/disks.txt

@@ -0,0 +1,5 @@
+# name fraction
+/      0.62
+/home  0.87
+/var   0.31
+/tmp   0.04

data/examples/dose.txt

@@ -0,0 +1,7 @@
+dose effect err
+1 2.1 0.4
+2 3.0 0.5
+3 4.6 0.3
+4 5.2 0.8
+5 6.9 0.6
+6 7.4 1.0

data/examples/drift.txt

@@ -0,0 +1,4 @@
+*=================*
+! ruby is 12 kLOC !
+! c is the bulk    !
+*=================*

data/examples/ethernet.txt

@@ -0,0 +1,3 @@
+Destination MAC:48
+Source MAC:48
+EtherType:16

data/examples/figure.c

@@ -0,0 +1,5 @@
+/*
+ *   +--------+   */   +-------+
+ *   | client |------->| server|
+ *   +--------+        +-------+
+ */

data/examples/fit.rb

@@ -0,0 +1,16 @@
+# 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

data/examples/floors.rb

@@ -0,0 +1,21 @@
+# 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

data/examples/gallery.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# examples/gallery.sh -- one picture in several styles, each captioned
+# with its name, then set side by side.
+# usage: sh gallery.sh [image]   (default disc.pgm)
+set -eu
+
+cd -- "$(dirname -- "$0")" || exit 1
+image=${1:-disc.pgm}
+
+tmpdir=
+cleanup() { [ -z "$tmpdir" ] || rm -rf -- "$tmpdir"; }
+trap cleanup EXIT INT HUP TERM
+tmpdir=$(mktemp -d "${TMPDIR:-/tmp}/gallery.XXXXXX") || exit 1
+
+for style in ramp half quadrant edges; do
+    tessella image --style "$style" --width 14 -- "$image" |
+        tessella compose caption --text "$style" - > "$tmpdir/$style"
+done
+tessella compose beside --gap 3 --align bottom \
+    "$tmpdir/ramp" "$tmpdir/half" "$tmpdir/quadrant" "$tmpdir/edges"

data/examples/gauges.sh

@@ -0,0 +1,31 @@
+#!/bin/sh
+# examples/gauges.sh -- upright meters side by side, one per line of
+# "name fraction", bottoms aligned: a row of gauges.
+# usage: sh gauges.sh [file]   (default disks.txt)
+set -eu
+
+cd -- "$(dirname -- "$0")" || exit 1
+input=${1:-disks.txt}
+
+tmpdir=
+cleanup() { [ -z "$tmpdir" ] || rm -rf -- "$tmpdir"; }
+trap cleanup EXIT INT HUP TERM
+tmpdir=$(mktemp -d "${TMPDIR:-/tmp}/gauges.XXXXXX") || exit 1
+
+n=0
+while read -r name fraction; do
+    case $name in
+        '' | '#'*) continue ;;
+    esac
+    n=$((n + 1))
+    tessella meter --orientation vertical --height 6 --title "$name" \
+        -- "$fraction" > "$tmpdir/$n"
+done < "$input"
+
+set --
+i=1
+while [ "$i" -le "$n" ]; do
+    set -- "$@" "$tmpdir/$i"
+    i=$((i + 1))
+done
+tessella compose beside --gap 3 --align bottom "$@"