tessella 0.3.0

data/lib/tessella/cli/meter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella meter` (DESIGN.md, "Meters and rules"): one meter line
+    # for FRACTION (0..1, or 45%). Exit 0 drawn; 2 usage (a bad flag,
+    # an unknown style, a mixed-class pair, a fraction out of range).
+    class MeterCLI
+        class UsageError < StandardError; end
+        # Raised by --help, carrying its text.
+        class Help < StandardError; end
+
+        BANNER = "Usage: tessella meter [options] FRACTION  (0..1, or 45%)\n"
+
+        def self.run(argv, stdout:, stderr:, **)
+            stdout.print(draw(argv))
+            0
+        rescue Help => e
+            stdout.print(e.message)
+            0
+        rescue OptionParser::ParseError, UsageError, ArgumentError => e
+            stderr.puts("tessella meter: #{e.message}")
+            2
+        end
+
+        def self.draw(argv)
+            opts, args = parse(argv.dup)
+            raise UsageError, "one FRACTION, got #{args.size}" unless
+                args.size == 1
+
+            Tessella.meter(args.first, **opts).to_s
+        end
+
+        def self.parse(argv)
+            opts = {}
+            parser = OptionParser.new(BANNER)
+            options(parser, opts)
+            [opts, parser.parse!(argv)]
+        end
+
+        def self.options(parser, opts)
+            styles = Glyphs::METERS.keys.each_slice(4)
+                                   .map { "#{it.join(", ")}," }
+            parser.on("--style S", *styles,
+                      "or a fill and a track glyph") { opts[:style] = it }
+            layout(parser, opts)
+            titles(parser, opts)
+            flags(parser, opts)
+        end
+
+        def self.layout(parser, opts)
+            parser.on("--width N", Integer, "horizontal bar cells " \
+                                            "(default 20)") do |n|
+                opts[:width] = n
+            end
+            parser.on("--orientation O", %w[horizontal vertical],
+                      "horizontal, or vertical: filled bottom-up") do |v|
+                opts[:orientation] = v.to_sym
+            end
+            parser.on("--height N", Integer,
+                      "vertical bar cells (default 8)") { opts[:height] = it }
+        end
+
+        def self.titles(parser, opts)
+            parser.on("--title T", "text before the bar") { opts[:title] = it }
+            parser.on("--title-width N", Integer, "pad the title to N " \
+                                                  "columns") do |n|
+                opts[:title_width] = n
+            end
+        end
+
+        def self.flags(parser, opts)
+            parser.on("--no-label", "no percentage") { opts[:label] = false }
+            parser.on("--no-brackets", "no [ ]") { opts[:brackets] = false }
+            parser.on("--[no-]ascii", "the classic style: [=====     ]") do |v|
+                opts[:ascii] = v
+            end
+            parser.on("--help", "print this help") { raise Help, parser.to_s }
+        end
+    end
+end

data/lib/tessella/cli/rule.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella rule` (DESIGN.md, "Meters and rules"): one divider line.
+    # Exit 0 drawn; 2 usage (a bad flag, an unknown style, an ornament
+    # too wide, a non-ASCII ornament under --ascii, an argument).
+    class RuleCLI
+        # Raised by --help, carrying its text.
+        class Help < StandardError; end
+
+        BANNER = "Usage: tessella rule [options]\n"
+
+        def self.run(argv, stdout:, stderr:, **)
+            stdout.print(draw(argv))
+            0
+        rescue Help => e
+            stdout.print(e.message)
+            0
+        rescue OptionParser::ParseError, ArgumentError => e
+            stderr.puts("tessella rule: #{e.message}")
+            2
+        end
+
+        def self.draw(argv)
+            opts, args = parse(argv.dup)
+            raise ArgumentError, "no argument expected: #{args.first}" if
+                args.any?
+
+            Tessella.rule(**opts).to_s
+        end
+
+        def self.parse(argv)
+            opts = {}
+            parser = OptionParser.new(BANNER)
+            options(parser, opts)
+            [opts, parser.parse!(argv)]
+        end
+
+        def self.options(parser, opts)
+            parser.on("--width N", Integer, "columns (default 78)") do |n|
+                opts[:width] = n
+            end
+            parser.on("--ornament T", "text centred in the line") do |t|
+                opts[:ornament] = t
+            end
+            parser.on("--style S", Glyphs::RULES.keys.join(", ")) do |s|
+                opts[:style] = s
+            end
+            flags(parser, opts)
+        end
+
+        def self.flags(parser, opts)
+            parser.on("--[no-]ascii", "a line of -") { opts[:ascii] = it }
+            parser.on("--help", "print this help") { raise Help, parser.to_s }
+        end
+    end
+end

data/lib/tessella/cli/seq.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella seq`: reads one file or stdin, draws a sequence
+    # diagram via Tessella.seq, and prints it. Exit 0 drawn, 1 bad
+    # input (an unrecognised statement, a non-ASCII name under
+    # --ascii, no statements or participants, output past
+    # --max-width), 2 usage. The artlint pass the skill's seq.rb runs
+    # by default stays in the skill; there is no --no-lint here.
+    class SeqCLI
+        class Error < StandardError; end
+        class UsageError < Error; end
+        class DataError < Error; end
+
+        # Raised by --help to short-circuit parsing with a message
+        # and a 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 seq [options] [file]"
+
+        def self.run(argv, stdin:, stdout:, stderr:)
+            draw(argv, stdin, stdout)
+        rescue Halt => e
+            CLI.halt(e, stdout, stderr)
+        rescue OptionParser::ParseError, UsageError => e
+            usage_error(e, stderr)
+        rescue DataError, ArgumentError => e
+            data_error(e, stderr)
+        end
+
+        def self.draw(argv, stdin, stdout)
+            opts, path = Options.parse(argv.dup)
+            text = CLI.read_text(path, stdin, DataError)
+            block = Tessella.seq(text, ascii: opts[:ascii],
+                                       numbered: opts[:numbered],
+                                       footer: opts[:footer])
+            check_max_width!(block, opts[:max_width])
+            stdout.print(block.to_s)
+            0
+        end
+
+        def self.check_max_width!(block, max_width)
+            return unless max_width
+
+            w = block.lines.map { Width.of(it.rstrip) }.max
+            return if w <= max_width
+
+            raise DataError,
+                  "output is #{w} columns, over --max-width #{max_width}"
+        end
+
+        def self.usage_error(error, stderr)
+            stderr.puts("tessella seq: #{error.message}")
+            stderr.puts(BANNER)
+            2
+        end
+
+        def self.data_error(error, stderr)
+            stderr.puts("tessella seq: #{error.message}")
+            1
+        end
+    end
+
+    # Parses argv into { ascii:, numbered:, footer:, max_width: } plus
+    # at most one file argument; raises Halt for --help, or lets
+    # OptionParser::ParseError escape for a bad flag or value.
+    class SeqCLI
+        class Options
+            def self.parse(argv)
+                new.parse(argv)
+            end
+
+            def initialize
+                @opts = { ascii: Target.ascii? }
+                @parser = OptionParser.new
+                @parser.banner = SeqCLI::BANNER
+                build
+            end
+
+            def parse(argv)
+                @parser.parse!(argv)
+                raise SeqCLI::UsageError, "one file argument at most" if
+                    argv.size > 1
+
+                [@opts, argv.first]
+            end
+
+            private
+
+            def build
+                @parser.on("--[no-]ascii") { @opts[:ascii] = it }
+                @parser.on("--numbered") { @opts[:numbered] = true }
+                @parser.on("--footer") { @opts[:footer] = true }
+                add_max_width
+                add_help
+            end
+
+            def add_max_width
+                @parser.on("--max-width N", Integer) { @opts[:max_width] = it }
+            end
+
+            def add_help
+                @parser.on("-h", "--help") do
+                    raise SeqCLI::Halt.new(0, @parser.to_s)
+                end
+            end
+        end
+    end
+end

data/lib/tessella/cli/sparkline.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella sparkline` (DESIGN.md, "Meters and rules"): one line
+    # from the VALUES given, or read from stdin (split on blanks and
+    # commas). Exit 0 drawn; 1 bad input (no value, a non-number); 2
+    # usage.
+    class SparklineCLI
+        class DataError < StandardError; end
+        # Raised by --help, carrying its text.
+        class Help < StandardError; end
+
+        BANNER = "Usage: tessella sparkline [options] [VALUE ...]  " \
+                 "(stdin if none)\n"
+
+        def self.run(argv, stdin:, stdout:, stderr:)
+            stdout.print(draw(argv, stdin))
+            0
+        rescue Help => e
+            stdout.print(e.message)
+            0
+        rescue DataError => e
+            fail_with(stderr, e.message, 1)
+        rescue OptionParser::ParseError, ArgumentError => e
+            fail_with(stderr, e.message, 2)
+        end
+
+        def self.draw(argv, stdin)
+            opts, words = parse(argv.dup)
+            source = words.empty? ? stdin.read : words.join(" ")
+            CLI.utf8!(source, DataError)
+            Tessella.sparkline(numbers(source), **opts).to_s
+        end
+
+        def self.fail_with(stderr, message, status)
+            stderr.puts("tessella sparkline: #{message}")
+            status
+        end
+
+        def self.numbers(text)
+            fields = text.split(/[\s,]+/).reject(&:empty?)
+            raise DataError, "no value" if fields.empty?
+
+            fields.map do |f|
+                value = Float(f, exception: false)
+                raise DataError, "not a number: #{f.inspect}" unless
+                    value&.finite?
+
+                value
+            end
+        end
+
+        def self.parse(argv)
+            opts = {}
+            parser = OptionParser.new(BANNER)
+            options(parser, opts)
+            [opts, parser.parse!(argv)]
+        end
+
+        def self.options(parser, opts)
+            parser.on("--width N", Integer, "cells (one a value)") do |n|
+                opts[:width] = n
+            end
+            parser.on("--min A", Float, "range bottom") { opts[:min] = it }
+            parser.on("--max B", Float, "range top") { opts[:max] = it }
+            parser.on("--[no-]ascii", "eight ASCII levels: _.-:=+*#") do |v|
+                opts[:ascii] = v
+            end
+            parser.on("--help", "print this help") { raise Help, parser.to_s }
+        end
+    end
+end

data/lib/tessella/cli/table.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella table` options (ported from the ascii-art skill's
+    # scripts/table.rb): everything a usage error can be -- an
+    # unknown --style, a malformed --align, a negative --max-width,
+    # more than one file -- is settled here, before any row is read.
+    class TableOptions
+        def self.parse(argv)
+            new.parse(argv)
+        end
+
+        def initialize
+            @opts = { ascii: Target.ascii?, tsv: false, no_header: false }
+            @parser = build_parser
+        end
+
+        def parse(argv)
+            @parser.parse!(argv)
+            raise TableCLI::UsageError, "too many arguments" if argv.size > 1
+
+            check_custom_style!
+            [@opts, argv]
+        end
+
+        private
+
+        def usage!(message) = raise(TableCLI::UsageError, message)
+
+        def build_parser
+            OptionParser.new do |op|
+                op.banner = TableCLI::BANNER
+                add_input(op)
+                add_style(op)
+                add_output(op)
+            end
+        end
+
+        def add_input(op)
+            op.on("--tsv") { @opts[:tsv] = true }
+            op.on("--no-header") { @opts[:no_header] = true }
+            op.on("--align SPEC") { |s| @opts[:align] = align!(s) }
+        end
+
+        # A name, or a glyph set checked as a table's (11 glyphs).
+        def style!(spec, names)
+            name = Borders.name(spec)
+            return name if names.include?(name.to_s)
+
+            usage!("unknown --style #{spec}") unless Borders.custom?(spec)
+            Table::Glyphs.custom(spec)
+            spec
+        rescue ArgumentError => e
+            usage!(e.message)
+        end
+
+        def check_custom_style!
+            style = @opts[:style]
+            Borders.custom(style, ascii: @opts[:ascii]) if
+                Borders.custom?(style)
+        rescue ArgumentError => e
+            usage!(e.message)
+        end
+
+        def align!(spec)
+            usage!("--align must be letters l, r or c") unless
+                /\A[lrc]+\z/i.match?(spec)
+            spec.downcase
+        end
+
+        def add_style(op)
+            names = Table::STYLE_NAMES.map(&:to_s)
+            op.on("--style S", "#{names.join(", ")},",
+                  "or 11 glyphs: tl tr bl br h v top_t bot_t",
+                  "sep_l sep_t sep_r") do |s|
+                @opts[:style] = style!(s, names)
+            end
+            op.on("--[no-]ascii") { @opts[:ascii] = it }
+            op.on("--title TEXT") { |t| @opts[:title] = t }
+        end
+
+        def add_output(op)
+            op.on("--max-width N", Integer) do |n|
+                usage!("--max-width must be >= 1") if n < 1
+                @opts[:max_width] = n
+            end
+            op.on("-h", "--help") do
+                @opts[:help] = true
+            end
+        end
+    end
+
+    # `tessella table` (DESIGN.md, "Command line"): one table from
+    # one CSV/TSV file argument ("-" or none for stdin). Exit 0 drawn,
+    # 1 bad input (a ragged row, no rows, malformed CSV, output past
+    # --max-width), 2 usage. The script's --no-lint has no equivalent
+    # here: the artlint.rb pass stays in the skill.
+    class TableCLI
+        class UsageError < StandardError; end
+        class DataError < StandardError; end
+
+        BANNER = <<~TEXT
+            Usage: tessella table [options] [file]  (stdin if none)
+                --tsv --no-header --align SPEC --style NAME|GLYPHS --[no-]ascii
+                --title TEXT --max-width N
+        TEXT
+
+        def self.run(argv, stdin:, stdout:, stderr:)
+            opts, paths = TableOptions.parse(argv.dup)
+            return help(stdout) if opts[:help]
+
+            stdout.print(draw(paths.first, opts, 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(BANNER)
+            0
+        end
+
+        def self.fail_with(stderr, message, status)
+            stderr.puts("tessella table: #{message}")
+            stderr.print(BANNER) if status == 2
+            status
+        end
+
+        def self.draw(path, opts, stdin)
+            text = CLI.read_text(path == "-" ? nil : path, stdin, DataError)
+            rows = Table.parse(text, tsv: opts[:tsv])
+            header = !opts[:no_header]
+            block = build(rows, header, opts)
+            check_max_width!(block, opts[:max_width])
+            block.to_s
+        rescue ArgumentError => e
+            raise DataError, e.message
+        end
+
+        def self.build(rows, header, opts)
+            head, body = Table.split(rows, header)
+            check_align_length!(opts[:align], (head || body.first).size)
+            Tessella.table(rows, header: header, style: opts[:style],
+                                 ascii: opts[:ascii], align: opts[:align],
+                                 title: opts[:title])
+        end
+
+        def self.check_align_length!(align, ncols)
+            return unless align && align.length != ncols
+
+            raise UsageError,
+                  "--align has #{align.length} letters, #{ncols} columns"
+        end
+
+        def self.check_max_width!(block, max_width)
+            return unless max_width
+
+            over = block.lines.map(&:rstrip).find { Width.of(it) > max_width }
+            return unless over
+
+            raise DataError, "output is #{Width.of(over)} columns, over " \
+                             "--max-width #{max_width}"
+        end
+    end
+end

data/lib/tessella/cli/text.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella text` (DESIGN.md, "Text styles"): TEXT (the words given,
+    # or stdin when none) in a style. A letter or digit with no form in
+    # it passes through, named on stderr; --strict makes that exit 1.
+    # --plain turns any style back to plain text. Exit 0; 1 under
+    # --strict when a character has no form; 2 usage (no --style, an
+    # unknown style, --ascii).
+    class TextCLI
+        class UsageError < StandardError; end
+        class DataError < StandardError; end
+        # Raised by --help, carrying its text.
+        class Help < StandardError; end
+
+        BANNER = "Usage: tessella text --style S [--strict] [TEXT ...]  " \
+                 "(stdin if none)\n       tessella text --plain [TEXT ...]\n"
+
+        def self.run(argv, stdin:, stdout:, stderr:)
+            opts, words = parse(argv.dup)
+            convert(input(words, stdin), opts, stdout, stderr)
+        rescue Help => e
+            stdout.print(e.message)
+            0
+        rescue DataError, OptionParser::ParseError, UsageError,
+               ArgumentError => e
+            stderr.puts("tessella text: #{e.message}")
+            e.is_a?(DataError) ? 1 : 2
+        end
+
+        # The words given, or stdin; UTF-8 either way.
+        def self.input(words, stdin)
+            text = words.empty? ? stdin.read : "#{words.join(" ")}\n"
+            CLI.utf8!(text, DataError)
+        end
+
+        def self.convert(text, opts, stdout, stderr)
+            style = opts[:style] or raise UsageError, "--style S or --plain"
+            raise UsageError, "text styles are not ASCII" if opts[:ascii]
+
+            missing = Text.unmapped(text, style)
+            stdout.print(Tessella.text(text, style: style)) unless
+                opts[:strict] && missing.any?
+            return 0 if missing.empty?
+
+            name = Text.dashed(Borders.name(style))
+            stderr.puts("tessella text: no #{name} form for: " \
+                        "#{missing.join(" ")}")
+            opts[:strict] ? 1 : 0
+        end
+
+        def self.parse(argv)
+            opts = {}
+            parser = OptionParser.new(BANNER)
+            options(parser, opts)
+            [opts, parser.parse!(argv)]
+        end
+
+        def self.options(parser, opts)
+            names = (Text::STYLES - [:plain]).map { Text.dashed(it) }
+            lines = names.each_slice(3).map { "#{it.join(", ")}," }
+            parser.on("--style S", *lines) { opts[:style] = it }
+            parser.on("--plain", "any style back to plain") do
+                opts[:style] = "plain"
+            end
+            flags(parser, opts)
+        end
+
+        def self.flags(parser, opts)
+            parser.on("--strict", "exit 1 when a letter or digit has no " \
+                                  "form") { opts[:strict] = true }
+            parser.on("--ascii", "refused: every style is non-ASCII") do
+                opts[:ascii] = true
+            end
+            parser.on("--help", "print this help") { raise Help, parser.to_s }
+        end
+    end
+end

data/lib/tessella/cli/tree.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella tree` (DESIGN.md, "Command line"): draws one tree from
+    # a file argument or stdin. Same options as the ascii-art skill's
+    # scripts/tree.rb minus --no-lint (its lint pass stays in the
+    # skill) plus --help; messages are prefixed "tessella tree: ".
+    # Exit 0 drawn; 1 bad input, an ArgumentError from Tree itself
+    # (a tab, a bad indent, a skipped level, an unknown style, a
+    # render past --max-width); 2 usage (an unknown option, more than
+    # one file argument, or a missing file, as tree.rb itself exits
+    # for the last of those).
+    class TreeCLI
+        class UsageError < StandardError; end
+        class Help < StandardError; end
+
+        USAGE_ERRORS = [OptionParser::ParseError, UsageError].freeze
+
+        USAGE = <<~TEXT
+            Usage: tessella tree [--style S] [--[no-]ascii] [--root NAME]
+                                 [--max-width N] [file]  (stdin if none)
+        TEXT
+
+        def self.run(argv, stdin:, stdout:, stderr:)
+            opts, paths = TreeOptions.parse(argv.dup)
+            check_arity!(paths)
+            stdout.print(draw(input(paths, stdin), opts))
+            0
+        rescue Help
+            help(stdout)
+        rescue *USAGE_ERRORS => e
+            fail_with(stderr, e.message, 2)
+        rescue ArgumentError => e
+            fail_with(stderr, e.message, 1)
+        end
+
+        def self.input(paths, stdin)
+            CLI.read_text(paths.first, stdin, ArgumentError)
+        end
+
+        def self.help(stdout)
+            stdout.print(USAGE)
+            0
+        end
+
+        def self.fail_with(stderr, message, status)
+            stderr.puts("tessella tree: #{message}")
+            status
+        end
+
+        def self.check_arity!(paths)
+            raise UsageError, "too many arguments" if paths.size > 1
+        end
+
+        # Usage is settled by now; style is ignored under --ascii, as
+        # tree.rb itself ignores it rather than refusing the conflict
+        # (Tree.render's own refusal is for a direct Tessella.tree
+        # call made with both; this CLI never reaches it, since it
+        # drops style whenever --ascii is given, same as the script).
+        def self.draw(text, opts)
+            style = opts[:ascii] ? nil : opts[:style]
+            result = Tree.render(text, style: style, ascii: opts[:ascii],
+                                       root: opts[:root])
+            Tree.check_max_width!(result, opts[:max_width])
+            Block.new(result.lines).to_s
+        end
+    end
+
+    # `tessella tree`'s options: --style (one of STYLE_NAMES; another
+    # value is OptionParser's own usage error, as tree.rb's own
+    # `--style S, STYLES.keys` is), --ascii, --root NAME, --max-width
+    # N, and -h/--help, which raises immediately on being parsed (as
+    # tree.rb's own `-h`/`--help` prints its usage and exits on the
+    # spot, so an error in an option before it on the line still wins).
+    class TreeOptions
+        STYLE_NAMES = %w[light heavy rounded].freeze
+
+        def self.parse(argv)
+            opts = { style: nil, ascii: Target.ascii?, root: nil,
+                     max_width: nil }
+            build_parser(opts).parse!(argv)
+            [opts, argv]
+        end
+
+        def self.build_parser(opts)
+            OptionParser.new do |op|
+                op.banner = TreeCLI::USAGE
+                add_options(op, opts)
+            end
+        end
+
+        def self.add_options(op, opts)
+            op.on("--style S", STYLE_NAMES) { |s| opts[:style] = s.to_sym }
+            op.on("--[no-]ascii") { opts[:ascii] = it }
+            op.on("--root NAME") { |n| opts[:root] = n }
+            op.on("--max-width N", Integer) { |n| opts[:max_width] = n }
+            op.on("-h", "--help") { raise TreeCLI::Help }
+        end
+    end
+end