tessella 0.3.0

data/lib/tessella/tree.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A hierarchy, drawn as a box-drawing tree (ported from the
+    # ascii-art skill's scripts/tree.rb -- DESIGN.md names it as a
+    # drawing module alongside Compose). `outline` is one node per
+    # line, depth given by leading-space indentation (the indent unit
+    # is inferred from the first indented line); an optional leading
+    # "- " or "* " bullet is stripped, and an optional "label  # note"
+    # annotation (two or more spaces, then #) is pulled off and
+    # aligned into one comment column across the whole tree. Several
+    # top-level lines form a forest; root: gathers them under one
+    # synthesized root instead.
+    #
+    # Bad input (a tab, an indent that is not a whole multiple of the
+    # inferred unit, a line more than one level deeper than its
+    # predecessor, an empty label, no node at all) raises
+    # ArgumentError naming the input line, as does an unknown style,
+    # a style other than the default under ascii: true, and -- unlike
+    # the script, which lints afterwards -- non-ASCII content under
+    # ascii: true, refused at draw time rather than caught by a later
+    # pass.
+    module Tree
+        Result = Data.define(:lines, :entries)
+
+        STYLES = {
+            light: { sib: "├── ", last: "└── ", pipe: "│   " },
+            heavy: { sib: "┣━━ ", last: "┗━━ ", pipe: "┃   " },
+            rounded: { sib: "├── ", last: "╰── ", pipe: "│   " },
+            ascii: { sib: "|-- ", last: "`-- ", pipe: "|   " }
+        }.freeze
+        BLANK = "    "
+
+        def self.bad!(lineno, msg)
+            raise ArgumentError, "line #{lineno}: #{msg}"
+        end
+
+        def self.glyphs(style, ascii)
+            name = (style || (ascii ? :ascii : :light)).to_sym
+            if ascii && name != :ascii
+                raise ArgumentError, "style #{name} conflicts with ascii: true"
+            end
+
+            STYLES.fetch(name) do
+                raise ArgumentError, "unknown style: #{name.inspect}"
+            end
+        end
+
+        def self.render(outline, style: nil, ascii: Target.ascii?, root: nil)
+            lines = Parser.parse(outline)
+            roots = Builder.forest(lines)
+            roots = [Builder.wrap(root, roots)] if root
+            g = glyphs(style, ascii)
+            entries = []
+            Renderer.walk(roots, nil, g, entries)
+            rendered = Renderer.align(entries)
+            check_ascii!(root, rendered, entries) if
+                ascii && !Target.text_free?
+            Result.new(rendered, entries)
+        end
+
+        def self.check_ascii!(root, rendered, entries)
+            if root && !root.ascii_only?
+                bad!(0, "--root is non-ASCII under ascii: true")
+            end
+            i = rendered.each_index.find { |idx| !rendered[idx].ascii_only? }
+            return unless i
+
+            bad!(entries[i][:line], "is non-ASCII under ascii: true")
+        end
+
+        # Mirrors tree.rb's own --max-width check (naming the source
+        # node's line, not the rendered line), not Block#check_width!,
+        # whose message and line numbering are generic.
+        def self.check_max_width!(result, max_width)
+            return result unless max_width
+
+            i = result.lines.each_index.find do |idx|
+                Width.of(result.lines[idx]) > max_width
+            end
+            return result unless i
+
+            w = Width.of(result.lines[i])
+            bad!(result.entries[i][:line],
+                 "is #{w} columns, over --max-width #{max_width}")
+        end
+    end
+
+    # Lines to nodes: depth from indentation, an optional bullet
+    # stripped, an optional "  # note" annotation split off.
+    module Tree
+        module Parser
+            def self.parse(outline)
+                lines = outline.split("\n", -1).each_with_index
+                               .map { |raw, i| parse_line(raw, i + 1) }
+                               .compact
+                Tree.bad!(0, "no nodes in the input") if lines.empty?
+                lines
+            end
+
+            def self.parse_line(raw, lineno)
+                return nil if raw.strip.empty?
+                if raw.include?("\t")
+                    Tree.bad!(lineno, "a tab in the indentation")
+                end
+
+                indent = raw[/\A */].size
+                rest = raw[indent..].sub(/\A[-*] /, "")
+                label, annotation = split_annotation(rest)
+                Tree.bad!(lineno, "an empty node label") if label.empty?
+                { indent: indent, label: label, annotation: annotation,
+                  line: lineno }
+            end
+
+            def self.split_annotation(rest)
+                label, _, note = rest.partition(/ {2,}#\s?/)
+                [label.rstrip, note.empty? ? nil : note.rstrip]
+            end
+        end
+    end
+
+    # Nodes to a forest: a stack of the open ancestors at each depth,
+    # one per indent level; root: wraps the forest under one node.
+    module Tree
+        module Builder
+            def self.forest(lines)
+                unit = nil
+                stack = []
+                roots = []
+                lines.each do |l|
+                    unit ||= l[:indent] if l[:indent].positive?
+                    insert(l, unit, stack, roots)
+                end
+                roots
+            end
+
+            def self.insert(line, unit, stack, roots)
+                depth = resolve_depth(line[:indent], unit, line[:line])
+                node = make_node(line)
+                attach(node, depth, stack, roots)
+                stack[depth] = node
+                stack.slice!((depth + 1)..)
+            end
+
+            def self.resolve_depth(indent, unit, lineno)
+                return 0 if indent.zero?
+
+                skewed = (indent % unit).nonzero?
+                if skewed
+                    Tree.bad!(lineno,
+                              "indentation is not a multiple of #{unit}")
+                end
+                indent / unit
+            end
+
+            def self.make_node(line)
+                { label: line[:label], annotation: line[:annotation],
+                  line: line[:line], children: [] }
+            end
+
+            def self.attach(node, depth, stack, roots)
+                prev = stack.size - 1
+                Tree.bad!(node[:line], "skips a level") if depth > prev + 1
+                return roots << node if depth.zero?
+
+                stack[depth - 1][:children] << node
+            end
+
+            def self.wrap(name, roots)
+                { label: name, annotation: nil, line: 0, children: roots }
+            end
+        end
+    end
+
+    # A forest to text: one line per node, its connector built from
+    # whether it is the last child at each ancestor level; notes
+    # aligned into one comment column across the whole render.
+    module Tree
+        module Renderer
+            def self.connector(prefix, last, g)
+                return "" if prefix.nil?
+
+                prefix + (last ? g[:last] : g[:sib])
+            end
+
+            def self.continuation(prefix, last, g)
+                return "" if prefix.nil?
+
+                prefix + (last ? Tree::BLANK : g[:pipe])
+            end
+
+            def self.walk(nodes, prefix, g, out)
+                nodes.each_with_index do |node, i|
+                    last = i == nodes.size - 1
+                    head = connector(prefix, last, g)
+                    out << { text: head + node[:label],
+                             annotation: node[:annotation],
+                             line: node[:line] }
+                    kids = node[:children]
+                    next if kids.empty?
+
+                    walk(kids, continuation(prefix, last, g), g, out)
+                end
+            end
+
+            def self.align(entries)
+                column = entries.map { Width.of(it[:text]) }.max + 2
+                entries.map do |e|
+                    next e[:text] if e[:annotation].nil?
+
+                    "#{Width.ljust(e[:text], column)}# #{e[:annotation]}"
+                end
+            end
+        end
+    end
+
+    def self.tree(outline, style: nil, ascii: Target.ascii?, root: nil)
+        result = Tree.render(outline, style: style, ascii: ascii, root: root)
+        Block.new(result.lines)
+    end
+end

data/lib/tessella/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tessella
+    VERSION = "0.3.0"
+end

data/lib/tessella/wave.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+module Tessella
+    # A timing diagram from WaveDrom-like signal text (DESIGN.md): one
+    # signal per line, "name: wave" in WaveDrom's alphabet (0 low, 1
+    # high, p positive clock, n negative clock, x unknown, z high
+    # impedance, = a bus value, . repeat the previous state), with an
+    # optional "| label label ..." naming the bus values in order and
+    # a lone "---" line drawing an empty separator row. Ported from
+    # the ascii-art skill's scripts/wave.rb; Tessella.wave is the
+    # entry point, at the bottom of this file.
+    module Wave
+        ALPHABET = ".01pnxz=".chars.freeze
+
+        # One input line -> a WaveSignal, :separator, or nil (blank).
+        WaveSignal = Struct.new(:name, :wave, :labels, :lineno)
+
+        # One rendered cell: a level, its column width, the bus label
+        # (if any), the state it follows, and whether its own first
+        # column is a boundary (edge/tick/marker) rather than fill.
+        Segment = Struct.new(:kind, :width, :label, :prev_kind, :boundary)
+
+        def self.build(text, period:, ascii:, ruler:)
+            check_period!(period)
+            diagram = Diagram.parse(text, period, ascii, ruler)
+            Block.new(diagram.rows)
+        end
+
+        def self.check_period!(period)
+            return if period.is_a?(Integer) && period >= 2
+
+            raise ArgumentError,
+                  "period must be an Integer >= 2: #{period.inspect}"
+        end
+    end
+
+    # One input line -> a WaveSignal, :separator, or nil (a blank
+    # line); every refusal names the line it is about.
+    module Wave
+        class LineParser
+            def self.parse(line, lineno)
+                text = line.strip
+                return nil if text.empty?
+                return :separator if text == "---"
+
+                new(text, lineno).signal
+            end
+
+            def initialize(text, lineno)
+                @text = text
+                @lineno = lineno
+            end
+
+            def signal
+                name, rest = split_name
+                wave, labels = split_wave(rest)
+                validate(wave)
+                Wave::WaveSignal.new(name, wave, labels, @lineno)
+            end
+
+            private
+
+            def split_name
+                idx = @text.index(":")
+                raise ArgumentError, "line #{@lineno}: missing ':'" unless idx
+
+                name = @text[0...idx].strip
+                if name.empty?
+                    raise ArgumentError, "line #{@lineno}: empty signal name"
+                end
+
+                [name, @text[(idx + 1)..].strip]
+            end
+
+            def split_wave(rest)
+                wave_part, _, label_part = rest.partition("|")
+                wave = wave_part.gsub(/\s+/, "")
+                if wave.empty?
+                    raise ArgumentError,
+                          "line #{@lineno}: empty wave"
+                end
+
+                [wave, label_part.strip.split]
+            end
+
+            def validate(wave)
+                bad = wave.chars.reject { Wave::ALPHABET.include?(it) }.uniq
+                return if bad.empty?
+
+                raise ArgumentError,
+                      "line #{@lineno}: unknown wave character " \
+                      "#{bad.join(",")}"
+            end
+        end
+    end
+
+    # Wave characters -> Segments, resolving "." continuation,
+    # splitting a clock char into its rise/fall halves, and merging a
+    # "=" with the "." that follow it into one labelled bus run.
+    module Wave
+        class SegmentBuilder
+            CHAR_KIND = { "0" => :low, "1" => :high, "x" => :unknown,
+                          "z" => :hiz }.freeze
+
+            def initialize(wave, labels, period)
+                @chars = wave.chars
+                @labels = labels.dup
+                @period = period
+                @prev = nil
+                @clock = nil
+            end
+
+            def segments
+                result = []
+                i = 0
+                i = step(result, i) while i < @chars.length
+                unless @labels.empty?
+                    raise ArgumentError,
+                          "too many labels for '='"
+                end
+
+                result
+            end
+
+            private
+
+            def step(result, i)
+                c = @chars[i]
+                return bus_run(result, i) if c == "="
+                return i + 1 if advance?(result, c)
+
+                raise ArgumentError, "unknown wave character #{c.inspect}"
+            end
+
+            def advance?(result, c)
+                case c
+                when "0", "1", "x", "z"
+                    result << flat(CHAR_KIND.fetch(c), @period)
+                    @clock = nil
+                when "." then result.concat(repeat)
+                when "p" then result.concat(pulse(:high, :low, :p))
+                when "n" then result.concat(pulse(:low, :high, :n))
+                else return false
+                end
+                true
+            end
+
+            def flat(kind, width)
+                seg = Wave::Segment.new(kind, width, nil, @prev, edge?(kind))
+                @prev = kind
+                seg
+            end
+
+            def edge?(kind)
+                return false if @prev.nil? || %i[unknown hiz].include?(kind)
+
+                kind != @prev
+            end
+
+            # "." repeats whatever the previous character did: another
+            # full cycle for a clock (its own rise and fall), a flat hold
+            # at the same level for anything else.
+            def repeat
+                raise ArgumentError, "'.' with no previous state" unless @prev
+                return pulse(:high, :low, :p) if @clock == :p
+                return pulse(:low, :high, :n) if @clock == :n
+
+                [Wave::Segment.new(@prev, @period, nil, @prev, false)]
+            end
+
+            def pulse(first, second, clock)
+                halves = [@period / 2, @period - (@period / 2)]
+                segs = [flat(first, halves[0]), flat(second, halves[1])]
+                @clock = clock
+                segs
+            end
+
+            def bus_run(result, i)
+                label = @labels.shift
+                raise ArgumentError, "not enough labels for '='" unless label
+                steps = 1
+                steps += 1 while @chars[i + steps] == "."
+                width = steps * @period
+                boundary = !@prev.nil?
+                check_fit(label, width - (boundary ? 1 : 0))
+                result << Wave::Segment.new(:bus, width, label, @prev, boundary)
+                @prev = :bus
+                i + steps
+            end
+
+            def check_fit(label, width)
+                return if Width.of(label) <= width
+
+                raise ArgumentError,
+                      "label #{label.inspect} does not fit in " \
+                      "#{width} columns"
+            end
+        end
+    end
+
+    # Segments -> the two printed rows (top: the high line; bottom:
+    # the low line, the bus baseline, and the name). One glyph table
+    # per mode.
+    module Wave
+        class RowRenderer
+            FILL = {
+                unicode: { low: "─", high: "─", unknown: "▒", hiz: "┄",
+                           bus: "─" },
+                ascii: { low: "_", high: "_", unknown: "x", hiz: "-", bus: "_" }
+            }.freeze
+
+            def initialize(ascii)
+                @ascii = ascii
+                @fill = ascii ? FILL[:ascii] : FILL[:unicode]
+            end
+
+            def render(segments)
+                pairs = segments.map { cell(it) }
+                [pairs.map(&:first).join, pairs.map(&:last).join]
+            end
+
+            private
+
+            def cell(seg)
+                lead = seg.boundary ? 1 : 0
+                top, bot = fill(seg, seg.width - lead)
+                return [top, bot] unless seg.boundary
+
+                mtop, mbot = marker(seg)
+                [mtop + top, mbot + bot]
+            end
+
+            def fill(seg, width)
+                case seg.kind
+                when :low  then [" " * width, @fill[:low] * width]
+                when :high then [@fill[:high] * width, " " * width]
+                when :unknown, :hiz
+                    band = @fill[seg.kind] * width
+                    [band, band]
+                when :bus then [" " * width, bus_label(seg.label, width)]
+                end
+            end
+
+            def bus_label(label, width)
+                gap = width - Width.of(label)
+                f = @fill[:bus]
+                (f * (gap / 2)) + label + (f * (gap - (gap / 2)))
+            end
+
+            def marker(seg)
+                return bus_marker if seg.kind == :bus || seg.prev_kind == :bus
+                return vertical_marker if
+                    %i[unknown hiz].include?(seg.prev_kind)
+
+                edge_marker(seg)
+            end
+
+            def bus_marker = @ascii ? [" ", "X"] : %w[╳ ╳]
+
+            def vertical_marker = @ascii ? [" ", "|"] : %w[│ │]
+
+            def edge_marker(seg)
+                return vertical_marker if @ascii
+
+                seg.kind == :high ? %w[┌ ┘] : %w[┐ └]
+            end
+        end
+    end
+
+    # The whole figure: every signal's two rows (never rstripped --
+    # Block does that), a blank line between any two consecutive
+    # entries (a "---" entry has no rows of its own, so it reads as
+    # one extra blank), and an optional ruler row at the end.
+    module Wave
+        class Diagram
+            def self.parse(text, period, ascii, ruler)
+                entries = text.each_line.with_index(1).filter_map do |line, n|
+                    Wave::LineParser.parse(line, n)
+                end
+                if entries.grep(Wave::WaveSignal).empty?
+                    raise ArgumentError, "no signal lines"
+                end
+
+                new(entries, period, ascii, ruler)
+            end
+
+            def initialize(entries, period, ascii, ruler)
+                @entries = entries
+                @period = period
+                @ascii = ascii
+                @ruler = ruler
+                Diagram.check_ascii!(entries) if ascii
+                widths = entries.grep(Wave::WaveSignal).map { Width.of(it.name) }
+                @name_width = widths.max || 0
+            end
+
+            def rows
+                @rows ||= build_rows
+            end
+
+            def self.check_ascii!(entries)
+                entries.grep(Wave::WaveSignal).each do |s|
+                    [s.name, *s.labels].each do |text|
+                        Check.ascii!(text, "line #{s.lineno}")
+                    end
+                end
+            end
+
+            private
+
+            def build_rows
+                rows = []
+                @entries.each_with_index do |e, i|
+                    rows << "" if i.positive?
+                    rows.concat(body(e))
+                end
+                rows.concat(ruler_rows) if @ruler
+                rows
+            end
+
+            def body(entry)
+                return [] if entry == :separator
+
+                top, bot = render_wave(entry)
+                [pad(nil) + top, pad(entry.name) + bot]
+            end
+
+            def render_wave(entry)
+                builder = Wave::SegmentBuilder.new(entry.wave, entry.labels,
+                                                   @period)
+                Wave::RowRenderer.new(@ascii).render(builder.segments)
+            rescue ArgumentError => e
+                raise ArgumentError, "line #{entry.lineno}: #{e.message}"
+            end
+
+            def ruler_rows
+                steps = @entries.grep(Wave::WaveSignal)
+                                .map { it.wave.length }.max || 0
+                line = (0...steps).map { it.to_s.ljust(@period) }.join
+                ["", pad(nil) + line]
+            end
+
+            def pad(name)
+                text = name ? Width.ljust(name, @name_width) : " " * @name_width
+                "#{text} "
+            end
+        end
+    end
+
+    def self.wave(text, period: 4, ascii: Target.ascii?, ruler: false)
+        Wave.build(text, period: period, ascii: ascii, ruler: ruler)
+    end
+end

data/lib/tessella/width.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Display width: the columns a terminal gives a string. East Asian
+    # Wide and Fullwidth glyphs take two, invisible ones (every
+    # nonspacing and enclosing mark, Mn and Me, in every script; the
+    # Hangul medial and final jamo; zero-width and format characters;
+    # variation selectors) none, everything else one -- ambiguous
+    # glyphs (box drawing, blocks) included, the Western terminal
+    # width. The two tables are generated from Unicode 15.1's
+    # UnicodeData.txt and EastAsianWidth.txt (a range WIDE holds is not
+    # repeated in INVISIBLE), shared with Tessella.lint (lint.rb); the
+    # markdown skill's check_md.rb keeps a copy that must stay
+    # identical to them.
+    module Width
+        WIDE = [
+            0x1100..0x115F, 0x231A..0x231B, 0x2329..0x232A, 0x23E9..0x23EC,
+            0x23F0..0x23F0, 0x23F3..0x23F3, 0x25FD..0x25FE, 0x2614..0x2615,
+            0x2648..0x2653, 0x267F..0x267F, 0x2693..0x2693, 0x26A1..0x26A1,
+            0x26AA..0x26AB, 0x26BD..0x26BE, 0x26C4..0x26C5, 0x26CE..0x26CE,
+            0x26D4..0x26D4, 0x26EA..0x26EA, 0x26F2..0x26F3, 0x26F5..0x26F5,
+            0x26FA..0x26FA, 0x26FD..0x26FD, 0x2705..0x2705, 0x270A..0x270B,
+            0x2728..0x2728, 0x274C..0x274C, 0x274E..0x274E, 0x2753..0x2755,
+            0x2757..0x2757, 0x2795..0x2797, 0x27B0..0x27B0, 0x27BF..0x27BF,
+            0x2B1B..0x2B1C, 0x2B50..0x2B50, 0x2B55..0x2B55, 0x2E80..0x2E99,
+            0x2E9B..0x2EF3, 0x2F00..0x2FD5, 0x2FF0..0x303E, 0x3041..0x3096,
+            0x3099..0x30FF, 0x3105..0x312F, 0x3131..0x318E, 0x3190..0x31E3,
+            0x31EF..0x321E, 0x3220..0x3247, 0x3250..0x4DBF, 0x4E00..0xA48C,
+            0xA490..0xA4C6, 0xA960..0xA97C, 0xAC00..0xD7A3, 0xF900..0xFAFF,
+            0xFE10..0xFE19, 0xFE30..0xFE52, 0xFE54..0xFE66, 0xFE68..0xFE6B,
+            0xFF01..0xFF60, 0xFFE0..0xFFE6, 0x16FE0..0x16FE4, 0x16FF0..0x16FF1,
+            0x17000..0x187F7, 0x18800..0x18CD5, 0x18D00..0x18D08,
+            0x1AFF0..0x1AFF3, 0x1AFF5..0x1AFFB, 0x1AFFD..0x1AFFE,
+            0x1B000..0x1B122, 0x1B132..0x1B132, 0x1B150..0x1B152,
+            0x1B155..0x1B155, 0x1B164..0x1B167, 0x1B170..0x1B2FB,
+            0x1F004..0x1F004, 0x1F0CF..0x1F0CF, 0x1F18E..0x1F18E,
+            0x1F191..0x1F19A, 0x1F200..0x1F202, 0x1F210..0x1F23B,
+            0x1F240..0x1F248, 0x1F250..0x1F251, 0x1F260..0x1F265,
+            0x1F300..0x1F320, 0x1F32D..0x1F335, 0x1F337..0x1F37C,
+            0x1F37E..0x1F393, 0x1F3A0..0x1F3CA, 0x1F3CF..0x1F3D3,
+            0x1F3E0..0x1F3F0, 0x1F3F4..0x1F3F4, 0x1F3F8..0x1F43E,
+            0x1F440..0x1F440, 0x1F442..0x1F4FC, 0x1F4FF..0x1F53D,
+            0x1F54B..0x1F54E, 0x1F550..0x1F567, 0x1F57A..0x1F57A,
+            0x1F595..0x1F596, 0x1F5A4..0x1F5A4, 0x1F5FB..0x1F64F,
+            0x1F680..0x1F6C5, 0x1F6CC..0x1F6CC, 0x1F6D0..0x1F6D2,
+            0x1F6D5..0x1F6D7, 0x1F6DC..0x1F6DF, 0x1F6EB..0x1F6EC,
+            0x1F6F4..0x1F6FC, 0x1F7E0..0x1F7EB, 0x1F7F0..0x1F7F0,
+            0x1F90C..0x1F93A, 0x1F93C..0x1F945, 0x1F947..0x1F9FF,
+            0x1FA70..0x1FA7C, 0x1FA80..0x1FA88, 0x1FA90..0x1FABD,
+            0x1FABF..0x1FAC5, 0x1FACE..0x1FADB, 0x1FAE0..0x1FAE8,
+            0x1FAF0..0x1FAF8, 0x20000..0x2FFFD, 0x30000..0x3FFFD
+        ].freeze
+
+        # An ANSI colour sequence (a chart drawn with color: true) takes
+        # no column.
+        ANSI = /\e\[[0-9;]*m/
+
+        # What makes a cluster one emoji: a zero-width joiner, or a
+        # skin-tone modifier.
+        EMOJI_JOIN = /[\u200D\u{1F3FB}-\u{1F3FF}]/
+
+        # Summed over grapheme clusters, so an emoji sequence counts
+        # once (Width.cluster).
+        def self.of(text)
+            plain = text.to_s.gsub(ANSI, "")
+            return plain.length if plain.ascii_only?
+
+            plain.each_grapheme_cluster.sum { cluster(it) }
+        end
+
+        # One grapheme cluster's columns: its characters' sum, except an
+        # emoji sequence -- joined by ZWJ (👨‍👩‍👧) or skin-toned (👍🏽)
+        # -- which terminals draw as the one wide glyph it is: 2.
+        def self.cluster(text)
+            widths = text.each_char.map { char(it.ord) }
+            return 2 if widths.include?(2) && text.match?(EMOJI_JOIN)
+
+            widths.sum
+        end
+
+        def self.pad(count) = " " * [count, 0].max
+
+        # glyph repeated to fill cols columns: cols / its width copies,
+        # so a two-column box glyph (an ambiguous one under :cjk) runs
+        # half as many times.
+        def self.run(glyph, cols) = glyph * (cols / [of(glyph), 1].max)
+
+        # cols rounded up to a whole number of units: a frame's or a
+        # column's inner width, so its border glyphs fill it exactly.
+        def self.round_up(cols, unit) = ((cols + unit - 1) / unit) * unit
+        def self.ljust(text, cols) = text + pad(cols - of(text))
+        def self.rjust(text, cols) = pad(cols - of(text)) + text
+
+        def self.center(text, cols)
+            gap = cols - of(text)
+            pad(gap / 2) + text + pad(gap - (gap / 2))
+        end
+
+        # A character's columns under the current target (Target):
+        # an ambiguous glyph takes two under :cjk.
+        def self.char(code)
+            width = base(code)
+            return width unless width == 1 && code > 0x7F && Target.cjk?
+
+            ambiguous?(code) ? 2 : 1
+        end
+
+        # A character's columns in a Western terminal, whatever the
+        # target: what its width class is read from.
+        def self.base(code)
+            return 1 if code < 0x300
+            return 2 if in?(WIDE, code)
+
+            in?(INVISIBLE, code) ? 0 : 1
+        end
+
+        # Whether code falls in one of a table's sorted ranges.
+        def self.in?(table, code)
+            table.bsearch { it.end >= code }&.cover?(code) || false
+        end
+    end
+end