tessella 0.3.0

data/doc/meter.md

@@ -0,0 +1,210 @@
+# Meters
+
+`meter` draws one line: a bar filled to a fraction, between brackets,
+with its percentage after it. A progress line in a log, a gauge in a
+status report, a column of them in a dashboard.
+
+```ruby
+Tessella.meter(fraction, style: :block, width: 20, title: nil,
+               title_width: nil, label: true, brackets: true,
+               orientation: :horizontal, height: 8,
+               ascii: false)                                # => Block
+```
+
+```text
+tessella meter [--style S] [--width N] [--title T] [--title-width N]
+               [--no-label] [--no-brackets] [--ascii]
+               [--orientation horizontal|vertical] [--height N] FRACTION
+```
+
+`FRACTION` is a number from 0 to 1, or a percentage, `45%`.
+
+```text
+$ tessella meter 0.5
+[██████████··········] 50 %
+```
+
+```text
+$ tessella meter --width 10 --title disk 37%
+disk [███▊······] 37 %
+```
+
+`--width` is the bar's cells, 20 by default. The default `block`
+style fills its last cell by eighths, so a bar moves by an eighth of
+a cell, not a whole one. `--no-label` drops the percentage and
+`--no-brackets` the brackets:
+
+```text
+$ tessella meter --no-label --no-brackets 0.25
+█████···············
+```
+
+## Styles
+
+A style is a fill glyph and a track glyph. The named ones are the
+meter sets in the [registry](glyphs.md#the-registry):
+
+```text
+$ for s in arrow chevron classic rectangle wave block box circle star; do \
+    tessella meter --style $s --width 12 --title $s --title-width 9 0.6; \
+  done
+arrow     [▸▸▸▸▸▸▸▹▹▹▹▹] 60 %
+chevron   [›››››››     ] 60 %
+classic   [=======     ] 60 %
+rectangle [▮▮▮▮▮▮▮▯▯▯▯▯] 60 %
+wave      [~~~~~~~_____] 60 %
+block     [███████▎····] 60 %
+box       [■■■■■■■□□□□□] 60 %
+circle    [●●●●●●●○○○○○] 60 %
+star      [★★★★★★★☆☆☆☆☆] 60 %
+```
+
+`blade` (`▰▱`) and `button` (`⦿⦾`) exist too, but many fonts lack
+their glyphs: try them in the reader's font first.
+`tessella glyphs meter` lists every set with its width class.
+
+A style of one's own is two glyphs, fill then track, one column each
+and of one [width class](glyphs.md#width-classes):
+
+```text
+$ tessella meter --style '▰▱' 0.33
+[▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱▱▱] 33 %
+```
+
+```text
+$ tessella meter --style '■░' 0.5
+tessella meter: meter style "■░" mixes width classes: A, N
+```
+
+## Upright meters
+
+`--orientation vertical` stands the bar up: a column `--height` cells
+tall (8 by default), filled from the bottom, between `─` caps (`-`
+under `--ascii`, none with `--no-brackets`), the title centred above
+and the percentage below. The block style tops its column with an
+eighth, `▁` to `▇`. An upright meter takes `--height`, not
+`--width`, and the other way round across; either one in the wrong
+orientation is a usage error.
+
+```text
+$ tessella meter --orientation vertical --height 6 --title cpu 0.62
+cpu
+ ─
+ ·
+ ·
+ ▆
+ █
+ █
+ █
+ ─
+62 %
+```
+
+Upright meters stand side by side with `compose beside`, their
+bottoms aligned. `gauges.sh` draws one per line of `disks.txt`:
+
+```sh
+#!/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 "$@"
+```
+
+```text
+$ sh gauges.sh
+ /     /home   /var   /tmp
+ ─       ─      ─      ─
+ ·       ▂      ·      ·
+ ·       █      ·      ·
+ ▆       █      ·      ·
+ █       █      ·      ·
+ █       █      ▇      ·
+ █       █      █      ▂
+ ─       ─      ─      ─
+62 %   87 %    31 %   4 %
+```
+
+## ASCII
+
+`--ascii` draws the classic style, `=` on a blank track:
+
+```text
+$ tessella meter --ascii 0.5
+[==========          ] 50 %
+```
+
+## A status board
+
+Meters are blocks like any figure, so they stack and frame.
+`--title-width N` (`title_width:`) pads a title to N columns, so a
+column of meters lines up; a longer title is refused (exit 2).
+`disks.sh` reads `name fraction` lines and draws one meter each:
+
+```sh
+#!/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 -
+```
+
+```text
+$ sh disks.sh
+┌──────────── disks ─────────────┐
+│ /      [█████████▉······] 62 % │
+│ /home  [█████████████▉··] 87 % │
+│ /var   [█████···········] 31 % │
+│ /tmp   [▋···············] 4 %  │
+└────────────────────────────────┘
+```
+
+## Errors
+
+A fraction outside 0..1 (or 0%..100%), an unknown style, a style that
+is not two glyphs of one class, or a missing fraction is a usage error,
+exit 2:
+
+```text
+$ tessella meter 1.5
+tessella meter: fraction must be 0..1 or 0%..100%: "1.5"
+```

data/doc/rule.md

@@ -0,0 +1,51 @@
+# Rules
+
+`rule` draws a divider: one line in a rule style, with an optional
+ornament centred in it. It separates the parts of a report, a log, a
+plain-text document.
+
+```ruby
+Tessella.rule(width: 78, ornament: nil, style: :light,
+              ascii: false)                          # => Block
+```
+
+```text
+tessella rule [--width N] [--ornament T] [--style S] [--ascii]
+```
+
+```text
+$ tessella rule --width 30
+──────────────────────────────
+```
+
+The ornament is any text, centred by display width with a blank on
+each side:
+
+```text
+$ tessella rule --width 30 --ornament '✦'
+───────────── ✦ ──────────────
+```
+
+```text
+$ tessella rule --width 30 --style double --ornament 'Part II'
+══════════ Part II ═══════════
+```
+
+The styles are the rule sets in the [registry](glyphs.md#the-registry):
+`light` (`─`, the default), `heavy` (`━`), `double` (`═`), `dashed`
+(`┄`) and `ascii` (`-`). `--ascii` draws `-`, and refuses an ornament
+that is not ASCII:
+
+```text
+$ tessella rule --width 30 --ascii --ornament '* * *'
+----------- * * * ------------
+```
+
+```text
+$ tessella rule --ascii --ornament '✦'
+tessella rule: ornament is non-ASCII under ascii: true
+```
+
+`stack`'s `rule:` draws a plain line between figures; `rule` is the
+one to reach for when the line needs a style or an ornament, or
+stands alone.

data/doc/seq.md

@@ -0,0 +1,169 @@
+# Sequence diagrams
+
+`seq` draws a UML-style sequence diagram: participants across the
+top, their lifelines down, and messages between them in order.
+
+```ruby
+Tessella.seq(text, ascii: false, numbered: false, footer: false)
+                                                       # => Block
+```
+
+```text
+tessella seq [--ascii] [--numbered] [--footer] [--max-width N] [file]
+```
+
+## Input
+
+One statement per line; blank lines and `#` comments are skipped.
+
+| Statement               | Draws                                   |
+|-------------------------|-----------------------------------------|
+| `participant A`         | declares A, fixing its column           |
+| `A -> B: text`          | a call, solid arrow                     |
+| `A --> B: text`         | a reply, dashed arrow                   |
+| `A ->> B: text`         | an asynchronous message, double head    |
+| `A -> A: text`          | a self call, a loop right of A          |
+| `note over A: text`     | a note on A's lifeline                  |
+| `note over A,B: text`   | a note spanning A to B                  |
+
+A name is a run of letters, digits, `_`, `.` or `-`, not ending in
+`-`, so `A-->B` reads as a reply with or without blanks. Participants
+take their columns in the order they are declared, or first appear;
+columns widen to fit every label, never truncating one.
+
+```text
+$ cat login.txt
+participant Browser
+participant Server
+participant DB
+Browser -> Server: POST /login
+Server -> DB: SELECT user
+DB --> Server: row
+Server -> Server: check hash
+note over Server,DB: bcrypt, cost 12
+Server ->> DB: log attempt
+Server --> Browser: 200 + cookie
+```
+
+```text
+$ tessella seq login.txt
+┌─────────┐    ┌─────────┐        ┌─────┐
+│ Browser │    │ Server  │        │ DB  │
+└────┬────┘    └────┬────┘        └──┬──┘
+     │              │                │
+     │ POST /login  │                │
+     │─────────────►│                │
+     │              │                │
+     │              │  SELECT user   │
+     │              │───────────────►│
+     │              │                │
+     │              │      row       │
+     │              │◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄│
+     │              │                │
+     │              │──┐             │
+     │              │  │ check hash  │
+     │              │◄─┘             │
+     │              │                │
+     │              ┌────────────────┐
+     │              │bcrypt, cost 12 │
+     │              └────────────────┘
+     │              │                │
+     │              │  log attempt   │
+     │              │──────────────►►│
+     │              │                │
+     │ 200 + cookie │                │
+     │◄┄┄┄┄┄┄┄┄┄┄┄┄┄│                │
+     │              │                │
+```
+
+## Arrow heads
+
+Calls and replies end in `►` or `◄`, asynchronous messages in a
+double head, `►►` or `◄◄`, in every [width target](targets.md). These
+heads read at a glance and never turn into emoji in a browser, but a
+font that lacks them draws them at a fallback width
+([on the web](targets.md#web)). Under `--ascii` they are `>` and `<`,
+and `>>` and `<<` for an asynchronous message.
+
+## Options
+
+`--numbered` numbers the messages; `--footer` repeats the participant
+boxes under the lifelines, which helps a long diagram:
+
+```text
+$ tessella seq --numbered --footer login.txt
+┌─────────┐       ┌─────────┐           ┌─────┐
+│ Browser │       │ Server  │           │ DB  │
+└────┬────┘       └────┬────┘           └──┬──┘
+     │                 │                   │
+     │ 1. POST /login  │                   │
+     │────────────────►│                   │
+     │                 │                   │
+     │                 │  2. SELECT user   │
+     │                 │──────────────────►│
+     │                 │                   │
+     │                 │      3. row       │
+     │                 │◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄│
+     │                 │                   │
+     │                 │──┐                │
+     │                 │  │ 4. check hash  │
+     │                 │◄─┘                │
+     │                 │                   │
+     │                 ┌───────────────────┐
+     │                 │  bcrypt, cost 12  │
+     │                 └───────────────────┘
+     │                 │                   │
+     │                 │  5. log attempt   │
+     │                 │─────────────────►►│
+     │                 │                   │
+     │ 6. 200 + cookie │                   │
+     │◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄│                   │
+     │                 │                   │
+┌────┴────┐       ┌────┴────┐           ┌──┴──┐
+│ Browser │       │ Server  │           │ DB  │
+└─────────┘       └─────────┘           └─────┘
+```
+
+`--ascii` draws in `+ - |`, with `- - -` for a reply:
+
+```text
+$ tessella seq --ascii login.txt
++---------+    +---------+        +-----+
+| Browser |    | Server  |        | DB  |
++----+----+    +----+----+        +--+--+
+     |              |                |
+     | POST /login  |                |
+     |------------->|                |
+     |              |                |
+     |              |  SELECT user   |
+     |              |--------------->|
+     |              |                |
+     |              |      row       |
+     |              |<- - - - - - - -|
+     |              |                |
+     |              |--+             |
+     |              |  | check hash  |
+     |              |<-+             |
+     |              |                |
+     |              +----------------+
+     |              |bcrypt, cost 12 |
+     |              +----------------+
+     |              |                |
+     |              |  log attempt   |
+     |              |-------------->>|
+     |              |                |
+     | 200 + cookie |                |
+     |<- - - - - - -|                |
+     |              |                |
+```
+
+## Errors
+
+A line that is none of the statements above is refused, quoting it
+(exit 1); so is input with no statement, and a non-ASCII name under
+`--ascii`.
+
+```text
+$ printf 'A => B: x\n' | tessella seq
+tessella seq: line 1: A => B: x
+```

data/doc/sparkline.md

@@ -0,0 +1,63 @@
+# Sparklines
+
+A sparkline is a chart one line high and one cell a value, small
+enough to sit in a sentence, a table cell or a log line: ▁▂▄▃█▁▂.
+
+```ruby
+Tessella.sparkline(values, width: nil, min: nil, max: nil,
+                   ascii: false)                    # => Block
+```
+
+```text
+tessella sparkline [--width N] [--min A] [--max B] [--ascii] [VALUE ...]
+```
+
+The command reads the values given, or stdin when there are none,
+split on blanks and commas:
+
+```text
+$ tessella sparkline 1 5 22 13 53 2 8
+▁▂▄▃█▁▂
+```
+
+```text
+$ printf '1,2\n3 4\n' | tessella sparkline
+▁▃▆█
+```
+
+Each value takes one of eight steps, `▁` to `█`, from the lowest value
+to the highest. Under `--ascii` the steps are `_.-:=+*#`:
+
+```text
+$ tessella sparkline --ascii 1 5 22 13 53 2 8
+_.:-#_.
+```
+
+## Width and range
+
+`--width N` averages the values into N cells, for a long series in a
+short space (with fewer values than cells, each is repeated to fill
+them). `cpu.txt` holds 60 values:
+
+```text
+$ tessella sparkline --width 20 < cpu.txt
+▅▇██▇▆▄▃▂▁▁▃▄▆▇██▇▅▄
+```
+
+By default the range is the values' own, so every sparkline uses all
+eight steps. `--min` and `--max` fix it, so several sparklines share
+one scale and can be compared:
+
+```text
+$ tessella sparkline --min 0 --max 100 10 50 90
+▂▅▇
+```
+
+## Errors
+
+A value that is not a number is bad input, exit 1:
+
+```text
+$ tessella sparkline 1 x
+tessella sparkline: not a number: "x"
+```