tessella 0.3.0

data/doc/library.md

@@ -0,0 +1,239 @@
+# The library
+
+```ruby
+require "tessella"
+```
+
+loads the drawing library and nothing else: no command line, no
+option parser, no gem. Every factory is a module function on
+`Tessella`; its result prints with `puts`.
+
+## Factories
+
+### Charts
+
+```ruby
+Tessella.line(x = nil, y, name: nil, mark: nil, **opts)    # => Chart
+Tessella.scatter(x = nil, y, name: nil, mark: nil, **opts)
+Tessella.stairs(x = nil, y, name: nil, mark: nil, style: :post, **opts)
+Tessella.density(x = nil, y, name: nil, mark: nil, **opts)
+Tessella.bar(labels, values, **opts)
+Tessella.histogram(values, bins: nil, closed: :left, **opts)
+Tessella.box(names, samples, **opts)     # samples: Array of Arrays
+Tessella.stem(values, other = nil, scale: nil, **opts)
+Tessella.heatmap(matrix, xlabels: nil, ylabels: nil, cell_width: 2,
+                 colormap: nil, min: nil, max: nil, **opts)
+Tessella.candlestick(x, open:, high:, low:, close:, **opts)
+Tessella.pie(labels, values, donut: false, rim: :cells, **opts)
+
+chart.add(x = nil, y, name: nil, color: nil, mark: nil)  # => chart
+chart.to_s                  # => String, framed, "\n"-terminated
+chart.render(io = $stdout)  # prints to_s
+```
+
+`x` defaults to `1..y.length`. `add` takes another series on a line,
+scatter, stairs or density chart. `stem`'s `other` is the second set
+of a back-to-back plot. `opts`, their defaults, and the bar options
+(`fill:`, `eighths:`, `track:`) are in [charts](charts.md#common-options).
+
+### Composition
+
+```ruby
+Tessella.frame(fig, title: nil, style: nil, pad: 1, fill: nil,
+               halo: true, ascii: false)
+Tessella.beside(fig, fig, ..., gap: 1, align: :top, ascii: false)
+Tessella.stack(fig, fig, ..., gap: 0, rule: nil, center: false,
+               ascii: false)
+Tessella.grid(fig, fig, ..., columns: 2, gap: 2, row_gap: 1,
+              align: :top, ascii: false)
+Tessella.indent(fig, prefix:, ascii: false)
+Tessella.caption(fig, text:, above: false, ascii: false)
+Tessella.shadow(fig, glyph: nil, ascii: false)
+Tessella.fill(fig, pattern: nil, halo: true, ascii: false)
+```
+
+Each takes any figure (a `Block`, a `String`, a chart) and returns a
+`Block`. See [composition](composition.md).
+
+### Diagrams and pictures
+
+```ruby
+Tessella.tree(outline, style: nil, ascii: false, root: nil)
+Tessella.table(rows, header: true, style: nil, ascii: false,
+               align: nil, title: nil, width: nil, min_width: 4,
+               color: false)                # min_width: N, or [N, ...]
+Tessella::Table.parse(text, tsv: false)        # => Array of rows
+Tessella.bitfield(fields, word: 32, octets: false, ruler: true,
+                  abbrev: false)
+Tessella.wave(text, period: 4, ascii: false, ruler: false)
+Tessella.seq(text, ascii: false, numbered: false, footer: false)
+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)
+Tessella.meter(fraction, style: :block, width: 20, title: nil,
+               title_width: nil, label: true, brackets: true,
+               orientation: :horizontal, height: 8, ascii: false)
+Tessella.sparkline(values, width: nil, min: nil, max: nil, ascii: false)
+Tessella.rule(width: 78, ornament: nil, style: :light, ascii: false)
+Tessella.text(str, style:, strict: false, ascii: false)  # => String
+```
+
+The figures return a `Block`. Pages: [tree](tree.md), [table](table.md),
+[bitfield](bitfield.md), [wave](wave.md), [seq](seq.md),
+[images](images.md), [sparkline](sparkline.md), [meter](meter.md),
+[rule](rule.md),
+[text](text.md). `text` returns a String, not a Block.
+
+### Lint
+
+```ruby
+Tessella.lint(source, width: 78, prefix: "", web: false, forbid: [],
+              no_wide: false, ascii: false, allow_mixed: false,
+              fences: false, geometry: false, borders: [])
+                                   # => Tessella::Lint::Report
+Tessella.alphabet(source)          # => "ascii" or "utf-8 <classes>"
+```
+
+`source` is a String or an IO. A report has `findings` (each a
+`Finding` with `line` and `message`), `clean?`, and `rulers` (each a
+`Ruler` with `line`, `width` and `verticals`). See [lint](lint.md).
+
+## Values
+
+### `Tessella::Block`
+
+```ruby
+block.lines            # => Array of String
+block.width            # => Integer, display columns
+block.height           # => Integer
+block.to_s             # => String, "\n"-terminated
+block.check_width!(n)  # raises ArgumentError if wider than n
+Tessella::Block.from(figure)  # a Block from a Block, String or chart
+```
+
+A block has no trailing blank on any line, no trailing blank line,
+and no tab.
+
+### `Tessella::Raster`
+
+```ruby
+Tessella::Raster.new(width:, height:, luma:)
+Tessella::Raster.decode(bytes)   # PNM or PNG; others via rmagick
+```
+
+A greyscale image: `luma` is `width * height` Floats in 0..1, row by
+row from the top. See [images](images.md#sources).
+
+### `Tessella::Borders::Set`
+
+```ruby
+Tessella::Borders::Set.new(tl, tr, bl, br, h, v)
+```
+
+A custom border, for `frame`'s and `table`'s `style:` and `lint`'s
+`borders:`. A six-glyph String in the same order does the same job;
+a table needs eleven, its five tees after these six. See
+[custom borders](composition.md#custom-borders).
+
+### `Tessella::Width`
+
+```ruby
+Tessella::Width.of("日本")         # => 4
+Tessella::Width.of("\e[1mab\e[0m") # => 2
+```
+
+The display width of a string: the columns a terminal gives it, wide
+characters two, combining marks and ANSI escapes none. Every figure
+is measured with it, which is why CJK labels line up.
+`Tessella::Width.class_of(char)` is a character's width class, `:N`,
+`:A` or `:W`; see [glyph sets](glyphs.md). Width counts grapheme
+clusters: an emoji sequence joined by ZWJ, or skin-toned, is one
+glyph, two columns wide.
+
+### Width targets
+
+```ruby
+Tessella.target = :cjk           # :term (default), :cjk or :web
+Tessella::Target.with(:web) { ... }
+```
+
+The target the figures are drawn for, per fiber; see
+[width targets](targets.md).
+
+### `Tessella::Glyphs`
+
+```ruby
+Tessella::Glyphs.fetch(kind, name)  # => GlyphSet
+Tessella::Glyphs.all                # => every GlyphSet
+glyph_set.glyphs; glyph_set.classes; glyph_set.mixed?
+```
+
+The named glyph sets the library draws with, and their width classes.
+See [glyph sets](glyphs.md).
+
+## Errors
+
+Every refusal is an `ArgumentError` with a message that names what is
+wrong — the option, the value, the line of input — raised before
+anything is drawn. A figure is either right or not returned. A value
+that cannot be drawn (not finite, out of range, out of order) raises
+`Tessella::ValueError`, a subclass, so a caller can tell bad data
+from a bad call; the command line exits 1 for the first and 2 for
+the second.
+
+```ruby
+# frozen_string_literal: true
+
+# examples/refusals.rb: what the library refuses, and how it says so.
+require "tessella"
+
+[
+    -> { Tessella.line([1, 2, 3], [1, 2]) },
+    -> { Tessella.bar(%w[a b], [1, Float::NAN]) },
+    -> { Tessella.line([1, 2], width: 0) },
+    -> { Tessella.line([1, 2], colour: true) },
+    -> { Tessella.tree("a\n   b\n  c") },
+    -> { Tessella.frame("é", ascii: true) }
+].each do |call|
+    call.call
+rescue ArgumentError => e
+    puts "#{e.class}: #{e.message}"
+end
+```
+
+```text
+$ ruby refusals.rb
+ArgumentError: x and y differ in length: 3 and 2
+Tessella::ValueError: value must be a finite number: NaN
+ArgumentError: width must be a positive Integer: 0
+ArgumentError: unknown option: :colour
+ArgumentError: line 3: indentation is not a multiple of 3
+ArgumentError: block 1 is non-ASCII under ascii: true
+```
+
+## The rules every figure keeps
+
+- **No trailing blank** on any line, and no trailing blank line.
+- **No escape code** unless `color: true`.
+- **No tab, no invisible glyph.** A blank cell is a space (U+0020),
+  never the empty braille pattern U+2800.
+- **`ascii: true` is ASCII from the first byte:** a figure is drawn
+  in ASCII glyphs, not drawn in Unicode and rewritten after, and any
+  text given to it that is not ASCII is refused. A bit field is
+  always ASCII.
+- **Values as given:** `12` prints `12`, not `12.0`, and a Float
+  keeps its digits.
+
+These are what make a figure safe to paste into a README, a commit
+message, a source comment or a man page.
+
+## Vendoring
+
+tessella has no runtime dependency, so it can travel as one file:
+
+```sh
+make bundle    # writes dist/tessella.rb: the library and the CLI
+```
+
+`dist/tessella.rb` is the library followed by the command line, in
+load order. Copy it into a project and `require_relative` it.

data/doc/lint.md

@@ -0,0 +1,270 @@
+# Linting
+
+A text figure that looks right in one editor can break on someone
+else's screen: a tab that expands differently, a trailing blank a
+formatter strips, a glyph that one font draws two cells wide, a box
+side one column off. `lint` checks a figure for these before it ships,
+whether tessella drew it or a person did.
+
+```ruby
+report = Tessella.lint(source, width: 78, prefix: "", suffix: "",
+                       web: false, forbid: [], no_wide: false, ascii: false,
+                       allow_mixed: false, fences: false,
+                       geometry: false, borders: [])
+report.findings   # => Array of Finding (line, message)
+report.clean?     # => true when there is none
+report.rulers     # => Array of Ruler (line, width, verticals)
+Tessella.alphabet(source)  # => "ascii", or "utf-8 <classes>"
+```
+
+```text
+tessella lint [--width N] [--prefix STR] [--suffix STR] [--ruler]
+              [--forbid SEQ]...
+              [--web] [--no-wide] [--ascii] [--allow-mixed]
+              [--fences] [--geometry] [--border GLYPHS]...
+              [--target T] [file ...]
+tessella lint --alphabet [file ...]
+```
+
+`source` is a String or an IO. The command reads its files, or stdin
+when none is given.
+
+## Output and exit status
+
+Each finding goes to stderr as `FILE:LINE: message` (`stdin` for
+stdin), one per line. The exit status is 0 when every input is clean,
+1 on any finding or a file that cannot be read (the other files are
+still linted), and 2 on a usage mistake. A clean file prints nothing:
+
+```text
+$ tessella lint plot.txt && echo clean
+clean
+```
+
+`broken.txt` is a four-line figure with a tab on its first line, a
+trailing blank on its second, and a box whose right side wanders:
+
+```text
+$ tessella lint broken.txt
+broken.txt:1: tab character
+broken.txt:2: trailing whitespace
+```
+
+## What is always checked
+
+- **Characters that have no fixed width:** tabs, invisible glyphs
+  (any character a terminal gives no column, such as a zero-width
+  space), invalid UTF-8.
+- **Look-alike spaces:** a no-break, thin, ideographic or other space
+  that is not U+0020, drawn as a blank and told from a space by no
+  display.
+- **Trailing blanks**, which an editor or a formatter may strip,
+  changing the figure behind the author's back.
+- **The column budget:** a line wider than `--width` (78 by default)
+  once `--prefix` is drawn before it and `--suffix` after it. The
+  prefix is what the figure will sit behind: `// `, `# `, ` * `, four
+  spaces of Markdown code; the suffix is what closes a comment wrapped
+  around each row, ` -->` or ` */`.
+
+```text
+$ tessella lint --width 16 --prefix '// ' note.txt
+note.txt:1: 18 columns rendered (budget 16)
+```
+
+- **ASCII and Unicode structure mixed in one figure**, such as `+--`
+  corners on a `│` side, which the reader's font rarely lines up.
+  `--allow-mixed` turns this off; a line reading `tessella:
+  allow-mixed` (or `artlint: allow-mixed`), in any comment syntax,
+  exempts the figure after it.
+- **Drift:** a vertical one column off its anchor on a few rows.
+- **Shadows:** a `░` drop shadow missing from a row or misplaced.
+
+## Geometry
+
+`--geometry` (`geometry: true`) reads the boxes and connectors as
+structure: a box's sides must stay in their columns down to its
+bottom edge, and a vertical or an arrow head must hang from something
+above it, not from blank space. It knows every box-drawing set (light,
+heavy, double, rounded, dashed, mixed junctions) and ASCII `+-|`
+boxes:
+
+```text
+$ tessella lint --geometry broken.txt
+broken.txt:1: tab character
+broken.txt:2: trailing whitespace
+broken.txt:3: side of box opened at line 2 col 1 is off at col 4
+broken.txt:3: connector '│' at col 5 hangs from ' '
+```
+
+It is off by default because it reads every `│` and `+` as structure,
+so a Markdown table or a `|` in prose would be flagged.
+
+A box drawn in a custom border set is not structure to the lint until
+it is declared: `--border GLYPHS` (`borders:`) takes six glyphs in the
+order `tl tr bl br h v`, as [frame's custom styles](composition.md#custom-borders)
+do. `drift.txt` is a frame in `****=!` whose right side moved on its
+third line:
+
+```text
+$ tessella lint --geometry drift.txt && \
+    echo 'clean: the custom box is not read'
+clean: the custom box is not read
+```
+
+```text
+$ tessella lint --geometry --border '****=!' drift.txt
+drift.txt:3: side of box opened at line 1 col 1 is off at col 19
+drift.txt:3: connector '!' at col 20 hangs from ' '
+```
+
+## Rulers
+
+`--ruler` prints, on stdout, each line's width and the columns of its
+verticals. Down a figure the verticals must agree, so a ruler shows a
+drift at a glance, even one `--geometry` is not asked to find:
+
+```text
+$ tessella lint --ruler table-drift.txt
+table-drift.txt:1: width=7
+table-drift.txt:2: width=7  verticals=1,4,7
+table-drift.txt:3: width=8  verticals=1,5,8
+table-drift.txt:4: width=7
+```
+
+## Markdown
+
+Linted whole, a Markdown file's prose and tables would be read as
+art. `--fences` (`fences: true`) lints each fenced block on its own,
+keeping the file's line numbers; a `tessella: allow-mixed` marker just
+before a fence exempts that block. `notes.md` holds a table, some
+prose, and a hand-drawn diagram whose connector is one column off:
+
+```text
+$ tessella lint --fences --geometry notes.md
+notes.md:13: connector '│' at col 20 hangs from '─'
+```
+
+A Markdown file is usually read on the web, so lint it for that
+target too. `--target web` also flags the `▶` at the end of the
+diagram's arrow, which a browser may draw as a wide emoji:
+
+```text
+$ tessella lint --fences --geometry --target web notes.md
+notes.md:11: emoji-capable U+25B6 ▶ (web target)
+notes.md:13: connector '│' at col 20 hangs from '─'
+```
+
+Redrawn with a small arrow head, `▸`, and the connector back on its
+`┬`, the figure in `notes-fixed.md` is clean for the web:
+
+```text
+$ sed -n 10,16p notes-fixed.md
+┌───────┐     ┌───────┐
+│ parse │────▸│ draw  │
+└───────┘     └───┬───┘
+                  │
+              ┌───┴───┐
+              │ print │
+              └───────┘
+```
+
+```text
+$ tessella lint --fences --geometry --target web notes-fixed.md && echo clean
+clean
+```
+
+## The target
+
+The options describe where the figure is going:
+
+- `--no-wide`: every wide (two-cell) glyph is a finding, for a target
+  whose font may not draw CJK at double width.
+
+```text
+$ tessella lint --no-wide wide.txt
+wide.txt:2: wide char U+65E5 日
+wide.txt:2: wide char U+672C 本
+wide.txt:2: wide char U+8A9E 語
+```
+
+```text
+$ printf '+---+\n|é  |\n+---+\n' | tessella lint --target cjk
+stdin:2: ambiguous U+00E9 é on aligned row (cjk target: 2 columns)
+```
+
+- `--target term|cjk|web`: measure with a [width target](targets.md)'s
+  widths. `web` is `--web`, and lets a glyph followed by U+FE0E pass;
+  `cjk` names an ambiguous glyph that is not box drawing on a row
+  that must line up, since it takes two columns there.
+- `--web`: a page in a browser. Glyphs some web renderers draw as
+  emoji, or two cells wide, are flagged.
+- `--ascii`: every non-ASCII glyph is a finding (it implies
+  `--no-wide`).
+- `--forbid SEQ`: lines holding SEQ are findings. SEQ is a sequence,
+  or a preset naming the comment syntax the figure sits in, so a line
+  that would end the comment early is caught: `xml`, `html`,
+  `c-block`, `rust`, `c-line`, `haskell`, `ocaml`, `pascal`, `d`,
+  `lisp`, `lua`, `python-doc`, `cdata`, `markdown-fence`. The option
+  repeats.
+
+```text
+$ tessella lint --forbid c-block figure.c
+figure.c:1: forbidden sequence "/*"
+figure.c:2: forbidden sequence "*/"
+figure.c:5: forbidden sequence "*/"
+```
+
+Here the comment's own opener and closer are caught too: lint the
+figure, not the comment around it.
+
+## The alphabet
+
+Before a figure goes into a file, `--alphabet` (`Tessella.alphabet`)
+says what that file already holds. It lints nothing and exits 0. A
+file that is pure ASCII should get an ASCII figure:
+
+```text
+$ tessella lint --alphabet figure.c langs.csv plot.txt notes.md
+figure.c: ascii
+langs.csv: ascii
+plot.txt: utf-8 box-drawing(7) blocks(27) other(1: U+00B7 ·)
+notes.md: utf-8 box-drawing(65) geometric(1)
+```
+
+## From Ruby
+
+```ruby
+# frozen_string_literal: true
+
+# examples/lint.rb: the lint from Ruby -- a figure tessella draws is
+# clean by construction; a hand-drawn one is reported line by line,
+# and the rulers show where its verticals stopped agreeing.
+require "tessella"
+
+chart = Tessella.bar(%w[ruby c rust], [12, 30, 7.5], width: 30)
+puts "chart: #{Tessella.lint(chart.to_s, geometry: true).clean?}"
+
+report = Tessella.lint(File.read("broken.txt"), geometry: true)
+report.findings.each { puts "broken.txt:#{it.line}: #{it.message}" }
+
+Tessella.lint(File.read("table-drift.txt")).rulers.each do |r|
+    puts "line #{r.line}: verticals #{r.verticals.inspect}"
+end
+```
+
+```text
+$ ruby lint.rb
+chart: true
+broken.txt:1: tab character
+broken.txt:2: trailing whitespace
+broken.txt:3: side of box opened at line 2 col 1 is off at col 4
+broken.txt:3: connector '│' at col 5 hangs from ' '
+line 1: verticals []
+line 2: verticals [1, 4, 7]
+line 3: verticals [1, 5, 8]
+line 4: verticals []
+```
+
+tessella holds its own output to this lint: a figure it draws is
+clean by construction, which is the point of the
+[rules every figure keeps](library.md#the-rules-every-figure-keeps).