tessella 0.3.0

data/lib/tessella/cli/image.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella image` (DESIGN.md): draws a picture as text -- tones,
+    # blocks, half/quadrant/sextant/braille pixels, or edges -- from a
+    # file or stdin, ported from the ascii-art skill's
+    # scripts/img2art.rb. Its --pad is dropped: composition pads a
+    # block itself. Exit 0 drawn; 1 bad input (an unreadable file, a
+    # malformed or unsupported image, output past --max-width); 2
+    # usage (a bad flag, an unknown --style/--dither, or any other bad
+    # option value -- an ArgumentError Tessella.image raises once the
+    # image itself has decoded cleanly).
+    class ImageCLI
+        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 image [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)
+            raster = decode(Reader.bytes(path, stdin))
+            block = render(raster, opts)
+            Overflow.check!(block, opts[:max_width]) if opts[:max_width]
+            stdout.print(block.to_s)
+            0
+        end
+
+        # A bad file is bad input, before any option is judged: the
+        # image itself never decoded, so there is nothing to draw.
+        def self.decode(bytes)
+            Raster.decode(bytes)
+        rescue ArgumentError => e
+            raise DataError, e.message
+        end
+
+        # Past this point the source is a Raster, so Tessella.image
+        # can only still refuse an option's own value -- usage, not
+        # bad input.
+        def self.render(raster, opts)
+            Tessella.image(raster, **opts.except(:max_width))
+        rescue Image::Blank => e
+            raise DataError, e.message
+        rescue ArgumentError => e
+            raise UsageError, e.message
+        end
+
+        def self.fail_with(stderr, message, status)
+            stderr.puts("tessella image: #{message}")
+            status
+        end
+    end
+
+    # `tessella image`'s numeric options, kept apart so Options stays
+    # under budget.
+    class ImageCLI
+        module NumericOptions
+            private
+
+            def add_width
+                @parser.on("--width N", Integer, "columns (default 78)") do |n|
+                    @opts[:width] = n
+                end
+            end
+
+            def add_gamma
+                @parser.on("--gamma F", Float,
+                           "tone curve (default 1.0)") do |f|
+                    @opts[:gamma] = f
+                end
+            end
+
+            def add_threshold
+                @parser.on("--threshold F", Float,
+                           "on/off cut, 0..1 (default 0.5)") do |f|
+                    @opts[:threshold] = f
+                end
+            end
+
+            def add_edge_threshold
+                @parser.on("--edge-threshold F", Float,
+                           "edge strength to draw (default 0.3)") do |f|
+                    @opts[:edge_threshold] = f
+                end
+            end
+        end
+    end
+
+    # Parses argv into Tessella.image's options plus :max_width and
+    # 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 --style/--dither value.
+    class ImageCLI
+        class Options
+            include NumericOptions
+
+            STYLES = %w[ramp blocks half quadrant sextant braille octant petscii
+                        edges]
+                     .freeze
+            DITHERS = %w[none fs atkinson bayer].freeze
+
+            def self.parse(argv)
+                new.parse(argv)
+            end
+
+            def initialize
+                @opts = { style: :ramp, width: 78, ramp: nil, gamma: 1.0,
+                          threshold: 0.5, dither: :fs, invert: false,
+                          edge_threshold: 0.3,
+                          ascii: Target.ascii? }
+                @parser = OptionParser.new
+                @parser.banner = ImageCLI::BANNER
+                build
+            end
+
+            def parse(argv)
+                @parser.parse!(argv)
+                raise ImageCLI::UsageError, "too many arguments" if
+                    argv.size > 1
+
+                [@opts, argv.first]
+            end
+
+            private
+
+            def build
+                add_style
+                add_dither
+                add_numeric_opts
+                add_ramp
+                add_flags
+            end
+
+            def add_numeric_opts
+                add_width
+                add_gamma
+                add_threshold
+                add_edge_threshold
+            end
+
+            def add_flags
+                add_invert
+                add_ascii
+                add_max_width
+                add_help
+            end
+
+            def add_style
+                @parser.on("--style S", STYLES,
+                           "ramp, blocks, half, quadrant,",
+                           "sextant, braille, octant (Unicode 16),",
+                           "petscii (best-fit shapes) or edges") do |s|
+                    @opts[:style] = s.to_sym
+                end
+            end
+
+            def add_dither
+                @parser.on("--dither M", DITHERS, "none, fs (Floyd-Steinberg),",
+                           "atkinson or bayer") do |m|
+                    @opts[:dither] = m.to_sym
+                end
+            end
+
+            def add_ramp
+                @parser.on("--ramp STR", "tone glyphs, light to dense, or a",
+                           "name: ramp, blocks, long, hatch") do |r|
+                    @opts[:ramp] = r
+                end
+            end
+
+            def add_invert
+                @parser.on("--invert", "for a light background") do
+                    @opts[:invert] = true
+                end
+            end
+
+            def add_ascii
+                @parser.on("--[no-]ascii",
+                           "ASCII only (ramp style, ASCII ramp)") do |v|
+                    @opts[:ascii] = v
+                end
+            end
+
+            def add_max_width
+                @parser.on("--max-width N", Integer,
+                           "refuse lines wider than N") do |n|
+                    @opts[:max_width] = n
+                end
+            end
+
+            def add_help
+                @parser.on("--help", "print this help") do
+                    raise ImageCLI::Halt.new(0, @parser.to_s)
+                end
+            end
+        end
+    end
+
+    # The file argument, or stdin when there is none, read as binary
+    # bytes. Errors opening it (a missing file, a directory) are bad
+    # input, named by the system error's message.
+    class ImageCLI
+        module Reader
+            def self.bytes(path, stdin)
+                path ? File.binread(path) : stdin.binmode.read
+            rescue SystemCallError => e
+                raise ImageCLI::DataError, CLI.cannot_read(path, e)
+            end
+        end
+    end
+
+    # --max-width, after the image is drawn: the first line over it
+    # refuses the whole figure, naming the line and its width.
+    class ImageCLI
+        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 ImageCLI::DataError,
+                          "line #{i + 1}: #{w} columns exceeds " \
+                          "--max-width #{max}"
+                end
+            end
+        end
+    end
+end

data/lib/tessella/cli/input.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Reading a command's input (DESIGN.md, "Command line"): a file or
+    # stdin, as UTF-8, an unreadable file or a bad byte named as bad
+    # input. Kept apart so CLI's own class body stays under budget.
+    class CLI
+        # The 1-based number of the first line of text that is not
+        # valid UTF-8, or nil: the readers name it as bad input.
+        def self.invalid_line(text)
+            return nil if text.valid_encoding?
+
+            text.each_line.find_index { !it.valid_encoding? } + 1
+        end
+
+        # text, or error (a command's DataError) naming the first line
+        # that is not valid UTF-8: bad input, not a crash.
+        def self.utf8!(text, error, where = "line ")
+            text = text.dup.force_encoding(Encoding::UTF_8) unless
+                text.encoding == Encoding::UTF_8
+            bad = invalid_line(text)
+            raise error, "#{where}#{bad}: invalid UTF-8" if bad
+
+            text
+        end
+
+        # A command's input: the file at path, or stdin when path is
+        # nil, as UTF-8 text; an unreadable file or invalid UTF-8 is
+        # error (the command's DataError), the bad line named after
+        # where.
+        def self.read_text(path, stdin, error, where = "line ")
+            utf8!(path ? File.read(path) : stdin.read, error, where)
+        rescue SystemCallError => e
+            raise error, cannot_read(path, e)
+        end
+
+        # "cannot read PATH: reason" for a file a command cannot open,
+        # the reason in the system's own words (ENOENT's "No such file
+        # or directory"), not Ruby's "... @ rb_sysopen - PATH".
+        def self.cannot_read(path, error)
+            "cannot read #{path || "stdin"}: #{error.class.new(nil).message}"
+        end
+    end
+end

data/lib/tessella/cli/iso_time.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tessella
+    # ISO 8601 dates and times for `chart --xdate` (DESIGN.md, "Command
+    # line"): 2026-11-05, 2026-11-05T14:30, 2026-11-05 14:30:15.5, with
+    # Z or +hh:mm (UTC when absent). Plain Ruby, so the command line
+    # needs no require "time".
+    module IsoTime
+        FORM = /\A(\d{4})-(\d\d)-(\d\d)
+                (?:[T\ ](\d\d):(\d\d)(?::(\d\d(?:\.\d+)?))?)?
+                \s*(Z|[+-]\d\d:?\d\d)?\z/x
+
+        # The Time, or nil when text is not one of the forms above.
+        def self.parse(text)
+            m = FORM.match(text.strip) or return nil
+            date = m[1..5].map(&:to_i) + [m[6].to_f]
+            Time.new(*date, offset(m[7]))
+        rescue ArgumentError
+            nil
+        end
+
+        def self.offset(zone)
+            return "+00:00" if zone.nil? || zone == "Z"
+
+            zone.include?(":") ? zone : "#{zone[0, 3]}:#{zone[3, 2]}"
+        end
+    end
+end

data/lib/tessella/cli/lint.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Tessella
+    # `tessella lint` (DESIGN.md, "Lint"): checks text figures in files
+    # or stdin, as the ascii-art skill's scripts/artlint.rb did -- its
+    # options and output contract kept, --paranoid dropped (--ascii is
+    # the flag). Findings on stderr as NAME:LINE: message, --ruler rows
+    # on stdout; --alphabet prints NAME: ascii|utf-8 ... on stdout and
+    # lints nothing. Exit 0 clean (or --alphabet); 1 a finding, or a
+    # file that cannot be read; 2 usage.
+    class LintCLI
+        class UsageError < 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 lint [options] [file ...]  " \
+                 "(stdin if none)\n"
+
+        def self.run(argv, stdin:, stdout:, stderr:)
+            opts, mode, paths = Options.parse(argv.dup)
+            new(opts, stdout, stderr).run(mode, Inputs.list(paths, stdin))
+        rescue Halt => e
+            (e.status.zero? ? stdout : stderr).print(e.text)
+            e.status
+        rescue OptionParser::ParseError, UsageError, ArgumentError => e
+            stderr.puts("tessella lint: #{e.message}")
+            2
+        end
+
+        def initialize(opts, stdout, stderr)
+            @opts = opts
+            @stdout = stdout
+            @stderr = stderr
+        end
+
+        # Every input, in order; an unreadable one is named and the
+        # rest still linted.
+        def run(mode, inputs)
+            Tessella.lint("", **@opts) # an option's own value: usage
+            statuses = inputs.map do |name, read|
+                one(mode, name, read.call)
+            rescue SystemCallError => e
+                @stderr.puts("tessella lint: #{CLI.cannot_read(name, e)}")
+                1
+            end
+            statuses.max || 0
+        end
+
+        private
+
+        def one(mode, name, bytes)
+            return alphabet(name, bytes) if mode == :alphabet
+
+            report = Tessella.lint(bytes, **@opts.except(:ruler))
+            rulers(name, report) if @opts[:ruler]
+            report.findings.each do |f|
+                @stderr.puts("#{name}:#{f.line}: #{f.message}")
+            end
+            report.clean? ? 0 : 1
+        end
+
+        def alphabet(name, bytes)
+            @stdout.puts("#{name}: #{Tessella.alphabet(bytes)}")
+            0
+        end
+
+        def rulers(name, report)
+            report.rulers.each do |r|
+                tail = if r.verticals.empty?
+                           ""
+                       else
+                           "  verticals=" \
+                               "#{r.verticals.join(",")}"
+                       end
+                @stdout.puts("#{name}:#{r.line}: width=#{r.width}#{tail}")
+            end
+        end
+    end
+
+    # The inputs as [name, reader] pairs: each file by its path, or
+    # stdin named "stdin"; reading is deferred so an unreadable file
+    # fails alone.
+    class LintCLI
+        module Inputs
+            def self.list(paths, stdin)
+                return [["stdin", -> { stdin.binmode.read }]] if paths.empty?
+
+                paths.map { |path| [path, -> { File.binread(path) }] }
+            end
+        end
+    end
+end

data/lib/tessella/cli/lint_options.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Tessella
+    # Parses `tessella lint`'s argv into Tessella.lint's options (plus
+    # :ruler), the mode (:lint or :alphabet), and the file arguments.
+    # Raises Halt for --help; lets OptionParser::ParseError escape for
+    # a bad flag or a missing argument.
+    class LintCLI
+        class Options
+            def self.parse(argv)
+                new.parse(argv)
+            end
+
+            def initialize
+                @opts = { width: 78, prefix: "", suffix: "", ruler: false,
+                          forbid: [], borders: [] }
+                @mode = :lint
+                @parser = OptionParser.new
+                @parser.banner = LintCLI::BANNER
+                build
+            end
+
+            def parse(argv)
+                @parser.parse!(argv)
+                [@opts, @mode, argv]
+            end
+
+            private
+
+            def build
+                add_budget
+                add_forbid
+                add_glyph_flags
+                add_figure_flags
+                add_modes
+            end
+
+            def add_budget
+                @parser.on("--width N", Integer,
+                           "column budget (default 78)") { @opts[:width] = it }
+                @parser.on("--prefix STR", "string rendered before each line,",
+                           "charged to the budget") { @opts[:prefix] = it }
+                @parser.on("--suffix STR", "string rendered after each line,",
+                           "charged to the budget") { @opts[:suffix] = it }
+                @parser.on("--ruler", "print each line's width and the",
+                           "columns of its verticals") { @opts[:ruler] = true }
+            end
+
+            def add_forbid
+                presets = Lint::FORBID_PRESETS.keys.each_slice(5)
+                                              .map { "#{it.join(", ")}," }
+                presets[-1] = presets[-1].chomp(",")
+                @parser.on("--forbid SEQ", "flag lines holding SEQ, or a",
+                           "preset's sequences:", *presets) do |seq|
+                    @opts[:forbid] << seq
+                end
+            end
+
+            def add_glyph_flags
+                @parser.on("--target T", Target::TARGETS.map(&:to_s),
+                           "term (default), cjk: ambiguous glyphs 2",
+                           "columns, or web: as --web") do |t|
+                    @opts[:target] = t.to_sym
+                end
+                flag("--web", :web, "web-viewed target: flag emoji-capable",
+                     "glyphs, and wide glyphs on aligned rows")
+                flag("--no-wide", :no_wide, "flag wide (2-cell) glyphs")
+                flag("--ascii", :ascii, "flag every non-ASCII glyph",
+                     "(implies --no-wide)")
+            end
+
+            def add_figure_flags
+                flag("--allow-mixed", :allow_mixed, "skip the check for ASCII",
+                     "and Unicode structure mixed")
+                flag("--fences", :fences, "lint each Markdown fenced block",
+                     "on its own")
+                flag("--geometry", :geometry, "check box sides, and that",
+                     "connectors hang from something")
+                @parser.on("--border GLYPHS", "a custom border set geometry",
+                           "reads (6 glyphs: tl tr bl br h v)") do |set|
+                    @opts[:borders] << set
+                end
+            end
+
+            def add_modes
+                @parser.on("--alphabet", "print each input's alphabet (ascii,",
+                           "or utf-8 and its glyph classes);",
+                           "lint nothing, exit 0") { @mode = :alphabet }
+                @parser.on("--help", "print this help") do
+                    raise LintCLI::Halt.new(0, @parser.to_s)
+                end
+            end
+
+            def flag(name, key, *text)
+                @parser.on(name, *text) { @opts[key] = true }
+            end
+        end
+    end
+end

data/lib/tessella/cli/main.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Tessella
+    # The tessella command (DESIGN.md, "Command line"): `tessella
+    # COMMAND [options]`, one command per drawing module, each with its
+    # own options and --help. The command is the first argument, so a
+    # module's options never collide with another's.
+    class CLI
+        COMMANDS = {
+            "chart" => ChartCLI, "compose" => ComposeCLI, "tree" => TreeCLI,
+            "table" => TableCLI, "bitfield" => BitfieldCLI, "wave" => WaveCLI,
+            "seq" => SeqCLI, "image" => ImageCLI, "lint" => LintCLI,
+            "glyphs" => GlyphsCLI, "meter" => MeterCLI, "rule" => RuleCLI,
+            "text" => TextCLI, "sparkline" => SparklineCLI
+        }.freeze
+
+        USAGE = <<~TEXT
+            Usage: tessella [--target T] COMMAND [options] [file]
+
+            Commands:
+              chart     line, scatter, stairs, density, bar, histogram,
+                        box and stem charts
+              compose   frame, beside, stack, indent, caption: assemble
+                        blocks into one figure
+              tree      an indented outline as a box-drawing tree
+              table     CSV or TSV rows as a framed table
+              bitfield  an RFC-style packet / bit-field diagram
+              wave      a timing diagram from WaveDrom-like signals
+              seq       a sequence diagram from "A -> B: msg" lines
+              image     a picture as text: tones, blocks, braille, edges
+              lint      check text figures: tabs, widths, invisible
+                        glyphs, mixed or misaligned structure
+              glyphs    the named glyph sets and their width classes
+              meter     a one-line progress bar or gauge
+              rule      a divider line, with an optional ornament
+              text      text in a Unicode style: bold, script, small
+                        caps, circled, fullwidth, ...
+              sparkline one line of values, ▁ to █
+
+            --target term|cjk|web (or TESSELLA_TARGET) names where the
+            figure is read: term (default); cjk, a CJK terminal, whose
+            ambiguous glyphs (box drawing, blocks) are two columns, so
+            structure is ASCII; web, a browser, where emoji-capable
+            glyphs are kept as text with U+FE0E.
+
+            tessella COMMAND --help shows a command's options;
+            tessella --version prints the version.
+        TEXT
+
+        # A --target or TESSELLA_TARGET that names no target: usage.
+        class TargetError < ArgumentError; end
+
+        META = %w[--help -h --version].freeze
+
+        def self.run(argv, stdin:, stdout:, stderr:, env: ENV)
+            target, argv = target(argv, env)
+            command, *rest = argv
+            return meta(command, stdout) if META.include?(command)
+
+            klass = COMMANDS[command] or return refuse(command, stderr)
+            Target.with(target) do
+                klass.run(rest, stdin: stdin, stdout: stdout, stderr: stderr)
+            end
+        rescue TargetError => e
+            usage_error(e, stderr)
+        end
+
+        def self.usage_error(error, stderr)
+            stderr.puts("tessella: #{error.message}")
+            2
+        end
+
+        # A leading --target T (or --target=T), else TESSELLA_TARGET
+        # (set and not empty), else term -- checked before anything
+        # runs, --help and --version included; and the arguments after.
+        def self.target(argv, env)
+            name, rest = given_target(argv)
+            name ||= env["TESSELLA_TARGET"].to_s
+            [check_target!(name.empty? ? "term" : name), rest]
+        end
+
+        def self.given_target(argv)
+            first, *rest = argv
+            if first == "--target"
+                raise TargetError, "--target needs term, cjk or web" if
+                    rest.empty?
+
+                return [rest.first, rest.drop(1)]
+            end
+            return [first.delete_prefix("--target="), rest] if
+                first&.start_with?("--target=")
+
+            [nil, argv]
+        end
+
+        def self.check_target!(name)
+            Target.check!(name)
+        rescue ArgumentError => e
+            raise TargetError, e.message
+        end
+
+        def self.meta(flag, stdout)
+            stdout.print(flag == "--version" ? "#{VERSION}\n" : USAGE)
+            0
+        end
+
+        # A command's Halt (--help, --version, a usage message): its
+        # text on stdout when its status is 0, else on stderr.
+        def self.halt(error, stdout, stderr)
+            (error.status.zero? ? stdout : stderr).print(error.text)
+            error.status
+        end
+
+        def self.refuse(command, stderr)
+            what = command ? "unknown command: #{command}" : "no command"
+            stderr.puts("tessella: #{what}")
+            stderr.print(USAGE)
+            2
+        end
+    end
+end