tessella 0.3.0

data/lib/tessella/cli/chart_help.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella chart --help`: the kinds and what each reads, and a
+    # description of every option -- filled into the parser's switches
+    # after they are built, so the option definitions stay short.
+    class ChartCLI
+        module Help
+            BANNER = <<~TEXT
+                Usage: tessella chart [options] [file]  (stdin if none)
+
+                Kinds (--kind) and the columns they read, a row a line:
+                  line, scatter, stairs, density  y; x y; or x and a y a series
+                  bar          label value; or label and a value a series
+                  histogram    values (one column)
+                  box          a column a box, a header naming them
+                  stem         one column, or two back to back
+                  heatmap      label then a row of values
+                  candlestick  x open high low close
+                  pie          label value
+
+                Options (some only for the kinds named):
+            TEXT
+
+            DESCRIPTIONS = {
+                "--kind" => ["the chart kind (default line)"],
+                "--width" => ["plot columns (default 40)"],
+                "--height" => ["plot rows (default 15)"],
+                "--title" => ["a title above the frame"],
+                "--xlabel" => ["the x axis label"],
+                "--ylabel" => ["the y axis label"],
+                "--xlim" => ["the x range, A,B"],
+                "--ylim" => ["the y range, A,B"],
+                "--canvas" => ["braille, block (quadrant), half, sextant,",
+                               "octant (Unicode 16), dot,",
+                               "ascii, density, or eighths (--area)"],
+                "--ascii" => ["ASCII only, from the first byte"],
+                "--color" => ["ANSI colours (off by default)"],
+                "--xscale" => ["ln, log2 or log10 on x"],
+                "--yscale" => ["ln, log2 or log10 on y (plotted kinds)"],
+                "--xdate" => ["x is ISO 8601 dates; FMT a strftime",
+                              "format (plotted kinds, candlestick)"],
+                "--yerr" => ["x y error: error bars (line, scatter)"],
+                "--threshold" => ["a dashed rule at N (line, scatter,",
+                                  "stairs)"],
+                "--above" => ["colour beyond --threshold (red)"],
+                "--below" => ["colour before --threshold"],
+                "--bins" => ["histogram bins (Sturges by default)"],
+                "--closed" => ["histogram bins closed left or right"],
+                "--orientation" => ["horizontal or vertical: the value",
+                                    "axis's direction"],
+                "--blocks" => ["bar glyphs: eighths, braille, block,",
+                               "quadrant, half, sextant or octant"],
+                "--cell-width" => ["heatmap columns a cell (2)"],
+                "--colormap" => ["heatmap colours, C,C,... (--color)"],
+                "--min" => ["heatmap range bottom"],
+                "--max" => ["heatmap range top"],
+                "--donut" => ["pie: a ring, hollow in the middle"],
+                "--rim" => ["pie edge: cells (default), smooth (shaped",
+                            "glyphs) or basic (smooth, older fonts)"],
+                "--style" => ["stairs: post or pre"],
+                "--scale" => ["stem: the stem unit"],
+                "--area" => ["fill under the line (line, stairs)"],
+                "--gradient" => ["area colours by height, C,C,... or",
+                                 "none (--color)"],
+                "--stacked" => ["bar: stack the series"],
+                "--fill" => ["bar glyph (█, # in ASCII)"],
+                "--no-eighths" => ["bar: whole cells only"],
+                "--track" => ["bar track glyph, or none"],
+                "--help" => ["print this help"],
+                "--version" => ["print the version"]
+            }.freeze
+
+            # Each switch's description from DESCRIPTIONS, by its long
+            # name (--[no-]x and --no-x alike).
+            def self.describe!(parser)
+                parser.top.list.each do |switch|
+                    name = Array(switch.long).first.to_s
+                    text = DESCRIPTIONS[name.sub("[no-]", "")]
+                    switch.desc.replace(text) if text && switch.desc.empty?
+                end
+            end
+        end
+    end
+end

data/lib/tessella/cli/chart_pie.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Tessella
+    # pie: label value, a row a slice, --donut for a ring (DESIGN.md's
+    # CLI input rules). A pie has no axes: --width, --xlim, --ylim,
+    # --canvas and --xscale are refused, --height sizes the disc.
+    class ChartCLI
+        class PieKind
+            REFUSED = { width: "--width", xlim: "--xlim", ylim: "--ylim",
+                        canvas: "--canvas", xscale: "--xscale" }.freeze
+
+            def self.build(opts, rows)
+                refuse!(opts)
+                _header, data = Header.split(rows, bar_like: true)
+                two!(data)
+                ChartCLI.fills!(data.size, "slices")
+                Tessella.pie(data.map(&:first),
+                             Columns.numeric(data, 1, "value"),
+                             **ChartOpts.for(opts).except(*REFUSED.keys))
+            end
+
+            def self.refuse!(opts)
+                key = REFUSED.keys.find { opts.key?(it) }
+                return unless key
+
+                raise UsageError, "#{REFUSED[key]} is not valid with --kind pie"
+            end
+
+            def self.two!(data)
+                i = data.index { it.size != 2 }
+                return unless i
+
+                raise DataError, "row #{i + 1} has #{data[i].size} columns: " \
+                                 "pie reads label value"
+            end
+        end
+    end
+end

data/lib/tessella/cli/compose.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella compose` (DESIGN.md, "Command line"): one composition
+    # per subcommand over blocks read from files ("-" for stdin, once).
+    # Exit 0 drawn, 1 bad input (a missing file, an empty block, a tab,
+    # non-ASCII under --ascii, output past --max-width), 2 usage.
+    class ComposeCLI
+        class UsageError < StandardError; end
+        class DataError < StandardError; end
+        # Raised by a subcommand's --help, carrying its text.
+        class Help < StandardError; end
+
+        USAGE = <<~TEXT
+            Usage: tessella compose frame  [--title T] [--style S] [--pad N]
+                                          [--fill P] [--halo H] BLOCK
+                   tessella compose shadow [--glyph G] BLOCK
+                   tessella compose fill   [--pattern P] [--halo H] BLOCK
+                   tessella compose grid   [--columns N] [--gap N] [--row-gap N]
+                                          [--align A] BLOCK...
+                   tessella compose beside [--gap N] [--align A] BLOCK...
+                   tessella compose stack  [--gap N] [--rule C] [--center] BLOCK...
+                   tessella compose indent --prefix STR [--suffix STR] BLOCK
+                   tessella compose caption --text T [--above] BLOCK
+            Every subcommand also takes --[no-]ascii and --max-width N.
+        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 Help => e
+            stdout.print(e.message)
+            0
+        rescue UsageError, OptionParser::ParseError => e
+            fail_with(stderr, e.message, 2)
+        rescue DataError => e
+            fail_with(stderr, e.message, 1)
+        end
+
+        # A subcommand's own lines out of USAGE: its line and the
+        # continuation lines under it.
+        def self.usage_line(sub)
+            lines = USAGE.lines
+            i = lines.index { it.include?("compose #{sub} ") }
+            more = lines[(i + 1)..].take_while do |line|
+                !line.include?("tessella") && line.start_with?("  ")
+            end
+            ["Usage: #{lines[i].strip.delete_prefix("Usage: ")}\n",
+             *more].join
+        end
+
+        def self.help(stdout)
+            stdout.print(USAGE)
+            0
+        end
+
+        def self.fail_with(stderr, message, status)
+            stderr.puts("tessella compose: #{message}")
+            stderr.print(USAGE) if status == 2
+            status
+        end
+
+        def self.draw(argv, stdin)
+            sub = argv.shift or raise UsageError, "missing subcommand"
+            command = ComposeCommands.fetch(sub)
+            opts, paths = ComposeOptions.parse(sub, argv)
+            ComposeCommands.check_arity!(sub, paths)
+            blocks = ComposeReader.blocks(paths, opts, stdin)
+            finish(command, blocks, opts)
+        end
+
+        # Usage is settled by now; what the composition still refuses
+        # (a non-ASCII title, output past --max-width) is bad input.
+        def self.finish(command, blocks, opts)
+            figure = command.call(blocks, opts)
+            figure.check_width!(opts[:max_width]) if opts[:max_width]
+            figure.to_s
+        rescue ArgumentError => e
+            raise DataError, e.message
+        end
+    end
+
+    # The five subcommands: how many blocks each takes, and the call
+    # that composes them.
+    module ComposeCommands
+        ARITY = { "frame" => 1, "indent" => 1, "caption" => 1, "shadow" => 1,
+                  "fill" => 1, "grid" => 1..,
+                  "beside" => 2.., "stack" => 2.. }.freeze
+
+        def self.fetch(sub)
+            ARITY.fetch(sub) do
+                raise ComposeCLI::UsageError, "unknown subcommand #{sub}"
+            end
+            method(:"#{sub}_call")
+        end
+
+        def self.check_arity!(sub, paths)
+            arity = ARITY.fetch(sub)
+            return if arity === paths.size # rubocop:disable Style/CaseEquality
+
+            want = if arity.is_a?(Integer)
+                       "exactly one BLOCK"
+                   else
+                       "at least #{arity.begin} BLOCK#{"s" if arity.begin > 1}"
+                   end
+            raise ComposeCLI::UsageError, "#{sub} takes #{want}"
+        end
+
+        def self.frame_call(blocks, o)
+            Compose.frame(blocks.first, title: o[:title], style: o[:style],
+                                        pad: o.fetch(:pad, 1), ascii: o[:ascii],
+                                        fill: o[:fill],
+                                        halo: o.fetch(:halo, true))
+        end
+
+        def self.beside_call(blocks, o)
+            Compose.beside(*blocks, gap: o.fetch(:gap, 1),
+                                    align: o.fetch(:align, :top),
+                                    ascii: o[:ascii])
+        end
+
+        def self.stack_call(blocks, o)
+            Compose.stack(*blocks, gap: o.fetch(:gap, 0), rule: o[:rule],
+                                   center: o[:center], ascii: o[:ascii])
+        end
+
+        def self.indent_call(blocks, o)
+            Compose.indent(blocks.first, prefix: o[:prefix],
+                                         suffix: o[:suffix], ascii: o[:ascii])
+        end
+
+        def self.grid_call(blocks, o)
+            Compose.grid(*blocks, columns: o.fetch(:columns, 2),
+                                  gap: o.fetch(:gap, 2),
+                                  row_gap: o.fetch(:row_gap, 1),
+                                  align: o.fetch(:align, :top),
+                                  ascii: o[:ascii])
+        end
+
+        def self.fill_call(blocks, o)
+            Compose.fill(blocks.first, pattern: o[:pattern], ascii: o[:ascii],
+                                       halo: o.fetch(:halo, true))
+        end
+
+        def self.shadow_call(blocks, o)
+            Compose.shadow(blocks.first, glyph: o[:glyph], ascii: o[:ascii])
+        end
+
+        def self.caption_call(blocks, o)
+            Compose.caption(blocks.first, text: o[:text], above: o[:above],
+                                          ascii: o[:ascii])
+        end
+    end
+end

data/lib/tessella/cli/compose_options.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella compose` options, per subcommand: everything a usage
+    # error can be (an unknown style or align, a style against --ascii,
+    # a negative count, a missing --prefix or --text) is settled here.
+    # --style's checks for `tessella compose frame`: a known name (not
+    # another style against --ascii) or a valid custom set. Kept apart
+    # so ComposeOptions stays under budget.
+    module ComposeStyleCheck
+        private
+
+        def check_style!
+            style = @opts[:style]
+            return unless style
+            return check_custom_style!(style) if Borders.custom?(style)
+
+            usage!("unknown --style #{style}") unless
+                Borders::STYLES.key?(style)
+            usage!(ascii_conflict(style)) if @opts[:ascii] && style != :ascii
+        end
+
+        # Named for where ASCII came from: the flag, or the cjk
+        # target's default, which --no-ascii lifts.
+        def ascii_conflict(style)
+            return "--style #{style} conflicts with --ascii" if @ascii_flag
+
+            "--style #{style} needs --no-ascii under target cjk"
+        end
+
+        def check_custom_style!(style)
+            Borders.custom(style, ascii: @opts[:ascii])
+        rescue ArgumentError => e
+            usage!(e.message)
+        end
+    end
+
+    # The flags of `tessella compose`'s subcommands, one definer per
+    # flag (ComposeOptions::FLAGS names which a subcommand takes).
+    # Kept apart so ComposeOptions stays under budget.
+    module ComposeFlags
+        HALO = { "sides" => true, "around" => :around, "none" => false }.freeze
+
+        private
+
+        def add_title
+            @parser.on("--title T", "a title in the top edge") do |t|
+                @opts[:title] = t
+            end
+        end
+
+        def add_style
+            @parser.on("--style S", "a border style, or six glyphs") do |s|
+                @opts[:style] = Borders.custom?(s) ? s : Borders.name(s)
+            end
+        end
+
+        def add_pad = add_count("--pad", :pad, "blank columns inside each side")
+        def add_gap = add_count("--gap", :gap, "blank columns (rows) between")
+
+        def add_center
+            @parser.on("--center", "centre narrower blocks") do
+                @opts[:center] = true
+            end
+        end
+
+        def add_prefix
+            @parser.on("--prefix STR", "the text before every line") do |p|
+                @opts[:prefix] = p
+            end
+        end
+
+        def add_suffix
+            @parser.on("--suffix STR", "the text after every line,",
+                       "rows padded to one width") { @opts[:suffix] = it }
+        end
+
+        def add_text = @parser.on("--text T", "caption") { @opts[:text] = it }
+
+        def add_glyph
+            @parser.on("--glyph G", "shadow glyph (░; # with --ascii)") do |g|
+                @opts[:glyph] = g
+            end
+        end
+
+        def add_fill
+            @parser.on("--fill P", "fill the inside: a pattern name or " \
+                                   "glyphs") { @opts[:fill] = it }
+        end
+
+        # --halo sides|around|none, or --no-halo for none.
+        def add_halo
+            @parser.on("--[no-]halo [H]", "blanks kept by text: sides,",
+                       "around or none") do |h|
+                @opts[:halo] = h == false ? false : (h || "sides")
+            end
+        end
+
+        # --halo's optional H took the word after it: one that names no
+        # halo is the block, given back.
+        def unhalo!(argv)
+            mode = @opts[:halo]
+            return unless mode.is_a?(String)
+
+            unless HALO.key?(mode)
+                argv.unshift(mode)
+                mode = "sides"
+            end
+            @opts[:halo] = HALO[mode]
+        end
+
+        def add_columns
+            @parser.on("--columns N", Integer, "figures a row (2)") do |n|
+                usage!("--columns must be >= 1") if n < 1
+                @opts[:columns] = n
+            end
+        end
+
+        def add_row_gap = add_count("--row-gap", :row_gap, "blank rows apart")
+
+        def add_pattern
+            @parser.on("--pattern P", "pattern name or glyphs (light)") do |p|
+                @opts[:pattern] = p
+            end
+        end
+
+        def add_above
+            @parser.on("--above", "caption above, not below") do
+                @opts[:above] = true
+            end
+        end
+
+        def add_count(flag, key, text)
+            @parser.on("#{flag} N", Integer, text) do |n|
+                usage!("#{flag} must be >= 0") if n.negative?
+                @opts[key] = n
+            end
+        end
+
+        def add_align
+            @parser.on("--align A", "top, middle or bottom") do |a|
+                usage!("unknown --align #{a}") unless
+                    Compose::ALIGNS.include?(a.to_sym)
+                @opts[:align] = a.to_sym
+            end
+        end
+
+        def add_rule
+            @parser.on("--rule C", "a rule of C between blocks") do |c|
+                usage!("--rule must be exactly one character") unless
+                    c.length == 1
+                @opts[:rule] = c
+            end
+        end
+    end
+
+    class ComposeOptions
+        include ComposeStyleCheck
+        include ComposeFlags
+
+        FLAGS = {
+            "frame" => %i[title style pad fill halo],
+            "beside" => %i[gap align],
+            "stack" => %i[gap rule center], "indent" => %i[prefix suffix],
+            "caption" => %i[text above], "shadow" => %i[glyph],
+            "fill" => %i[pattern halo],
+            "grid" => %i[columns gap row_gap align]
+        }.freeze
+        REQUIRED = { "indent" => :prefix, "caption" => :text }.freeze
+
+        def self.parse(sub, argv)
+            new(sub).parse(argv)
+        end
+
+        def initialize(sub)
+            @sub = sub
+            @opts = { ascii: Target.ascii? }
+            @parser = OptionParser.new
+            @parser.banner = ComposeCLI.usage_line(sub)
+            FLAGS.fetch(sub).each { send(:"add_#{it}") }
+            add_common
+        end
+
+        def parse(argv)
+            @parser.parse!(argv)
+            unhalo!(argv)
+            check_required!
+            check_style!
+            [@opts, argv]
+        end
+
+        private
+
+        def usage!(message) = raise(ComposeCLI::UsageError, message)
+
+        def add_common
+            add_ascii
+            @parser.on("--max-width N", Integer,
+                       "refuse a figure wider than N columns") do |n|
+                usage!("--max-width must be >= 1") if n < 1
+                @opts[:max_width] = n
+            end
+            add_help
+        end
+
+        def add_ascii
+            @parser.on("--[no-]ascii",
+                       "ASCII glyphs; refuse non-ASCII text") do |v|
+                @opts[:ascii] = v
+                @ascii_flag = v
+            end
+        end
+
+        def add_help
+            @parser.on("--help", "print this help") do
+                raise ComposeCLI::Help, @parser.to_s
+            end
+        end
+
+        def check_required!
+            key = REQUIRED[@sub]
+            usage!("#{@sub} requires --#{key}") if key && !@opts[key]
+        end
+    end
+
+    # Blocks for `tessella compose`, one per file argument ("-" is
+    # stdin, at most once), each refused as bad input, naming the file
+    # and line, when it is missing, empty, holds a tab, or holds a
+    # non-ASCII byte under --ascii.
+    module ComposeReader
+        def self.blocks(paths, opts, stdin)
+            if paths.count("-") > 1
+                raise ComposeCLI::UsageError, "'-' given more than once"
+            end
+
+            paths.map { block(it, opts[:ascii], stdin) }
+        end
+
+        def self.block(path, ascii, stdin)
+            text = CLI.read_text(path == "-" ? nil : path, stdin,
+                                 ComposeCLI::DataError, "#{path}:")
+            lines = text.lines(chomp: true)
+            check!(path, lines, ascii)
+            Block.new(lines)
+        rescue ArgumentError
+            raise ComposeCLI::DataError, "#{path}: empty block"
+        end
+
+        def self.check!(path, lines, ascii)
+            lines.each_with_index do |line, i|
+                where = "#{path}:#{i + 1}"
+                raise ComposeCLI::DataError, "#{where}: tab character" if
+                    line.include?("\t")
+                raise ComposeCLI::DataError, "#{where}: non-ASCII byte" if
+                    ascii && !line.ascii_only? && !Target.text_free?
+            end
+        end
+    end
+end

data/lib/tessella/cli/glyphs.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella glyphs` (DESIGN.md, "Glyphs"): the named glyph sets and
+    # their width classes, and the width targets each is safe for
+    # (--target T lists only those). No argument lists every set; KIND lists one
+    # kind; KIND NAME lists one set glyph by glyph (code point, class);
+    # --check GLYPHS classifies a set of one's own. Exit 0; 1 when
+    # --check finds the glyphs mix classes; 2 usage (an unknown kind or
+    # set, too many arguments).
+    class GlyphsCLI
+        class UsageError < StandardError; end
+        # Raised by --help, carrying its text.
+        class Help < StandardError; end
+
+        BANNER = "Usage: tessella glyphs [--target T] [KIND [NAME]] | " \
+                 "--check GLYPHS\n"
+        KINDS = %w[border pattern meter rule ramp head].freeze
+
+        def self.run(argv, stdout:, stderr:, **)
+            opts = parse(argv.dup)
+            return check(opts[:check], stdout) if opts[:check]
+
+            stdout.print(listing(*opts[:args], target: opts[:target]))
+            0
+        rescue Help => e
+            stdout.print(e.message)
+            0
+        rescue OptionParser::ParseError, UsageError, ArgumentError => e
+            stderr.puts("tessella glyphs: #{e.message}")
+            2
+        end
+
+        def self.parse(argv)
+            opts = {}
+            parser = OptionParser.new(BANNER)
+            parser.on("--check GLYPHS", "classify a set of one's own") do |g|
+                opts[:check] = g
+            end
+            target(parser, opts)
+            parser.on("--help", "print this help") { raise Help, parser.to_s }
+            opts[:args] = parser.parse!(argv)
+            opts
+        end
+
+        def self.target(parser, opts)
+            parser.on("--target T", Target::TARGETS.map(&:to_s),
+                      "only the sets safe for term, cjk or web") do |t|
+                opts[:target] = t.to_sym
+            end
+        end
+
+        def self.listing(kind = nil, name = nil, *rest, target: nil)
+            raise UsageError, "too many arguments" unless rest.empty?
+            return detail(Glyphs.fetch(kind!(kind), name)) if name
+
+            sets = Glyphs.all
+            sets = sets.select { it.kind == kind!(kind) } if kind
+            sets = sets.select { it.targets.include?(target) } if target
+            sets.map { row(it) }.join
+        end
+
+        def self.kind!(kind)
+            return kind.to_sym if KINDS.include?(kind)
+
+            raise UsageError, "unknown kind: #{kind} (#{KINDS.join(", ")})"
+        end
+
+        def self.row(set)
+            classes = set.classes.join("+")
+            flag = set.mixed? ? "  mixed" : ""
+            note = set.note ? "  (#{set.note})" : ""
+            line = format("%<kind>-8s %<name>-18s %<cls>-4s %<safe>-13s " \
+                          "%<glyphs>s",
+                          kind: set.kind, name: set.name, cls: classes,
+                          safe: set.targets.join(" "),
+                          glyphs: set.glyphs.strip)
+            "#{line}#{flag}#{note}\n"
+        end
+
+        def self.detail(set)
+            set.glyphs.chars.uniq.reject { it == " " }.map do |g|
+                format("%<g>s  U+%<code>04X  %<cls>s\n",
+                       g: g, code: g.ord, cls: Width.class_of(g))
+            end.join
+        end
+
+        def self.check(glyphs, stdout)
+            classes = Width.classes(glyphs)
+            mixed = classes.size > 1
+            prefix = mixed ? "mixed: " : ""
+            stdout.puts(prefix + classes.join(" "))
+            stdout.puts("safe for: #{Glyphs.targets(glyphs).join(" ")}")
+            mixed ? 1 : 0
+        end
+    end
+end