tessella 0.3.0

data/lib/tessella/chart.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Marked series (add's mark:): one glyph in the cell of each point,
+    # in place of the kind's own drawing. Kept apart from Chart so
+    # Chart's own class body stays under budget.
+    module Marks
+        private
+
+        def check_mark!(mark)
+            return if mark.nil?
+            unless mark.is_a?(String) && mark.length == 1
+                raise ArgumentError,
+                      "mark must be one character: #{mark.inspect}"
+            end
+            return unless @ascii && !mark.ascii_only?
+
+            raise ArgumentError,
+                  "mark must be ASCII under ascii: true: #{mark.inspect}"
+        end
+
+        def draw_or_mark(canvas, series)
+            return draw_series(canvas, series) unless series.mark
+
+            series.x.zip(series.y).each do |x, y|
+                canvas.mark(x, y, series.mark, color: series.color)
+            end
+        end
+
+        # A marked series shows its glyph before its name.
+        def legend(series) = [series.mark, series.name].compact.join(" ")
+    end
+
+    # What a chart refuses before it draws (DESIGN.md, "Chart and
+    # kinds"): unknown options, a width or height that is not a
+    # positive Integer, and a series whose x and y differ in length or
+    # hold a value an axis cannot place. Kept apart from Chart so
+    # Chart's own class body stays under budget.
+    module ChartChecks
+        private
+
+        def check_options!(opts)
+            unknown = opts.keys - self.class::OPTIONS
+            return check_sizes!(opts) if unknown.empty?
+
+            raise ArgumentError,
+                  "unknown option: #{unknown.map(&:inspect).join(", ")}"
+        end
+
+        def check_sizes!(opts)
+            %i[width height].each do |key|
+                Check.positive_integer!(opts[key], key.to_s) if opts.key?(key)
+            end
+        end
+
+        # x (nil for 1..n) and y as stored: each through its scale,
+        # both finite, and the same length.
+        def series_values(x, y)
+            ys = Check.finite!(Array(y), "y")
+            xs = Array(x || (1..ys.length))
+            Check.same_size!(xs, ys, %w[x y])
+            [Check.finite!(xs.map(&@xscale), scaled_name(:x)),
+             Check.finite!(ys.map(&@yscale), scaled_name(:y))]
+        end
+
+        def scaled_name(axis)
+            scale = @opts[:"#{axis}scale"]
+            scale ? "#{axis} under #{axis}scale #{scale}" : axis.to_s
+        end
+    end
+
+    # Shared machinery behind every chart kind (DESIGN.md, "Chart and
+    # kinds"): option handling and defaults, series bookkeeping, colour
+    # cycling over Color::NAMES, canvas and frame assembly, and
+    # to_s / render. A subclass implements draw_series(canvas, series)
+    # and may override default_canvas_type, canvas_type, default_border,
+    # draw_grid? or add itself (Stairs reshapes its points there).
+    class Chart
+        include ChartChecks
+        include Marks
+
+        DEFAULT_WIDTH = 40
+        DEFAULT_HEIGHT = 15
+
+        # Canvases a chart reaches only through another's name.
+        WIDE = %i[half_wide eighths_wide].freeze
+        OPTIONS = %i[title xlabel ylabel width height xlim ylim canvas
+                     ascii color border xscale].freeze
+
+        Series = Data.define(:x, :y, :name, :color, :mark)
+
+        def initialize(**opts)
+            check_options!(opts)
+            @opts = opts
+            @ascii = opts.fetch(:ascii) { Target.ascii? }
+            @color_on = opts.fetch(:color, false)
+            @border = opts[:border] || default_border
+            @xscale = Stats.transform(opts[:xscale])
+            @yscale = Stats.transform(opts[:yscale])
+            @series = []
+            @next_color = 0
+        end
+
+        # mark: a one-character glyph drawn in the cell of each point,
+        # instead of the kind's own drawing of the series.
+        def add(*args, name: nil, color: nil, mark: nil)
+            check_mark!(mark)
+            x, y = args.length == 1 ? [nil, *args] : args
+            xs, ys = series_values(x, y)
+            @series << Series.new(x: xs, y: ys, name: name,
+                                  color: color || auto_color, mark: mark)
+            self
+        end
+
+        def to_s
+            text = frame.to_s
+            return text unless @ascii
+
+            text.each_line.with_index(1) do |line, n|
+                Check.ascii!(line.chomp, "chart line #{n}")
+            end
+            text
+        end
+
+        def render(io = $stdout) = io.print(to_s)
+
+        private
+
+        def default_border = :box
+        def draw_grid? = true
+        def default_canvas_type = @ascii ? :ascii : Target.canvas
+
+        def auto_color
+            name = Color::NAMES[@next_color % Color::NAMES.size]
+            @next_color += 1
+            name
+        end
+
+        def canvas_type
+            type = @opts[:canvas] || default_canvas_type
+            return eighths_type if type == :eighths
+            return type if Canvas.types.key?(type) && !WIDE.include?(type)
+
+            raise ArgumentError, "unknown canvas: #{type.inspect}"
+        end
+
+        # The eighths canvas only fills (Canvas::Eighths): an area, up
+        # its columns or, sideways, along its rows -- not a threshold's
+        # dashes, which would read as bars.
+        def eighths_type
+            raise ArgumentError, "canvas: :eighths needs area: true" unless
+                fills?
+            raise ArgumentError, "canvas: :eighths takes no threshold:" if
+                @opts[:threshold]
+
+            @sideways ? :eighths_wide : :eighths
+        end
+
+        def fills? = false
+
+        def width  = @opts.fetch(:width, DEFAULT_WIDTH)
+        def height = @opts.fetch(:height, DEFAULT_HEIGHT)
+        def xlim = Axis.limits(@series.flat_map(&:x), @opts[:xlim])
+        def ylim = Axis.limits(@series.flat_map(&:y), @opts[:ylim])
+
+        def canvas_extra
+            canvas_type == :density ? { ascii: @ascii } : {}
+        end
+
+        def build_canvas(xl, yl)
+            opts = { width: width, height: height, xlim: xl, ylim: yl,
+                     **canvas_extra }
+            canvas = Canvas.build(canvas_type, **opts)
+            draw_axes(canvas, xl, yl)
+            @series.each { draw_or_mark(canvas, it) }
+            canvas
+        end
+
+        def draw_axes(canvas, xl, yl)
+            return unless draw_grid?
+
+            canvas.line(xl.first, 0, xl.last, 0) if
+                yl.first.negative? && yl.last.positive?
+            canvas.line(0, yl.first, 0, yl.last) if
+                xl.first.negative? && xl.last.positive?
+        end
+
+        def frame
+            xl = xlim
+            yl = ylim
+            Frame.new(**frame_options(build_canvas(xl, yl), xl, yl))
+        end
+
+        def frame_options(canvas, xl, yl)
+            { body: canvas.rows, border: @border, ascii: @ascii,
+              color: @color_on, title: @opts[:title],
+              xlabel: @opts[:xlabel], ylabel: @opts[:ylabel],
+              left: left_labels(yl), right: right_labels,
+              bottom: [Axis.tick(xl.first), Axis.tick(xl.last)] }
+        end
+
+        def left_labels(yl)
+            { 0 => Axis.tick(yl.last), (height - 1) => Axis.tick(yl.first) }
+        end
+
+        def right_labels
+            named = @series.reject { |s| s.name.to_s.empty? }
+            named.each_with_index.to_h { |s, i| [i, legend(s)] }
+        end
+    end
+end

data/lib/tessella/check.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Tessella
+    # The argument checks every kind shares: each raises ArgumentError
+    # naming what it refused, before anything is drawn.
+    module Check
+        def self.positive_integer!(value, name)
+            return value if value.is_a?(Integer) && value.positive?
+
+            raise ArgumentError,
+                  "#{name} must be a positive Integer: #{value.inspect}"
+        end
+
+        def self.positive!(value, name)
+            return value if value.is_a?(Numeric) && value.positive?
+
+            raise ArgumentError, "#{name} must be positive: #{value.inspect}"
+        end
+
+        # Only a finite number can be placed on an axis: nil, a String,
+        # NaN or +-Infinity is refused, and what produced it (data, or
+        # an xscale over a value <= 0) is named.
+        def self.finite!(values, name)
+            i = values.index { !finite_number?(it) }
+            return values unless i
+
+            raise ValueError,
+                  "#{name} must be a finite number: #{values[i].inspect}"
+        end
+
+        def self.finite_number?(value)
+            value.is_a?(Numeric) && (!value.is_a?(Float) || value.finite?)
+        end
+
+        # Under ascii: true every text drawn into a figure is ASCII
+        # too: one that is not is refused, naming where it came from.
+        def self.ascii!(text, where)
+            return text if text.nil? || text.to_s.ascii_only? ||
+                           Target.text_free?
+
+            raise ArgumentError, "#{where} is non-ASCII under ascii: " \
+                                 "true: #{text.to_s.inspect}"
+        end
+
+        def self.same_size!(a, b, names)
+            return if a.size == b.size
+
+            raise ArgumentError, "#{names[0]} and #{names[1]} differ in " \
+                                 "length: #{a.size} and #{b.size}"
+        end
+    end
+end

data/lib/tessella/cli/bitfield.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella bitfield` (ported byte for byte from the tessella
+    # skill's scripts/bitfield.rb, minus its --no-lint: the lint pass
+    # stays in the skill). Exit 0 drawn, 1 bad input (a missing file, a
+    # bad line, a name too wide for its cell, output past --max-width),
+    # 2 usage.
+    class BitfieldCLI
+        class UsageError < StandardError; end
+        class DataError < StandardError; end
+
+        USAGE = <<~TEXT
+            Usage: tessella bitfield [options] [file]  (stdin if none)
+                --word N          bits per row: 8, 16, 32 (default), 64
+                --octets          byte-oriented: no bit ruler, a tick
+                                  per octet
+                --no-ruler        drop the two-row bit ruler
+                --abbrev          truncate a name too wide for its cell
+                --ascii           accepted; this command always draws
+                                  ASCII
+                --max-width N     error if a line exceeds N columns
+        TEXT
+
+        def self.run(argv, stdin:, stdout:, stderr:)
+            return help(stdout) if %w[--help -h].include?(argv.first)
+
+            stdout.print(draw(argv.dup, stdin))
+            0
+        rescue UsageError, OptionParser::ParseError => e
+            fail_with(stderr, e.message, 2)
+        rescue DataError => e
+            fail_with(stderr, e.message, 1)
+        end
+
+        def self.help(stdout)
+            stdout.print(USAGE)
+            0
+        end
+
+        # No usage dump after the message (unlike compose's CLI): the
+        # parity gate requires bitfield's stderr to match the script's
+        # own, byte for byte but for the prefix.
+        def self.fail_with(stderr, message, status)
+            stderr.puts("tessella bitfield: #{message}")
+            status
+        end
+
+        def self.draw(argv, stdin)
+            opts, paths = BitfieldOptions.parse(argv)
+            raise UsageError, "too many arguments" if paths.size > 1
+
+            text = CLI.read_text(paths.first, stdin, DataError)
+            finish(text, opts)
+        end
+
+        # Usage is settled by now; what drawing still refuses (a bad
+        # line, a name too wide, output past --max-width) is bad input.
+        def self.finish(text, opts)
+            block = Tessella.bitfield(text, word: opts.fetch(:word, 32),
+                                            octets: opts[:octets] || false,
+                                            ruler: !opts[:no_ruler],
+                                            abbrev: opts[:abbrev] || false)
+            check_max_width!(block, opts[:max_width])
+            block.to_s
+        rescue ArgumentError => e
+            raise DataError, e.message
+        end
+
+        def self.check_max_width!(block, max_width)
+            return unless max_width
+
+            block.lines.each do |line|
+                width = Width.of(line)
+                next if width <= max_width
+
+                raise DataError, "a line is #{width} columns, over " \
+                                 "--max-width #{max_width}"
+            end
+        end
+    end
+
+    # bitfield's options: --word validated immediately (a usage error,
+    # as the script's own OptionParser block), the rest stored as-is.
+    class BitfieldOptions
+        def self.parse(argv)
+            new.parse(argv)
+        end
+
+        def initialize
+            @opts = {}
+            @parser = OptionParser.new { |op| add(op) }
+        end
+
+        def parse(argv)
+            @parser.parse!(argv)
+            [@opts, argv]
+        end
+
+        private
+
+        def add(op)
+            add_word(op)
+            op.on("--octets") { @opts[:octets] = true }
+            op.on("--no-ruler") { @opts[:no_ruler] = true }
+            op.on("--abbrev") { @opts[:abbrev] = true }
+            op.on("--ascii") { @opts[:ascii] = true }
+            op.on("--max-width N", Integer) { |n| @opts[:max_width] = n }
+        end
+
+        def add_word(op)
+            op.on("--word N", Integer) do |n|
+                unless Bitfield::WORD_SIZES.include?(n)
+                    raise BitfieldCLI::UsageError,
+                          "--word must be 8, 16, 32 or 64"
+                end
+                @opts[:word] = n
+            end
+        end
+    end
+end