r2ui 0.1.0 → 0.2.0

data/lib/r2ui/canvas.rb

@@ -14,6 +14,10 @@ module R2UI
   end
 
   # A grid of styled characters. Widgets draw into it; the terminal (or a snapshot) prints it.
+  #
+  # Cells hold Integer codepoints, so drawing text allocates nothing per character. Text in another
+  # encoding, or with invalid bytes, keeps its one-character Strings instead; both append to a line
+  # the same way (`String#<<`). The second cell of a wide character holds "" (prints nothing).
   class Canvas
     STYLES = {
       plain: "0", bold: "1", dim: "2", reverse: "7",
@@ -21,46 +25,163 @@ module R2UI
       ok: "32", warn: "33", alert: "31", accent: "35", muted: "90"
     }.freeze
 
+    SGR = /\A\e\[([0-9;:]*)m\z/
+    # SGR, any other escape sequence (CSI, OSC, two-byte; dropped), or a run of text.
+    TOKEN = /\e\[[0-9;:]*m|\e(?:\[[0-?]*[ -\/]*[@-~]|\][^\a\e]*(?:\a|\e\\)|[@-_])|[^\e]+|\e/
+    RESET = /\A0*\z/
+
+    SPACE = 32
+    WIDE_TAIL = ""
+    CODEPOINT_ENCODINGS = [Encoding::UTF_8, Encoding::US_ASCII].freeze
+    MEMO_LIMIT = 4096
+
+    # Memos of pure functions, shared by every canvas: cell width per codepoint (ANSI.string_width
+    # of that one character), and the "\e[0;...m" prefix per SGR String style and per named style
+    # of the default palette.
+    WIDTHS = {} # rubocop:disable Style/MutableConstant
+    STRING_PREFIXES = {} # rubocop:disable Style/MutableConstant
+    PALETTE_PREFIXES = {} # rubocop:disable Style/MutableConstant
+
+    def self.cell_width(cp)
+      return 1 if cp >= 0x20 && cp < 0x7F
+
+      WIDTHS[cp] ||= Compat::Tea::ANSI.string_width(cp.chr(Encoding::UTF_8))
+    end
+
     attr_reader :width, :height
 
-    def initialize(width, height)
+    # `styles` overrides or adds named styles ({ name => "SGR params" }).
+    def initialize(width, height, styles: nil)
       @width = width
       @height = height
-      @chars = Array.new(height) { Array.new(width, " ") }
+      @palette = styles ? STYLES.merge(styles) : STYLES
+      @prefixes = styles ? {} : PALETTE_PREFIXES
+      @chars = Array.new(height) { Array.new(width, SPACE) }
       @styles = Array.new(height) { Array.new(width, :plain) }
     end
 
+    # Writes one line of styled text (a lipgloss render, a bubbles view): its SGR colours are
+    # kept per cell, other escapes dropped. Wide characters take two cells. Returns the cells used.
+    def write_ansi(x, y, text, max: nil)
+      return 0 if y.negative? || y >= height
+
+      limit = [max || width, width - x].min
+      used = 0
+      sgr = nil
+      text.to_s.scan(TOKEN).each do |part|
+        if part.getbyte(0) == 27
+          if (m = part.match(SGR))
+            params = m[1]
+            sgr = params.match?(RESET) ? nil : (sgr ? "#{sgr};#{params}" : params)
+          end
+          next
+        end
+
+        style = sgr || :plain
+        if codepoints?(part)
+          part.each_codepoint do |cp|
+            w = Canvas.cell_width(cp)
+            next if w.zero?
+            return used if used + w > limit
+
+            put(x + used, y, cp, style)
+            put(x + used + 1, y, WIDE_TAIL, style) if w == 2
+            used += w
+          end
+        else
+          part.each_char do |ch|
+            w = Compat::Tea::ANSI.string_width(ch)
+            next if w.zero?
+            return used if used + w > limit
+
+            put(x + used, y, ch, style)
+            put(x + used + 1, y, WIDE_TAIL, style) if w == 2
+            used += w
+          end
+        end
+      end
+      used
+    end
+
     def write(x, y, text, style = :plain, max: nil)
       return if y.negative? || y >= height
 
-      limit = [max || width, width - x].min
-      text.to_s.each_char.first([limit, 0].max).each_with_index do |ch, i|
-        next if (x + i).negative?
+      count = [[max || width, width - x].min, 0].max.to_i
+      return if count.zero?
+
+      chars = @chars[y]
+      styles = @styles[y]
+      str = text.to_s
+      i = 0
+      cells = codepoints?(str) ? str.each_codepoint : str.each_char
+      cells.each do |cell|
+        break if i >= count
 
-        @chars[y][x + i] = ch
-        @styles[y][x + i] = style
+        unless (x + i).negative?
+          chars[x + i] = cell
+          styles[x + i] = style
+        end
+        i += 1
       end
+      nil
     end
 
     def fill(rect, char = " ", style = :plain)
       rect.height.times { |dy| write(rect.x, rect.y + dy, char * rect.width, style) }
     end
 
-    def plain_lines = @chars.map { |row| row.join.rstrip }
+    def plain_lines
+      @chars.map do |row|
+        line = String.new(capacity: row.size, encoding: Encoding::UTF_8)
+        row.each { |cell| line << cell }
+        line.rstrip!
+        line
+      end
+    end
 
     # ANSI for each line, so the terminal can redraw only lines that changed.
     def ansi_lines
-      @chars.each_index.map do |y|
-        out = +""
+      @chars.each_with_index.map do |row, y|
+        styles = @styles[y]
+        out = String.new(capacity: row.size * 4 + 128, encoding: Encoding::UTF_8)
         current = nil
-        @chars[y].each_with_index do |ch, x|
-          style = @styles[y][x]
-          out << "\e[0;#{STYLES.fetch(style)}m" if style != current
+        x = 0
+        n = row.size
+        while x < n
+          style = styles[x]
+          out << prefix(style) if style != current
           current = style
-          out << ch
+          out << row[x]
+          x += 1
         end
         out << "\e[0m"
       end
     end
+
+    private
+
+    # Text whose characters can be stored as Integer codepoints (appending one to a UTF-8 line
+    # gives the same bytes as appending the character).
+    def codepoints?(str) = CODEPOINT_ENCODINGS.include?(str.encoding) && str.valid_encoding?
+
+    def prefix(style)
+      if style.is_a?(String)
+        STRING_PREFIXES[style] || memo(STRING_PREFIXES, style, "\e[0;#{style}m")
+      else
+        @prefixes[style] || memo(@prefixes, style, "\e[0;#{@palette.fetch(style)}m")
+      end
+    end
+
+    def memo(hash, key, value)
+      hash.clear if hash.size >= MEMO_LIMIT
+      hash[key] = value.freeze
+    end
+
+    def put(x, y, ch, style)
+      return if x.negative? || x >= width
+
+      @chars[y][x] = ch
+      @styles[y][x] = style
+    end
   end
 end

data/lib/r2ui/cli/builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # The keywords inside `R2UI.cli do ... end` and `command :x do ... end`. Extensions add more
+    # with `dsl(:command) { def keyword ... end }`; inside them `definition` is the Command being
+    # built and `declare(key, value)` records plain data on it.
+    class Builder
+      attr_reader :definition
+
+      def initialize(definition)
+        @definition = definition
+      end
+
+      # One line, shown in the parent's command list and atop this command's help.
+      def summary(text) = definition.summary = text
+
+      # Longer text for this command's help (the summary when there is none).
+      def description(text) = definition.description = text
+
+      def option(name, type = :string, short: nil, default: nil, required: false, desc: nil, in: nil,
+                 many: false, placeholder: nil, hidden: false, **meta)
+        short = short&.to_s&.delete_prefix("-")
+        raise ArgumentError, "short option must be one character, got #{short.inspect}" if short && short.size != 1
+
+        choices = binding.local_variable_get(:in)
+        definition.add_option(Option.new(name: name.to_sym, type:, short:, default:, required:, desc:, choices:,
+                                         many:, placeholder:, hidden:, meta:))
+      end
+
+      # A boolean option (`--force`, `--no-force`).
+      def flag(name, short: nil, default: false, desc: nil, hidden: false, **meta)
+        option(name, :boolean, short:, default:, desc:, hidden:, **meta)
+      end
+
+      # A positional argument, in order. `default:` makes it optional.
+      def argument(name, type = :string, required: true, many: false, desc: nil, default: nil)
+        required = false unless default.nil?
+        definition.add_argument(Argument.new(name: name.to_sym, type:, required:, many:, desc:, default:))
+      end
+
+      # A subcommand; its block runs on a Builder for it, so commands nest
+      # (`command :db do command :migrate do ... end end`).
+      def command(name, summary = nil, hidden: false, &block)
+        sub = Command.new(name, parent: definition)
+        sub.summary = summary
+        sub.hidden = hidden
+        definition.add_command(sub)
+        Builder.new(sub).instance_exec(&block) if block
+        sub
+      end
+
+      # Other names the command answers to (`aliases :d, :ship`).
+      def aliases(*names) = definition.aliases.concat(names.map(&:to_s))
+
+      # What the command does. The block runs on a Context: `args`, `options`, every helper.
+      def run(&block)
+        raise ArgumentError, "run needs a block" unless block
+
+        definition.action = block
+      end
+
+      # Hides the command from its parent's command list (it still runs).
+      def hidden = definition.hidden = true
+
+      # For extensions: record plain data on the command (`definition.declared(key)` reads it).
+      def declare(key, value) = definition.declare(key, value)
+
+      def declared(key) = definition.declared(key)
+    end
+  end
+end

data/lib/r2ui/cli/context.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # What a command's `run` block (and every runner hook) runs on. Has the parsed input, the
+    # shell, every helper, and the ways out:
+    #
+    #   args[:app]            positional arguments by name
+    #   options[:env]         options by name (defaults filled in); given?(:env) if typed
+    #   abort!("msg", code: 1)   "✖ msg" on stderr, exit 1 (no message: just the exit code)
+    #   halt(0)               stop now, quietly, with that code
+    #   usage_error!("msg")   like a bad option: message, "--help" hint, exit 2
+    class Context
+      include Helpers
+
+      attr_reader :shell, :command, :options, :args, :argv
+
+      def initialize(shell:, command:, options: {}, args: {}, argv: [], given: [])
+        @shell = shell
+        @command = command
+        @options = options
+        @args = args
+        @argv = argv
+        @given = given
+        @stores = {}
+      end
+
+      def program = command.root
+
+      def given?(name) = @given.include?(name.to_sym)
+
+      def abort!(message = nil, code: 1) = raise(Abort.new(message, code:))
+
+      def halt(code = 0) = raise(Halt.new(code))
+
+      def usage_error!(message) = raise(UsageError, message)
+
+      # An extension's private Hash for this run.
+      def store(name) = @stores[name.to_sym] ||= {}
+
+      # Runs a user block here (so it sees args, options and the helpers).
+      def call(block, *args) = instance_exec(*args, &block)
+    end
+  end
+end

data/lib/r2ui/cli/definition.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module R2UI
+  module CLI
+    # Value types for options and arguments: a Symbol from TYPES, or anything with #call that
+    # turns the string into a value (raising ArgumentError/TypeError for a bad one).
+    TYPES = {
+      string: ->(s) { s },
+      integer: ->(s) { Integer(s, 10) },
+      float: ->(s) { Float(s) },
+      boolean: ->(s) { Option.boolean(s) },
+      path: ->(s) { File.expand_path(s) }
+    }.freeze
+
+    # A typed option. `--name value`, `--name=value`, `-n value`, `-nvalue`; booleans are
+    # `--name` / `--no-name` and cluster (`-vf`). `many: true` collects repeats into an Array.
+    # `default:` may be a lambda (called when the option isn't given: `-> { ENV["TOKEN"] }`).
+    # `meta` keeps any other keyword, for extensions (`option :token, secret: true`).
+    Option = Data.define(:name, :type, :short, :default, :required, :desc, :choices, :many,
+                         :placeholder, :hidden, :meta) do
+      def self.boolean(string)
+        case string.to_s.downcase
+        when "true", "yes", "y", "1", "on" then true
+        when "false", "no", "n", "0", "off" then false
+        else raise ArgumentError, "expects true or false"
+        end
+      end
+
+      def long = "--#{name.to_s.tr("_", "-")}"
+
+      def boolean? = type == :boolean
+
+      # The value name in help: `--env <env>`.
+      def value_name = placeholder || name.to_s.tr("_", "-")
+
+      def convert(string)
+        value = CLI.convert(type, string)
+        if choices && !choices.include?(value)
+          raise UsageError, "#{long} must be one of #{choices.join(", ")} (got #{string.inspect})"
+        end
+
+        value
+      rescue ArgumentError, TypeError => e
+        raise UsageError, "#{long} #{type_error(e)}, got #{string.inspect}"
+      end
+
+      def default_value
+        value = default.respond_to?(:call) ? default.call : default
+        value = convert(value) if value.is_a?(String) && type != :string && !type.respond_to?(:call)
+        many && value.nil? ? [] : value.dup
+      end
+
+      private
+
+      def type_error(error)
+        type.is_a?(Symbol) && type != :boolean ? "expects #{type == :integer ? "an" : "a"} #{type}" : error.message
+      end
+    end
+
+    # A positional argument. `many: true` (the last one only) takes the rest as an Array.
+    Argument = Data.define(:name, :type, :required, :many, :desc, :default) do
+      def usage
+        base = "#{name.to_s.tr("_", "-")}#{"..." if many}"
+        required ? "<#{base}>" : "[#{base}]"
+      end
+
+      def convert(string)
+        CLI.convert(type, string)
+      rescue ArgumentError, TypeError
+        raise UsageError, "<#{name}> expects #{type == :integer ? "an" : "a"} #{type}, got #{string.inspect}"
+      end
+    end
+
+    def self.convert(type, string)
+      converter = type.respond_to?(:call) ? type : TYPES.fetch(type) { raise ArgumentError, "unknown type #{type.inspect}" }
+      converter.call(string)
+    end
+
+    # One command: the root (the Program) or a subcommand. Plain data, built by Builder; nothing
+    # here parses or prints. `declared(key)` holds what extension keywords recorded.
+    class Command
+      attr_reader :name, :parent, :options, :arguments, :commands, :aliases, :declarations
+      attr_accessor :summary, :description, :action, :hidden
+
+      def initialize(name, parent: nil)
+        @name = name.to_s
+        @parent = parent
+        @options = []
+        @arguments = []
+        @commands = []
+        @aliases = []
+        @declarations = Hash.new { |h, k| h[k] = [] }
+        @hidden = false
+      end
+
+      def root? = parent.nil?
+
+      def root = root? ? self : parent.root
+
+      def group? = commands.any?
+
+      # ["deployer", "db", "migrate"]
+      def path = root? ? [name] : parent.path + [name]
+
+      def full_name = path.join(" ")
+
+      def declare(key, value)
+        @declarations[key.to_sym] << value
+        value
+      end
+
+      def declared(key) = @declarations.fetch(key.to_sym, [])
+
+      # The subcommand called `name` (or aliased so).
+      def find(name)
+        name = name.to_s
+        commands.find { |c| c.name == name || c.aliases.include?(name) }
+      end
+
+      # Options this command accepts: its own, then its ancestors' (a group's options apply to
+      # its whole subtree), nearest first.
+      def all_options = options + (root? ? [] : parent.all_options)
+
+      def option(name) = all_options.find { |o| o.name == name.to_sym }
+
+      def add_option(option)
+        taken = all_options.find { |o| o.name == option.name || (option.short && o.short == option.short) }
+        raise ArgumentError, "#{full_name}: option #{option.long} clashes with #{taken.long}" if taken
+        raise ArgumentError, "#{full_name}: -h is reserved for --help" if option.short == "h" || option.name == :help
+
+        @options << option
+        option
+      end
+
+      def add_argument(argument)
+        raise ArgumentError, "#{full_name}: only the last argument can be many: true" if arguments.last&.many
+        if argument.required && arguments.any? { |a| !a.required }
+          raise ArgumentError, "#{full_name}: required argument <#{argument.name}> after an optional one"
+        end
+
+        @arguments << argument
+        argument
+      end
+
+      def add_command(command)
+        raise ArgumentError, "#{full_name}: command #{command.name} is defined twice" if find(command.name)
+
+        @commands << command
+        command
+      end
+
+      def inspect = "#<#{self.class.name} #{full_name}>"
+    end
+
+    # The root command of a tool, plus how to run it.
+    class Program < Command
+      def self.build(name, &block)
+        program = new(name)
+        builder = Builder.new(program)
+        builder.instance_exec(&block) if block
+        Extensions.hooks(:setup).each { |hook| builder.instance_exec(&hook.block) }
+        program
+      end
+
+      # Runs argv and returns the exit code. Tests call this with a Shell on StringIOs.
+      def call(argv = ARGV, shell: CLI.shell) = Runner.new(self, shell:).call(argv)
+
+      # Runs argv and exits the process with the code.
+      def start(argv = ARGV, shell: CLI.shell) = exit(call(argv, shell:))
+    end
+  end
+end
+
+require_relative "builder"

data/lib/r2ui/cli/ext/ask.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# c17-ask: a line of text.
+#
+#   name = ask("Project name?")                                   # => "my-app"
+#   name = ask("Project name?", default: "app")                   # enter alone → "app"
+#   name = ask("Project name?", placeholder: "my-app",
+#              validate: ->(v) { "too short" if v.size < 2 })     # a String is the error message
+#
+# On a terminal (Shell#interactive?) it hosts bubbles' TextInput inline, like gum input:
+#
+#   ? Project name? › my-app▌                    the default (or `placeholder:`) shows muted
+#     ✖ too short                                 until something valid is typed
+#
+# enter submits (the default when nothing is typed); an answer `validate:` rejects keeps the prompt
+# open with its message under the field until the text is fixed. It leaves
+# "✔ Project name? · my-app" in the scrollback. ctrl+c or esc raises Interrupt (a command exits
+# 130) after the terminal is restored. Answers are stripped of surrounding spaces.
+#
+# Off a terminal it reads one line; an empty line or end of input means `default:`. When a person
+# can still type (stdin is a terminal, stdout piped) it asks "Project name? (app) " on stderr and
+# asks again after an answer `validate:` rejects. From a pipe (`echo web | tool`, CI) it doesn't
+# ask, records "✔ Project name? · web" on stderr, and a rejected answer is an error. End of input
+# with no default raises a CLI::Error naming the question.
+module R2UI
+  module CLI
+    module Ext
+      module Ask
+        # The inline prompt: bubbles' TextInput hosted on a Prompt::Model.
+        class Model < Prompt::Model
+          attr_reader :question, :default, :message
+
+          def initialize(shell, question, default: nil, placeholder: nil, validate: nil)
+            super(shell)
+            CLI.require_bubbles!
+            @question = question
+            @default = default
+            @validate = validate
+            @message = nil
+            input = Bubbles::TextInput.new
+            input.prompt = ""
+            input.placeholder = (placeholder || default).to_s
+            input.placeholder_style = shell.color? ? shell.theme.style(:muted) : Lipgloss::Style.new
+            input.width = [shell.width - Lipgloss.width(question) - 6, 10].max
+            @focus_command = input.focus
+            self.component = input
+          end
+
+          def init = [self, @focus_command]
+
+          # Re-checks after every edit once a message shows, so it goes away when the text is fixed.
+          def update(message)
+            result = super
+            @message = Ask.check(@validate, answer) if @message && !done?
+            result
+          end
+
+          def view
+            return "#{shell.symbol(:error)} #{question}" if interrupted?
+            return Ask.answered(shell, question, value) if done?
+
+            line = "#{shell.paint("?", :accent)} #{question} #{shell.paint(shell.theme.symbol(:pointer), :muted)} #{component.view}"
+            return line unless @message
+
+            "#{line}\n  #{shell.paint("#{shell.theme.symbol(:error)} #{@message}", :error)}"
+          end
+
+          private
+
+          def key(name, _message)
+            return nil unless name == "enter"
+
+            value = answer
+            @message = Ask.check(@validate, value)
+            return [self, nil] if @message
+
+            submit(value)
+          end
+
+          # What enter would submit now.
+          def answer
+            text = component.value.strip
+            text.empty? && !default.nil? ? default.to_s : text
+          end
+        end
+
+        module_function
+
+        def answered(shell, question, value)
+          "#{shell.symbol(:success)} #{question} #{shell.paint("·", :muted)} #{shell.paint(value, :accent)}"
+        end
+
+        # The validation message for `value`, or nil when it's fine (or there is no validator).
+        def check(validate, value)
+          return nil unless validate
+
+          result = validate.call(value)
+          result.is_a?(String) && !result.empty? ? result : nil
+        end
+
+        def ask_line(shell, question, default, validate)
+          hint = default.nil? || default.to_s.empty? ? "" : " (#{default})"
+          loop do
+            line = Prompt.read_line(shell, "#{question}#{hint} ")
+            raise Error, "no answer for #{question.inspect} (end of input); pass it as a command-line option, or run in a terminal" if line.nil? && default.nil?
+
+            value = line.to_s.strip
+            value = default.to_s if value.empty? && !default.nil?
+            message = check(validate, value)
+            if message.nil?
+              shell.err_puts("#{shell.symbol(:success)} #{question} · #{value}") unless shell.input_tty?
+              return value
+            end
+            raise Error, "invalid answer for #{question.inspect}: #{message} (got #{value.inspect})" if line.nil? || !shell.input_tty?
+
+            shell.err_puts("#{shell.symbol(:error)} #{message}")
+          end
+        end
+      end
+    end
+
+    extension :ask do
+      helpers do
+        def ask(question, default: nil, placeholder: nil, validate: nil)
+          return Ext::Ask.ask_line(shell, question, default, validate) unless shell.interactive?
+
+          model = Ext::Ask::Model.new(shell, question, default:, placeholder:, validate:)
+          Prompt.run(shell, model).value
+        end
+      end
+    end
+  end
+end