libtmux 0.1.0.alpha.1

data/lib/libtmux/entity.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module LibTmux
+  # IDs printed by the creation command itself, before later topology changes.
+  # A receipt proves creation, not continued ownership or current membership.
+  class CreationReceipt
+    attr_reader :entity, :window, :pane, :result
+
+    def initialize(entity:, window:, pane:, result:)
+      @entity, @window, @pane, @result = entity, window, pane, result
+      freeze
+    end
+    private_class_method :new
+
+    def inspect
+      "#<#{self.class} entity=#{entity.id} window=#{window.id} pane=#{pane.id}>"
+    end
+  end
+
+  # A target belongs to one open server binding; names never identify it.
+  class EntityRef
+    attr_reader :binding_key, :kind, :id, :session_id, :index
+
+    def initialize(binding_key:, kind:, id:, session_id: nil, index: nil)
+      prefix = {session: "$", window: "@", pane: "%", window_link: "@"}.fetch(kind)
+      unless id.is_a?(String) && id.match?(/\A#{Regexp.escape(prefix)}\d+\z/)
+        raise ProtocolError.new("tmux returned an invalid #{kind} ID", delivery: :observed, phase: :decode)
+      end
+      @binding_key = binding_key.dup.freeze
+      @kind = kind
+      @id = id.dup.freeze
+      if kind == :window_link
+        unless session_id.is_a?(String) && session_id.match?(/\A\$\d+\z/) && index.is_a?(Integer) && index >= 0
+          raise ProtocolError.new("tmux returned invalid window link context", delivery: :observed, phase: :decode)
+        end
+        @session_id = session_id.dup.freeze
+        @index = index
+      elsif session_id || index
+        raise ArgumentError, "only window links have session and index context"
+      end
+      freeze
+    end
+    private_class_method :new
+
+    def ==(other)
+      other.is_a?(EntityRef) && [binding_key, kind, id, session_id, index] ==
+        [other.binding_key, other.kind, other.id, other.session_id, other.index]
+    end
+    alias eql? ==
+
+    def hash
+      [binding_key, kind, id, session_id, index].hash
+    end
+
+    def inspect
+      "#<#{self.class} #{kind} #{id}>"
+    end
+  end
+
+  class Entity
+    attr_reader :server, :ref
+
+    def initialize(server, ref)
+      @server = server
+      @ref = ref
+      freeze
+    end
+    private_class_method :new
+
+    def id
+      ref.id
+    end
+
+    def snapshot(**options)
+      server.snapshot(**options).resolve(ref)
+    end
+
+    def ==(other)
+      other.is_a?(Entity) && ref == other.ref
+    end
+    alias eql? ==
+
+    def hash
+      ref.hash
+    end
+
+    def kill(timeout: 5.0, cancel: nil)
+      server.__send__(:execute_typed, ["kill-#{ref.kind}", "-t", target], timeout: timeout, cancel: cancel)
+    end
+
+    def inspect
+      "#<#{self.class} #{id}>"
+    end
+
+    private
+
+    def target
+      server.__send__(:target, ref, ref.kind)
+    end
+  end
+
+  class Session < Entity
+    def new_window(name:, command:, index: nil, cwd: nil, environment: {}, focus: false, receipt: false, timeout: 5.0, cancel: nil)
+      server.__send__(:create_window, ref, name: name, command: command, index: index,
+        cwd: cwd, environment: environment, focus: focus, receipt: receipt, timeout: timeout, cancel: cancel)
+    end
+
+    def list_windows(timeout: 5.0, cancel: nil)
+      server.__send__(:list_entities, :window, ["-t", target], timeout: timeout, cancel: cancel)
+    end
+
+    def list_panes(timeout: 5.0, cancel: nil)
+      server.__send__(:list_entities, :pane, ["-s", "-t", target], timeout: timeout, cancel: cancel)
+    end
+  end
+
+  class Window < Entity
+    LAYOUTS = %w[even-horizontal even-vertical main-horizontal main-vertical tiled].freeze
+    MIRRORED_LAYOUTS = %w[main-horizontal-mirrored main-vertical-mirrored].freeze
+    private_constant :LAYOUTS, :MIRRORED_LAYOUTS
+
+    def list_panes(timeout: 5.0, cancel: nil)
+      server.__send__(:list_entities, :pane, ["-t", target], timeout: timeout, cancel: cancel)
+    end
+
+    def split(direction:, command:, size: nil, cwd: nil, environment: {}, focus: false, timeout: 5.0, cancel: nil)
+      server.__send__(:split_window, ref, direction: direction, command: command, size: size,
+        cwd: cwd, environment: environment, focus: focus, timeout: timeout, cancel: cancel)
+    end
+
+    def select_layout(layout, timeout: 5.0, cancel: nil)
+      unless layout.is_a?(String) || layout.is_a?(Symbol)
+        raise ArgumentError, "layout must be a String or Symbol"
+      end
+      value = layout.is_a?(Symbol) ? layout.to_s.tr("_", "-") : layout
+      budget = server.__send__(:operation_budget, timeout, cancel)
+      # Older tmux can access an invalid pointer for a malformed layout header.
+      unless LAYOUTS.include?(value) || /\A[0-9a-fA-F]{4},/.match?(value)
+        choices = (LAYOUTS + MIRRORED_LAYOUTS).select { |name| name.start_with?(value) }
+        raise ArgumentError, "layout must be a native name or a saved layout" if value.empty? || choices.empty?
+
+        if choices.any? { |name| MIRRORED_LAYOUTS.include?(name) }
+          version = server.display('#{version}', **budget.options).text
+          release = /\A(\d+)\.(\d+)/.match(version)
+          raise ProtocolError.new("tmux version is invalid", phase: :decode, delivery: :observed) unless release
+
+          if ([release[1].to_i, release[2].to_i] <=> [3, 5]).negative?
+            choices &= LAYOUTS
+            if choices.empty?
+              raise UnsupportedFeatureError.new("mirrored layouts require tmux 3.5+", phase: :admission)
+            end
+          end
+        end
+        choices = [value] if choices.include?(value)
+        raise ArgumentError, "layout name is ambiguous" unless choices.length == 1
+
+        value = choices.first
+      end
+      server.__send__(:execute_typed, ["select-layout", "-t", target, "--", value], **budget.options)
+    end
+  end
+
+  class Pane < Entity
+    def split(direction:, command:, size: nil, cwd: nil, environment: {}, focus: false, timeout: 5.0, cancel: nil)
+      server.__send__(:split_window, ref, direction: direction, command: command, size: size,
+        cwd: cwd, environment: environment, focus: focus, timeout: timeout, cancel: cancel)
+    end
+
+    def capture(start: nil, finish: nil, join: false, escapes: false, escape_bytes: false, preserve_trailing: false,
+      trim_trailing: false, alternate: false, mode_screen: false, pending: false, timeout: 5.0, cancel: nil)
+      budget = server.__send__(:operation_budget, timeout, cancel)
+      if [alternate, mode_screen, pending].count { |value| value } > 1
+        raise ArgumentError, "alternate, mode_screen and pending captures are mutually exclusive"
+      end
+      arguments = ["capture-pane", "-p", "-t", target]
+      {"-S" => start, "-E" => finish}.each do |flag, value|
+        next if value.nil?
+        raise ArgumentError, "capture ranges must be integers or '-'" unless value.is_a?(Integer) || value == "-"
+
+        arguments.concat([flag, value.to_s])
+      end
+      {"T" => trim_trailing, "M" => mode_screen}.each do |flag, enabled|
+        next unless enabled
+
+        server.__send__(:require_command_flag, "capture-pane", flag, budget: budget)
+        arguments << "-#{flag}"
+      end
+      {"-J" => join, "-e" => escapes, "-C" => escape_bytes, "-N" => preserve_trailing,
+        "-a" => alternate, "-P" => pending}.each { |flag, enabled| arguments << flag if enabled }
+      server.__send__(:execute_typed, arguments, **budget.options)
+    end
+
+    def send_text(text, timeout: 5.0, cancel: nil)
+      raise ArgumentError, "text must be a String" unless text.is_a?(String)
+
+      server.__send__(:execute_typed, ["send-keys", "-l", "-t", target, "--", text], timeout: timeout, cancel: cancel)
+    end
+
+    def send_keys(*keys, timeout: 5.0, cancel: nil)
+      raise ArgumentError, "provide at least one key name" if keys.empty?
+
+      server.__send__(:execute_typed, ["send-keys", "-t", target, "--", *keys], timeout: timeout, cancel: cancel)
+    end
+  end
+
+  class WindowLink < Entity
+    def index
+      ref.index
+    end
+
+    def window
+      server.__send__(:build_entity, :window, id)
+    end
+
+    def session
+      server.__send__(:build_entity, :session, ref.session_id)
+    end
+
+    def select(timeout: 5.0, cancel: nil)
+      server.__send__(:execute_link, [ref], "select-window", ["-t", context], timeout: timeout, cancel: cancel)
+    end
+
+    def unlink(force: false, timeout: 5.0, cancel: nil)
+      server.__send__(:execute_link, [ref], "unlink-window", [*(force ? ["-k"] : []), "-t", context], timeout: timeout, cancel: cancel)
+    end
+
+    def kill(timeout: 5.0, cancel: nil)
+      server.__send__(:execute_link, [ref], "kill-window", ["-t", context], timeout: timeout, cancel: cancel)
+    end
+
+    def move(session:, index:, timeout: 5.0, cancel: nil)
+      raise ArgumentError, "index must be a nonnegative Integer" unless index.is_a?(Integer) && index >= 0
+
+      destination = server.__send__(:target, session, :session)
+      server.__send__(:execute_link, [ref], "move-window", ["-d", "-s", context, "-t", "#{destination}:#{index}"], timeout: timeout, cancel: cancel)
+    end
+
+    def swap(other, timeout: 5.0, cancel: nil)
+      server.__send__(:target, other, :window_link)
+      server.__send__(:execute_link, [ref, other], "swap-window",
+        ["-d", "-s", context, "-t", "#{other.session_id}:#{other.index}"], timeout: timeout, cancel: cancel)
+    end
+
+    def display(format, timeout: 5.0, cancel: nil)
+      server.__send__(:execute_link, [ref], "display-message", ["-p", "-t", context, "--", format], timeout: timeout, cancel: cancel)
+    end
+
+    def options
+      raise UnsupportedFeatureError.new("link-scoped options are not implemented; use an explicit window handle", phase: :admission)
+    end
+
+    def hooks
+      raise UnsupportedFeatureError.new("link-scoped hooks are not implemented; use an explicit window handle", phase: :admission)
+    end
+
+    private
+
+    def context
+      "#{ref.session_id}:#{ref.index}"
+    end
+  end
+end

data/lib/libtmux/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module LibTmux
+  class Error < StandardError
+    attr_reader :delivery, :phase, :pid, :cleanup_errors, :entity, :path, :expected
+
+    def initialize(message, delivery: :not_sent, phase: nil, pid: nil, cleanup_errors: [], entity: nil, path: nil, expected: nil)
+      super(message)
+      @delivery = delivery
+      @phase = phase
+      @pid = pid
+      @cleanup_errors = cleanup_errors.dup.freeze
+      @entity = entity
+      @path = path&.dup&.freeze
+      @expected = expected&.dup&.freeze
+    end
+
+    private
+
+    def attach_cleanup_errors(errors)
+      @cleanup_errors = (@cleanup_errors + errors).freeze
+    end
+  end
+
+  class InvalidFilterError < Error
+    def initialize(message = "invalid filter", entity: nil, path: "$", expected: nil, **details)
+      super("#{message} at #{path}#{expected ? "; expected #{expected}" : ""}",
+        entity: entity, path: path, expected: expected, **details)
+    end
+  end
+  class IncompleteSnapshotError < Error; end
+  class InconsistentSnapshotError < Error; end
+  class NoMatchError < Error; end
+  class MultipleMatchesError < Error; end
+  class TargetNotFoundError < Error; end
+  class FieldDecodeError < Error; end
+  class UnsupportedFeatureError < Error; end
+  class TransportError < Error; end
+  class ProtocolError < Error; end
+  class CapacityError < Error; end
+  class DeadlineExceeded < Error; end
+  class Cancelled < Error; end
+  class OutcomeUnknown < Error; end
+  class ClosedError < Error; end
+
+  class CommandError < Error
+    attr_reader :result
+
+    def initialize(message = "tmux command failed", result: nil, **details)
+      @result = result
+      super(message, **{delivery: result&.delivery || :not_sent, pid: result&.pid}.merge(details))
+    end
+  end
+end

data/lib/libtmux/group.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "server"
+
+module LibTmux
+  # Final client status cannot attribute a merged group result to individual steps.
+  class GroupResult
+    attr_reader :result, :steps
+
+    def initialize(result, count)
+      @result = result
+      @steps = Array.new(count) { |index| {index: index, outcome: :unknown}.freeze }.freeze
+      freeze
+    end
+    private_class_method :new
+
+    def success?
+      result.success?
+    end
+
+    def delivery
+      result.delivery
+    end
+
+    def inspect
+      "#<#{self.class} commands=#{steps.size} client_success=#{success?} delivery=#{delivery}>"
+    end
+  end
+
+  class Server
+    # One nontransactional tmux command group, with literal arguments per command.
+    def run_group(commands, input: "".b, timeout: 5.0, cancel: nil)
+      started = monotonic
+      unless timeout.is_a?(Numeric) && timeout.finite?
+        raise ArgumentError, "group timeout must be finite"
+      end
+      unless commands.is_a?(Array) && !commands.empty?
+        raise ArgumentError, "commands must be a nonempty Array of argument Arrays"
+      end
+      if commands.length > 128
+        raise CapacityError.new("command group exceeds 128 members", phase: :admission)
+      end
+      encoded = commands.map do |command|
+        validate_argv(command)
+        if command.first.start_with?("-")
+          raise ArgumentError, "group members cannot override endpoint flags"
+        end
+        encode_arguments(command)
+      end
+      argv = []
+      encoded.each_with_index do |command, index|
+        argv << ";" unless index.zero?
+        argv.concat(command)
+      end
+      result = run(argv, input: input, timeout: timeout - (monotonic - started), cancel: cancel)
+      GroupResult.__send__(:new, result, encoded.length)
+    end
+  end
+end

data/lib/libtmux/metadata.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module LibTmux
+  module Internal
+    module Metadata
+      module_function
+
+      def format(fields)
+        fields.map { |field| "\#{n:#{field}}:\#{q:#{field}}" }.join
+      end
+
+      # q doubles literal backslashes before tmux 3.5's VIS_NOSLASH output
+      # escaping. Decode that transport layer before using original byte lengths.
+      def unquote(value)
+        escapes = {"a" => "\a", "b" => "\b", "t" => "\t", "n" => "\n", "v" => "\v",
+          "f" => "\f", "r" => "\r", "s" => " ", "E" => "\e"}
+        value.b.gsub(/\\([0-7]{3}|.)/n) do
+          escaped = Regexp.last_match(1)
+          if escaped.match?(/\A[0-7]{3}\z/)
+            byte = escaped.to_i(8)
+            protocol_error("invalid metadata byte escape") if byte > 255
+            byte.chr(Encoding::BINARY)
+          else
+            escapes.fetch(escaped, escaped)
+          end
+        end
+      end
+
+      def decode(bytes, fields:, max_field_bytes: 1 << 20, max_bytes: 1 << 20, max_rows: 10_000, quoted: false)
+        unless bytes.is_a?(String) && fields.is_a?(Integer) && fields.between?(1, 64)
+          raise ArgumentError, "metadata requires String bytes and between 1 and 64 fields"
+        end
+        unless [max_field_bytes, max_bytes, max_rows].all? { |limit| limit.is_a?(Integer) && limit.positive? }
+          raise ArgumentError, "metadata limits must be positive integers"
+        end
+        capacity_error("metadata output exceeds its byte limit") if bytes.bytesize > max_bytes
+
+        bytes = quoted ? unquote(bytes) : bytes.b
+        rows = []
+        offset = 0
+        while offset < bytes.bytesize
+          capacity_error("metadata exceeds its row limit") if rows.length >= max_rows
+          row = Array.new(fields) do
+            length = 0
+            digits = 0
+            loop do
+              byte = bytes.getbyte(offset)
+              if byte == 58 && digits.positive?
+                offset += 1
+                break
+              end
+              unless byte && byte.between?(48, 57) && digits < 9
+                protocol_error("invalid metadata length prefix")
+              end
+              length = length * 10 + byte - 48
+              digits += 1
+              offset += 1
+            end
+            capacity_error("metadata field exceeds its byte limit") if length > max_field_bytes
+            protocol_error("truncated metadata field") if offset + length > bytes.bytesize
+            value = bytes.byteslice(offset, length).freeze
+            offset += length
+            value
+          end
+          protocol_error("missing metadata row terminator") unless bytes.getbyte(offset) == 10
+          offset += 1
+          rows << row.freeze
+        end
+        rows.freeze
+      end
+
+      def protocol_error(message)
+        raise ProtocolError.new(message, delivery: :observed, phase: :decode)
+      end
+      private_class_method :protocol_error
+
+      def capacity_error(message)
+        raise CapacityError.new(message, delivery: :observed, phase: :decode)
+      end
+      private_class_method :capacity_error
+    end
+  end
+end