tessella 0.3.0

data/lib/tessella/cli/wave.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella wave` (DESIGN.md, "Command line"): draws one timing
+    # diagram from a file or stdin, ported from the ascii-art skill's
+    # scripts/wave.rb (minus its --no-lint: the lint pass stays in the
+    # skill). Exit 0 drawn, 1 bad input (a bad signal line, an unknown
+    # wave character, missing or leftover labels, a label too wide,
+    # output past --max-width), 2 usage (a bad option, too many file
+    # arguments, a file that cannot be opened).
+    class WaveCLI
+        class UsageError < StandardError; end
+        class DataError < StandardError; end
+
+        # Raised by --help to short-circuit parsing with the text and
+        # status already decided.
+        class Halt < StandardError
+            attr_reader :status, :text
+
+            def initialize(status, text)
+                @status = status
+                @text = text
+                super(text)
+            end
+        end
+
+        BANNER = "Usage: tessella wave [options] [file]  " \
+                 "(stdin if no file)\n"
+
+        def self.run(argv, stdin:, stdout:, stderr:)
+            draw(argv, stdin, stdout)
+        rescue Halt => e
+            CLI.halt(e, stdout, stderr)
+        rescue OptionParser::ParseError, UsageError => e
+            fail_with(stderr, e.message, 2)
+        rescue DataError => e
+            fail_with(stderr, e.message, 1)
+        end
+
+        def self.draw(argv, stdin, stdout)
+            opts, path = Options.parse(argv.dup)
+            block = build(opts, CLI.read_text(path, stdin, DataError))
+            Overflow.check!(block, opts[:max_width]) if opts[:max_width]
+            stdout.print(block.to_s)
+            0
+        end
+
+        def self.build(opts, text)
+            Tessella.wave(text, period: opts[:period], ascii: opts[:ascii],
+                                ruler: opts[:ruler])
+        rescue ArgumentError => e
+            raise DataError, e.message
+        end
+
+        def self.fail_with(stderr, message, status)
+            stderr.puts("tessella wave: #{message}")
+            status
+        end
+    end
+
+    # Parses argv into opts (:period, :ascii, :max_width, :ruler) plus
+    # the one file argument, or nil for stdin. Raises Halt for --help,
+    # or lets OptionParser::ParseError escape for a bad flag, missing
+    # argument, or disallowed value.
+    class WaveCLI
+        class Options
+            def self.parse(argv)
+                new.parse(argv)
+            end
+
+            def initialize
+                @opts = { period: 4, ascii: Target.ascii?, ruler: false }
+                @parser = OptionParser.new
+                @parser.banner = WaveCLI::BANNER
+                build
+            end
+
+            def parse(argv)
+                @parser.parse!(argv)
+                raise WaveCLI::UsageError, "too many arguments" if argv.size > 1
+
+                [@opts, argv.first]
+            end
+
+            private
+
+            def build
+                add_period
+                add_ascii
+                add_max_width
+                add_ruler
+                add_help
+            end
+
+            def add_period
+                @parser.on("--period N", Integer,
+                           "columns per time step (default 4)") do |n|
+                    raise WaveCLI::UsageError, "--period must be >= 2" if
+                        n < 2
+                    @opts[:period] = n
+                end
+            end
+
+            def add_ascii
+                @parser.on("--[no-]ascii", "pure ASCII output") do |v|
+                    @opts[:ascii] = v
+                end
+            end
+
+            def add_max_width
+                @parser.on("--max-width N", Integer,
+                           "error if output exceeds N columns") do |n|
+                    @opts[:max_width] = n
+                end
+            end
+
+            def add_ruler
+                @parser.on("--ruler", "add a time-step index row") do
+                    @opts[:ruler] = true
+                end
+            end
+
+            def add_help
+                @parser.on("--help", "print this help") do
+                    raise WaveCLI::Halt.new(0, @parser.to_s)
+                end
+            end
+        end
+    end
+
+    # --max-width, after the diagram is drawn: the first line over it
+    # refuses the whole figure, naming the line and its width, exactly
+    # as wave.rb's own check does.
+    class WaveCLI
+        module Overflow
+            def self.check!(block, max)
+                block.lines.each_with_index do |line, i|
+                    w = Width.of(line.rstrip)
+                    next if w <= max
+
+                    raise WaveCLI::DataError,
+                          "line #{i + 1}: #{w} columns exceeds " \
+                          "--max-width #{max}"
+                end
+            end
+        end
+    end
+end

data/lib/tessella/cli.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# The tessella command line, on top of the library: `require
+# "tessella/cli"` for Tessella::CLI and the per-command classes
+# (ChartCLI, ComposeCLI, ...); `require "tessella"` alone loads none
+# of them, nor optparse. As lib/tessella.rb does for the library,
+# this file is the only place the command line's files are required,
+# in this order, and tools/bundle.rb follows it after the library's.
+
+require "optparse"
+
+require_relative "../tessella"
+
+require_relative "cli/iso_time"
+require_relative "cli/chart_help"
+require_relative "cli/chart"
+require_relative "cli/chart_heatmap"
+require_relative "cli/chart_candle"
+require_relative "cli/chart_pie"
+require_relative "cli/compose"
+require_relative "cli/compose_options"
+require_relative "cli/tree"
+require_relative "cli/table"
+require_relative "cli/bitfield"
+require_relative "cli/wave"
+require_relative "cli/seq"
+require_relative "cli/image"
+require_relative "cli/lint"
+require_relative "cli/lint_options"
+require_relative "cli/glyphs"
+require_relative "cli/meter"
+require_relative "cli/rule"
+require_relative "cli/text"
+require_relative "cli/sparkline"
+require_relative "cli/input"
+require_relative "cli/main"

data/lib/tessella/color.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Colours to ANSI SGR, and nothing else (DESIGN.md, "Frame and
+    # Color"). Color.wrap is the only way a cell or label becomes
+    # coloured text; every other part treats colour as a value, never
+    # an escape code. A colour is one of the eight basic names, a
+    # 256-colour index (0..255), or a truecolor "#rrggbb".
+    module Color
+        NAMES = %i[red green yellow blue magenta cyan white].freeze
+
+        CODES = {
+            red: 31, green: 32, yellow: 33, blue: 34,
+            magenta: 35, cyan: 36, white: 37
+        }.freeze
+
+        HEX = /\A#\h{6}\z/
+
+        RESET = "\e[0m"
+
+        # name nil => text as is, never an escape. [fg, bg] sets the
+        # background too: a cell split between two colours, the glyph's
+        # ink one and the rest of the cell the other.
+        def self.wrap(text, name)
+            return text if name.nil?
+
+            codes = if name.is_a?(Array)
+                        [code(name[0]), background(name[1])]
+                    else
+                        [code(name)]
+                    end
+            "\e[#{codes.join(";")}m#{text}#{RESET}"
+        end
+
+        # The background code for a colour: 4x for 3x, 48 for 38.
+        def self.background(color) = code(color).to_s.sub(/\A3/, "4")
+
+        def self.code(color)
+            case color
+            when Integer then "38;5;#{color}" if valid?(color)
+            when HEX then "38;2;#{rgb(color).join(";")}"
+            else CODES[color.to_s.to_sym]
+            end || (raise ArgumentError, "unknown colour: #{color}")
+        end
+
+        def self.valid?(color)
+            return color.between?(0, 255) if color.is_a?(Integer)
+            return true if color.is_a?(String) && color.match?(HEX)
+
+            CODES.key?(color.to_s.to_sym)
+        end
+
+        # A colour from a command-line word: a name, an index, a #hex.
+        def self.parse(word)
+            return word.to_i if word.match?(/\A\d+\z/)
+
+            word.start_with?("#") ? word.downcase : word.to_sym
+        end
+
+        def self.rgb(hex) = hex[1..].scan(/../).map { it.to_i(16) }
+    end
+
+    # A gradient: colours (stops) to one colour per row of a figure,
+    # row 0 the bottom. Truecolor stops blend smoothly, the first stop
+    # on the bottom row and the last on the top one; any other set is
+    # split into equal bands, the first at the bottom.
+    module Color
+        module Gradient
+            def self.check!(stops)
+                return if stops.is_a?(Array) && !stops.empty? &&
+                          stops.all? { Color.valid?(it) }
+
+                raise ArgumentError, "gradient must be colours (names " \
+                                     "#{Color::NAMES.join(", ")}, 0..255 " \
+                                     "or #rrggbb): #{stops.inspect}"
+            end
+
+            # The colour of row (0 the bottom) of rows.
+            def self.at(stops, row, rows)
+                return band(stops, row.fdiv(rows)) unless smooth?(stops)
+
+                blend(stops, rows > 1 ? row.fdiv(rows - 1) : 0.0)
+            end
+
+            def self.smooth?(stops)
+                stops.size > 1 && stops.all?(String)
+            end
+
+            def self.band(stops, share)
+                stops[[(share * stops.size).floor, stops.size - 1].min]
+            end
+
+            # The colour share (0..1) of the way through the stops.
+            def self.blend(stops, share)
+                pos = share.clamp(0.0, 1.0) * (stops.size - 1)
+                i = [pos.floor, stops.size - 2].min
+                mix(Color.rgb(stops[i]), Color.rgb(stops[i + 1]), pos - i)
+            end
+
+            def self.mix(from, to, t)
+                rgb = from.zip(to).map { |a, b| (a + ((b - a) * t)).round }
+                "##{rgb.map { format("%<v>02x", v: it) }.join}"
+            end
+        end
+    end
+end

data/lib/tessella/compose.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Composition (DESIGN.md, "Blocks and composition"): a frame around
+    # a block, blocks side by side or stacked, a prefix on every line, a
+    # caption. Each takes figures (Block.from) and returns a Block,
+    # measuring by display width, so a CJK table and a braille chart
+    # line up. A block's own lines are never rewritten, only padded on
+    # the right -- except stack's center:, which shifts a narrower
+    # block as a whole. Under ascii: true the glyphs added are ASCII and
+    # a non-ASCII block or text is refused.
+    module Compose
+        ALIGNS = %i[top middle bottom].freeze
+
+        def self.blocks(figures, ascii)
+            figures.each_with_index.map do |figure, i|
+                block = Block.from(figure)
+                if ascii && !block.ascii? && !Target.text_free?
+                    raise ArgumentError,
+                          "block #{i + 1} is non-ASCII under ascii: true"
+                end
+                block
+            end
+        end
+
+        # Text drawn into a figure: one line, and ASCII under ascii:
+        # true -- but under :cjk, where ascii: only means the structure.
+        def self.text!(name, text, ascii)
+            if text.to_s.include?("\n")
+                raise ArgumentError, "#{name} must be one line: #{text.inspect}"
+            end
+            return text unless ascii && !text.to_s.ascii_only? &&
+                               !Target.text_free?
+
+            raise ArgumentError, "#{name} is non-ASCII under ascii: true"
+        end
+
+        # A glyph of the structure (a rule, a shadow, a pattern): ASCII
+        # under ascii: true, whatever the target.
+        def self.structure!(name, glyph, ascii)
+            return glyph unless ascii && !glyph.to_s.ascii_only?
+
+            raise ArgumentError, "#{name} is non-ASCII under ascii: true"
+        end
+
+        def self.count!(name, value)
+            return value if value.is_a?(Integer) && !value.negative?
+
+            raise ArgumentError, "#{name} must be an Integer >= 0: " \
+                                 "#{value.inspect}"
+        end
+
+        def self.align!(align)
+            return align.to_sym if ALIGNS.include?(align&.to_sym)
+
+            raise ArgumentError, "unknown align: #{align.inspect}"
+        end
+    end
+
+    # frame: a box around one block, title centred in the top edge;
+    # pad: is horizontal only, the frame hugs its content vertically.
+    # Its inner width is a whole number of border glyphs, so under
+    # target :cjk, where a Unicode box glyph takes two columns, the
+    # frame still closes.
+    module Compose
+        # fill: a pattern for the background the frame adds, halo: as
+        # Compose.fill's (compose_fill.rb).
+        # rubocop:disable-next Metrics/ParameterLists
+        def self.frame(figure, title: nil, style: nil, pad: 1,
+                       ascii: Target.ascii?, fill: nil, halo: true)
+            block, = blocks([figure], ascii)
+            text!("title", title, ascii)
+            g = Borders.fetch(style, ascii: ascii)
+            field = frame_field(block, title, count!("pad", pad), g.h)
+            framed = Block.new([frame_top(g, title, field),
+                                *frame_rows(block, g, pad, field),
+                                g.bl + Width.run(g.h, field) + g.br])
+            fill ? fill_frame(framed, fill, ascii, halo) : framed
+        end
+
+        # The width inside the frame: the block and its pads, or room
+        # for the title and a run of border on each side, in whole h.
+        def self.frame_field(block, title, pad, h)
+            least = [block.width + (2 * pad),
+                     title ? Width.of(title) + 4 : 0].max
+            Width.round_up(least, Width.of(h))
+        end
+
+        def self.frame_rows(block, g, pad, field)
+            inner = field - (2 * pad)
+            margin = " " * pad
+            block.lines.map do |l|
+                g.v + margin + Width.ljust(l, inner) + margin + g.v
+            end
+        end
+
+        def self.frame_top(g, title, field)
+            return g.tl + Width.run(g.h, field) + g.tr unless title
+
+            g.tl + titled(g.h, deco(title, field, Width.of(g.h)), field) +
+                g.tr
+        end
+
+        # " title ", a blank more when the border around it would
+        # otherwise end half a glyph short.
+        def self.deco(title, field, unit)
+            deco = " #{title} "
+            deco += " " until ((field - Width.of(deco)) % unit).zero?
+            deco
+        end
+
+        # deco centred in a run of h field columns long, the odd one
+        # right; h whole, so under :cjk a two-column one splits evenly.
+        def self.titled(h, deco, field)
+            rest = field - Width.of(deco)
+            unit = Width.of(h)
+            left = (rest / unit / 2) * unit
+            Width.run(h, left) + deco + Width.run(h, rest - left)
+        end
+    end
+
+    # beside: blocks side by side, each padded to its own width, the
+    # shorter ones filled vertically by align:.
+    module Compose
+        def self.beside(*figures, gap: 1, align: :top, ascii: Target.ascii?)
+            raise ArgumentError, "beside takes two figures or more" if
+                figures.size < 2
+
+            cols = columns(blocks(figures, ascii), align!(align))
+            sep = " " * count!("gap", gap)
+            Block.new((0...cols.first.size).map do |i|
+                cols.map { it[i] }.join(sep)
+            end)
+        end
+
+        def self.columns(blocks, align)
+            height = blocks.map(&:height).max
+            blocks.map do |b|
+                w = b.width
+                vertical(b.lines.map { Width.ljust(it, w) }, height, align, w)
+            end
+        end
+
+        def self.vertical(lines, height, align, width)
+            extra = height - lines.size
+            top = { top: 0, middle: extra / 2, bottom: extra }.fetch(align)
+            blank = " " * width
+            ([blank] * top) + lines + ([blank] * (extra - top))
+        end
+    end
+
+    # stack: blocks one under another; rule: draws one separator line
+    # as wide as the widest block, gap: blank rows around it (or between
+    # blocks without one); center: centres a narrower block as a whole.
+    module Compose
+        def self.stack(*figures, gap: 0, rule: nil, center: false,
+                       ascii: Target.ascii?)
+            raise ArgumentError, "stack takes two figures or more" if
+                figures.size < 2
+
+            list = blocks(figures, ascii)
+            width = list.map(&:width).max
+            list = list.map { centred(it, width) } if center
+            Block.new(joined(list, separator(gap, rule!(rule, ascii), width)))
+        end
+
+        def self.rule!(rule, ascii)
+            return nil if rule.nil?
+            unless rule.length == 1
+                raise ArgumentError,
+                      "rule must be one character: #{rule.inspect}"
+            end
+
+            structure!("rule", rule, ascii)
+        end
+
+        def self.centred(block, width)
+            own = block.width
+            left = (width - own) / 2
+            margin = [" " * left, " " * (width - own - left)]
+            Block.new(block.lines.map do |l|
+                margin[0] + Width.ljust(l, own) + margin[1]
+            end)
+        end
+
+        # gap blank rows between blocks, or gap on each side of a rule.
+        def self.separator(gap, rule, width)
+            rows = [""] * count!("gap", gap)
+            rule ? rows + [Width.run(rule, width)] + rows : rows
+        end
+
+        def self.joined(blocks, separator)
+            blocks.each_with_index.flat_map do |b, i|
+                i.zero? ? b.lines : separator + b.lines
+            end
+        end
+    end
+
+    # indent: prefix: on every line, a blank line taking the prefix
+    # without its trailing blank -- or, with suffix:, every row padded
+    # to the block's width and closed by it; caption: one centred line of text:,
+    # above: or below the block, a blank line between.
+    module Compose
+        def self.indent(figure, prefix:, suffix: nil, ascii: Target.ascii?)
+            block, = blocks([figure], ascii)
+            text!("prefix", prefix, ascii)
+            return suffixed(block, prefix, suffix!(suffix, ascii)) if suffix
+
+            Block.new(block.lines.map do |l|
+                l.empty? ? prefix.rstrip : prefix + l
+            end)
+        end
+
+        # Every row padded to the block's width, so the suffix closes
+        # them all at one column; a blank row carries it too.
+        def self.suffixed(block, prefix, suffix)
+            Block.new(block.lines.map do |l|
+                prefix + Width.ljust(l, block.width) + suffix
+            end)
+        end
+
+        # The suffix ends every row, so a trailing blank in it is
+        # refused rather than stripped.
+        def self.suffix!(suffix, ascii)
+            text!("suffix", suffix, ascii)
+            return suffix unless suffix.to_s.match?(/\s\z/)
+
+            raise ArgumentError, "suffix ends in a blank: #{suffix.inspect}"
+        end
+
+        def self.caption(figure, text:, above: false, ascii: Target.ascii?)
+            block, = blocks([figure], ascii)
+            cap = Width.center(text!("text", text, ascii), block.width)
+            Block.new(above ? [cap, "", *block.lines] : [*block.lines, "", cap])
+        end
+    end
+
+    def self.frame(...) = Compose.frame(...)
+    def self.beside(...) = Compose.beside(...)
+    def self.stack(...) = Compose.stack(...)
+    def self.indent(...) = Compose.indent(...)
+    def self.caption(...) = Compose.caption(...)
+end