tessella 0.3.0

data/lib/tessella/compose_fill.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Tessella
+    # fill: a pattern in a figure's enclosed blank cells (DESIGN.md,
+    # "Blocks and composition"). A blank cell reachable from the
+    # figure's edge through blank cells is outside and stays blank;
+    # every other blank cell -- inside a frame, a box, any closed
+    # region -- takes the pattern, its glyphs tiled diagonally. Text
+    # and lines are never touched, and a halo of blank cells keeps the
+    # pattern off text (a glyph that is neither box drawing nor + - |):
+    # halo: true leaves the cell each side blank, :around the cells
+    # above and below too, false none. The pattern is a name from
+    # Glyphs::PATTERNS (light, hatch, stipple, ...) or glyphs of one's
+    # own, each one visible column and all of one width class; under
+    # ascii: true it must be ASCII (colons by default). frame(fill:)
+    # fills only the background the frame adds: what floods in from
+    # just inside its border, never a region the content encloses.
+    module Compose
+        FILL = :light
+        ASCII_FILL = :colons
+
+        HALOS = [true, false, :around].freeze
+        STRUCTURE = /[\u2500-\u257F+|-]/
+
+        def self.fill(figure, pattern: nil, ascii: Target.ascii?, halo: true)
+            block, = blocks([figure], ascii)
+            glyphs = pattern_glyphs!(pattern, ascii)
+            grid, codes = cell_grid(block)
+            inside = haloed(grid, enclosed(grid), halo)
+            Block.new(paint(grid, codes, inside, glyphs))
+        end
+
+        # The background a frame adds to a block it has just framed.
+        def self.fill_frame(framed, pattern, ascii, halo)
+            glyphs = pattern_glyphs!(pattern, ascii)
+            grid, codes = cell_grid(framed)
+            region = flood(grid, inner_ring(grid))
+            Block.new(paint(grid, codes, haloed(grid, region, halo), glyphs))
+        end
+
+        # The blank cells just inside a frame's border.
+        def self.inner_ring(grid)
+            last_r = grid.size - 2
+            last_c = grid.first.size - 2
+            ring = (1..last_r).flat_map { |r| [[r, 1], [r, last_c]] } +
+                   (1..last_c).flat_map { |c| [[1, c], [last_r, c]] }
+            ring.select { |r, c| grid[r][c] == " " }
+        end
+
+        def self.pattern_glyphs!(pattern, ascii)
+            name = pattern || (ascii ? ASCII_FILL : FILL)
+            glyphs = pattern_text(name).chars
+            glyphs.each { glyph!(it, "pattern glyph", ascii) }
+            classes = Width.classes(glyphs.join)
+            return glyphs if classes.size <= 1
+
+            raise ArgumentError, "pattern #{name.inspect} mixes width " \
+                                 "classes: #{classes.join(", ")}"
+        end
+
+        # A name in Glyphs::PATTERNS, else the glyphs themselves.
+        def self.pattern_text(name)
+            key = Borders.name(name)
+            return Glyphs::PATTERNS[key] if Glyphs::PATTERNS.key?(key)
+            raise ArgumentError, "empty pattern" if name.to_s.empty?
+
+            name.to_s
+        end
+
+        SGR = /\e\[[0-9;]*m/
+        TOKEN = /(?:#{SGR})*(?:\X|\z)/o
+
+        # The block as rows of one-column cells, a wide glyph (a grapheme
+        # cluster, an emoji sequence or an accented letter whole) and an
+        # empty tail cell after it, every row the block's width; and
+        # the colour codes before each cell ({ [r, c] => codes }, a
+        # row's trailing ones at [r, :end]), set aside so a coloured
+        # block is measured and filled by what it shows.
+        def self.cell_grid(block)
+            codes = {}
+            grid = block.lines.each_with_index.map do |line, r|
+                cells = row_cells(line, r, codes)
+                cells + Array.new(block.width - cells.size, " ")
+            end
+            [grid, codes]
+        end
+
+        def self.row_cells(line, r, codes)
+            line.scan(TOKEN).each_with_object([]) do |token, cells|
+                lead = token[/\A(?:#{SGR})*/o]
+                glyph = token.delete_prefix(lead)
+                next codes[[r, :end]] = lead if glyph.empty?
+
+                codes[[r, cells.size]] = lead unless lead.empty?
+                cells << glyph
+                cells.concat(Array.new([Width.cluster(glyph) - 1, 0].max, ""))
+            end
+        end
+
+        # The blank cells not reachable from the edge: { [r, c] => true }.
+        def self.enclosed(grid)
+            outside = flood(grid)
+            grid.each_with_index.with_object({}) do |(row, r), inside|
+                row.each_index do |c|
+                    inside[[r, c]] = true if row[c] == " " && !outside[[r, c]]
+                end
+            end
+        end
+
+        def self.flood(grid, starts = edge_blanks(grid))
+            seen = {}
+            todo = starts.dup
+            until todo.empty?
+                r, c = todo.pop
+                next if seen[[r, c]]
+
+                seen[[r, c]] = true
+                todo.concat(blank_neighbours(grid, r, c))
+            end
+            seen
+        end
+
+        def self.edge_blanks(grid)
+            last_r = grid.size - 1
+            last_c = (grid.first&.size || 0) - 1
+            cells = grid.each_index.flat_map { |r| [[r, 0], [r, last_c]] } +
+                    (0..last_c).flat_map { |c| [[0, c], [last_r, c]] }
+            cells.select { |r, c| grid[r][c] == " " }
+        end
+
+        def self.blank_neighbours(grid, r, c)
+            [[r - 1, c], [r + 1, c], [r, c - 1], [r, c + 1]].select do |y, x|
+                y.between?(0, grid.size - 1) &&
+                    x.between?(0, grid[y].size - 1) && grid[y][x] == " "
+            end
+        end
+    end
+
+    # The halo: blank cells fill keeps beside text, so a label keeps
+    # its word shape. Text is any glyph but box drawing and + - |.
+    module Compose
+        # The region less the cells a halo keeps blank around text.
+        def self.haloed(grid, region, halo)
+            unless HALOS.include?(halo)
+                raise ArgumentError, "halo must be true, false or :around: " \
+                                     "#{halo.inspect}"
+            end
+            return region unless halo
+
+            region.reject { |(r, c), _| near_text?(grid, r, c, halo) }
+        end
+
+        def self.near_text?(grid, r, c, halo)
+            near = [[r, c - 1], [r, c + 1]]
+            near += [[r - 1, c], [r + 1, c]] if halo == :around
+            near.any? { |y, x| text_cell?(grid, y, x) }
+        end
+
+        def self.text_cell?(grid, r, c)
+            cell = r.between?(0, grid.size - 1) && c >= 0 && grid[r][c]
+            cell && !["", " "].include?(cell) && !cell.match?(STRUCTURE)
+        end
+
+        def self.paint(grid, codes, inside, glyphs)
+            grid.each_with_index.map do |row, r|
+                painted = row.each_with_index.map do |cell, c|
+                    fill = glyphs[(r + c) % glyphs.size]
+                    "#{codes[[r, c]]}#{inside[[r, c]] ? fill : cell}"
+                end
+                painted.join + codes[[r, :end]].to_s
+            end
+        end
+    end
+
+    def self.fill(...) = Compose.fill(...)
+end

data/lib/tessella/compose_grid.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Tessella
+    # grid: figures in rows of columns: (DESIGN.md, "Blocks and
+    # composition") -- the dashboard layout other libraries have, built
+    # from beside and stack: each row's figures side by side, gap:
+    # columns apart and aligned by align:, the rows stacked row_gap:
+    # rows apart. A short last row stays short.
+    module Compose
+        GRID = { columns: 2, gap: 2, row_gap: 1, align: :top }.freeze
+
+        # (*figures, columns: 2, gap: 2, row_gap: 1, align: :top,
+        # ascii: false)
+        def self.grid(*figures, ascii: Target.ascii?, **layout)
+            raise ArgumentError, "grid takes one figure or more" if
+                figures.empty?
+
+            o = GRID.merge(layout)
+            Check.positive_integer!(o[:columns], "columns")
+            rows = blocks(figures, ascii).each_slice(o[:columns]).map do |row|
+                grid_row(row, o, ascii)
+            end
+            return rows.first if rows.size == 1
+
+            stack(*rows, gap: o[:row_gap], ascii: ascii)
+        end
+
+        def self.grid_row(row, o, ascii)
+            return row.first if row.size == 1
+
+            beside(*row, gap: o[:gap], align: o[:align], ascii: ascii)
+        end
+    end
+
+    def self.grid(...) = Compose.grid(...)
+end

data/lib/tessella/compose_shadow.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Tessella
+    # shadow: a drop shadow, as the ascii-art skill's ui.md draws it
+    # and the lint checks it (DESIGN.md, "Blocks and composition"): the
+    # glyph one column right of every row but the first, and a bottom
+    # bar one row down, from one column in to that same column, so the
+    # L closes at both ends. ░ by default, # under ascii: true.
+    module Compose
+        SHADOW = "░"
+        ASCII_SHADOW = "#"
+
+        def self.shadow(figure, glyph: nil, ascii: Target.ascii?)
+            block, = blocks([figure], ascii)
+            g = shadow_glyph!(glyph, ascii)
+            width = block.width
+            rows = block.lines.each_with_index.map do |line, i|
+                i.zero? ? line : Width.ljust(line, width) + g
+            end
+            Block.new([*rows, " #{g * width}"])
+        end
+
+        def self.shadow_glyph!(glyph, ascii)
+            glyph!(glyph || (ascii ? ASCII_SHADOW : SHADOW), "shadow glyph",
+                   ascii)
+        end
+
+        # A glyph drawn into a figure: one visible column, ASCII under
+        # ascii: true.
+        def self.glyph!(glyph, what, ascii)
+            unless glyph.is_a?(String) && glyph.length == 1 &&
+                   Width.of(glyph) == 1 && glyph.match?(/\A[[:graph:]]\z/)
+                raise ArgumentError, "#{what} must be one visible column: " \
+                                     "#{glyph.inspect}"
+            end
+            structure!(what, glyph, ascii)
+        end
+    end
+
+    def self.shadow(...) = Compose.shadow(...)
+end

data/lib/tessella/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tessella
+    # The family every tessella refusal belongs to.
+    class Error < StandardError; end
+
+    # A value in the data that cannot be drawn: not a finite number,
+    # a negative pie slice, a candle whose low and high do not hold
+    # it, an empty sample. An ArgumentError, as every bad argument
+    # is, kept apart so the command line can call it bad input (exit
+    # 1) rather than a usage mistake (exit 2).
+    class ValueError < ArgumentError; end
+end

data/lib/tessella/frame.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Turns a ready-made body of cells into text: border, title, axis
+    # labels and legend (DESIGN.md, "Frame and Color"). Frame knows
+    # nothing of data; the body and every label arrive as given. Labels
+    # are measured in display columns (Width), not characters, so a
+    # wide-character label keeps the frame aligned.
+    # The lines a Frame draws under its bottom border: a row of text
+    # aligned with the body (under:), and the x-axis extremes at its two
+    # ends (bottom:). Kept apart so Frame's own class body stays under
+    # budget.
+    module FrameBelow
+        private
+
+        # Rows of text under the body, column for column (a column
+        # chart's names, a legend wrapped by Legend).
+        def under_line
+            return nil if @under.to_s.empty?
+
+            indent = lead + (" " * Width.of(border_part(:l)))
+            @under.lines(chomp: true).map { indent + it }.join("\n")
+        end
+
+        def bottom_extremes_line
+            left_text, right_text = Array(@bottom)
+            return nil unless left_text || right_text
+
+            extremes_line(left_text.to_s, right_text.to_s)
+        end
+
+        # The two ends of the x axis, a space between them at least,
+        # even when they are wider than the body.
+        def extremes_line(left_text, right_text)
+            gap = extremes_gap(left_text, right_text)
+            gap = " " if gap.empty? && !left_text.empty? && !right_text.empty?
+            lead + left_text + gap + right_text
+        end
+
+        def extremes_gap(left_text, right_text)
+            lw = Width.of(left_text)
+            cnt1 = ((width / 2.0) - lw).round
+            cnt2 = width - Width.of(right_text) - lw + 2 - cnt1
+            pad(cnt1) + pad(cnt2)
+        end
+
+        def pad(count) = count.positive? ? " " * count : ""
+    end
+
+    class Frame
+        include FrameBelow
+
+        MARGIN = 3
+        GUTTER = 1
+
+        UNICODE_BORDERS = {
+            box: { tl: "┌", tr: "┐", bl: "└", br: "┘",
+                   t: "─", b: "─", l: "│", r: "│" },
+            bar: { tl: "┌", tr: "┐", bl: "└", br: "┘",
+                   t: " ", b: " ", l: "┤", r: nil }
+        }.freeze
+
+        ASCII_BORDERS = {
+            box: { tl: "+", tr: "+", bl: "+", br: "+",
+                   t: "-", b: "-", l: "|", r: "|" },
+            bar: { tl: "+", tr: "+", bl: "+", br: "+",
+                   t: " ", b: " ", l: "|", r: nil }
+        }.freeze
+
+        # DESIGN.md fixes this exact keyword interface: eleven named
+        # options.
+        # rubocop:disable-next Metrics/ParameterLists
+        def initialize(body:, border: :box, ascii: false, color: false,
+                       title: nil, xlabel: nil, ylabel: nil,
+                       left: {}, right: {}, bottom: nil, under: nil)
+            @body = body
+            @border = border == :none ? nil : borders(ascii).fetch(border)
+            @color = color
+            @title = title
+            @xlabel = xlabel
+            @ylabel = ylabel
+            @left = left
+            @right = right
+            @bottom = bottom
+            @under = under
+        end
+
+        # Under target :web, emoji-capable glyphs kept as text (Target).
+        def to_s
+            Target.adapt("#{lines.map(&:rstrip).join("\n")}\n")
+        end
+
+        private
+
+        def borders(ascii) = ascii ? ASCII_BORDERS : UNICODE_BORDERS
+        def width = @body.first&.length || 0
+        def height = @body.length
+        def ylabel = @ylabel.to_s.empty? ? nil : @ylabel
+
+        def max_left = @max_left ||= left_column_width
+
+        def lines
+            [title_line, top_line, *row_lines, bottom_line, under_line,
+             bottom_extremes_line, xlabel_line].compact
+        end
+
+        def left_column_width
+            base = @left.values.map { Width.of(it) }.max || 0
+            ylabel ? base + Width.of(ylabel) + 1 : base
+        end
+
+        def lead
+            " " * (MARGIN + max_left + GUTTER)
+        end
+
+        def title_line = label_line(@title, width)
+        def xlabel_line = label_line(@xlabel, width)
+
+        # Each line of text centred under the body.
+        def label_line(text, width)
+            return nil if text.to_s.empty?
+
+            text.to_s.lines(chomp: true).map do |line|
+                offset = [((width / 2.0) - (Width.of(line) / 2.0)).round, 0].max
+                lead + (" " * offset) + line
+            end.join("\n")
+        end
+
+        def top_line
+            return nil unless @border
+
+            lead + @border[:tl] + (@border[:t] * width) + @border[:tr]
+        end
+
+        def bottom_line
+            return nil unless @border
+
+            lead + @border[:bl] + (@border[:b] * width) + @border[:br]
+        end
+
+        def row_lines = (0...height).map { row_line(it) }
+
+        def row_line(row)
+            left_str = @left.fetch(row, "")
+            right_str = @right.fetch(row, "")
+            left_part(row, left_str) + (" " * GUTTER) + border_part(:l) +
+                body_row(row) + border_part(:r) + (" " * GUTTER) + right_str
+        end
+
+        def left_part(row, left_str)
+            prefix = ylabel_row?(row) ? ylabel : ""
+            fill = max_left - Width.of(prefix) - Width.of(left_str)
+            (" " * MARGIN) + prefix + (" " * fill) + left_str
+        end
+
+        def ylabel_row?(row) = ylabel && row == ylabel_row
+        def ylabel_row = (height / 2.0).round - 1
+
+        def border_part(side) = @border&.fetch(side, nil) || ""
+
+        def body_row(row)
+            cells = @body[row]
+            return cells.map(&:char).join unless @color
+
+            cells.chunk_while { |a, b| a.color == b.color }.map do |run|
+                Color.wrap(run.map(&:char).join, run.first.color)
+            end.join
+        end
+    end
+end

data/lib/tessella/glyphs.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Tessella
+    # The named glyph sets (DESIGN.md, "Glyphs"), from the ascii-art
+    # skill's glyph palette and ui.md: border styles, fill patterns,
+    # meter fill/track pairs, rule lines and tone ramps, each with the
+    # width classes its glyphs fall into, computed from Width, never
+    # typed in. A set whose glyphs span two classes is "mixed": fine in
+    # Western terminals, but it changes length in CJK-configured ones.
+    # Each set also says which width targets it is safe for.
+    module Glyphs
+        GlyphSet = Data.define(:kind, :name, :glyphs, :note) do
+            def classes = Width.classes(glyphs)
+            def mixed? = classes.size > 1
+            def targets = Glyphs.targets(glyphs)
+        end
+
+        # The targets (Target) a glyph set is safe for: term always;
+        # cjk with no ambiguous glyph, as a CJK terminal widens those
+        # and nothing else; web with no wide glyph, which browser fonts
+        # do not hold to two columns, and no emoji-capable one.
+        def self.targets(glyphs)
+            chars = glyphs.chars.reject { it == " " }
+            [:term,
+             (:cjk unless Width.classes(glyphs).include?(:A)),
+             (:web unless chars.any? { web_risk?(it) })].compact
+        end
+
+        # Wide, emoji-capable, or braille, which a browser draws from
+        # a fallback font wider than a column.
+        def self.web_risk?(char)
+            Width.class_of(char) == :W || Target.emoji_risk?(char.ord) ||
+                char.ord.between?(0x2801, 0x28FF)
+        end
+
+        PATTERNS = {
+            light: "░", medium: "▒", dark: "▓", solid: "█",
+            hatch: "╱", backhatch: "╲", cross: "╳", grid: "┼",
+            stipple: "∴∵", sparse: "·", dotted: "∘",
+            dots: ".", colons: ":", hash: "#", at: "@"
+        }.freeze
+
+        # Fill then track, as ui.md's progress-bar styles.
+        METERS = {
+            arrow: "▸▹", chevron: "› ", classic: "= ", rectangle: "▮▯",
+            wave: "~_", blade: "▰▱", button: "⦿⦾", block: "█·",
+            box: "■□", circle: "●○", star: "★☆"
+        }.freeze
+
+        RULES = {
+            light: "─", heavy: "━", double: "═", dashed: "┄", ascii: "-"
+        }.freeze
+
+        # Light to dense, a blank first.
+        RAMPS = {
+            ramp: " .:-=+*#%@", blocks: " ░▒▓█",
+            long: " .'`^\",:;Il!i><~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZm" \
+                  "wqpdbkhao*#MW&8%B@$",
+            hatch: " ·∘╱╳"
+        }.freeze
+
+        # Arrow heads, right left up down (the ascii-art skill's rule):
+        # full-size for any target, though ▲ ▼ are ambiguous, two
+        # columns in a CJK terminal; small ones line up everywhere,
+        # ▴ ▾ standing in for ▲ ▼ there; ▶ ◀ may turn into wide emoji
+        # on the web.
+        HEADS = { full: "►◄▲▼", small: "▸◂▴▾", emoji: "▶◀" }.freeze
+
+        NOTES = {
+            meter: { blade: "patchy font coverage",
+                     button: "patchy font coverage",
+                     block: "house style" },
+            head: { full: "▴▾ under cjk", emoji: "+U+FE0E on web" }
+        }.freeze
+
+        def self.all
+            @all ||= [*borders, *table(:pattern, PATTERNS),
+                      *table(:meter, METERS), *table(:rule, RULES),
+                      *table(:ramp, RAMPS), *table(:head, HEADS)].freeze
+        end
+
+        def self.borders
+            Borders::STYLES.map do |name, set|
+                GlyphSet.new(kind: :border, name: name,
+                             glyphs: set.to_h.values.join, note: nil)
+            end
+        end
+
+        def self.table(kind, sets)
+            sets.map do |name, glyphs|
+                note = NOTES.dig(kind, name)
+                GlyphSet.new(kind: kind, name: name, glyphs: glyphs, note: note)
+            end
+        end
+
+        # The set of that kind and name, or ArgumentError naming both.
+        def self.fetch(kind, name)
+            key = Borders.name(name)
+            all.find { it.kind == kind && it.name == key } or
+                raise ArgumentError, "unknown #{kind}: #{name.inspect} " \
+                                     "(#{names(kind).join(", ")})"
+        end
+
+        def self.names(kind) = all.select { it.kind == kind }.map(&:name)
+    end
+end