libtmux 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79156b66bcf107fc6cb87a8c8eee64b72a87fee01297547d7ae1c1fc00f78eda
-  data.tar.gz: dbc00e2cc431568ed740fb97abe0e2183d8179d855f06331692c201304cb8fd0
+  metadata.gz: e121eada829f9816c2d77a1910ae0ff9c473bb10539250a80a732156d7cf2804
+  data.tar.gz: 725a646a69288b57ec37d9ded5f02444d40ac8968419bf0470706d2d3ec5505d
 SHA512:
-  metadata.gz: f3452f20558e34c94ed20ff6556f2224f2ed2f60025ad5f85bcedaba71bce596fdb22f1df3a0dc20cbd5056500884c075cc6c3d88ffcd0629e5d90b5fdde050f
-  data.tar.gz: e636d17486684ade7616fa70f59c8b64766d5e096f388c8047b939875651a21e21095cdd79f4f35a3221b31d59ef06ed69aad5719e29d4cd28781cbc12d337c5
+  metadata.gz: 062be2f34e7a702808bc822350dca3bca1ef456957aab5f0885b069c518ce68b3bcfb3914b758ff1607ed98b25edef72c560e6c28ce79a5ef09ca566389261bd
+  data.tar.gz: 0f2434316cd39f28f75618aa47b5fe3bb122f1dcec91017d256df182fcd564801602be30c7d84d803a3d4fa829a4af632fab3b5ff315f45f6ba3f29399788236

data/README.md

@@ -19,6 +19,9 @@ as handles, [snapshots][snapshot] you filter in plain Ruby, and
 [Guides](https://libtmux.org/en/ruby/latest/guides/) ·
 [RubyGems](https://rubygems.org/gems/libtmux)
 
+[![libtmux.org](https://img.shields.io/badge/docs-libtmux.org-0b7285)](https://libtmux.org/en/ruby/)
+[![libtmux](https://img.shields.io/gem/v/libtmux?label=libtmux)](https://rubygems.org/gems/libtmux)
+
 </div>
 
 Part of [libtmux for Ruby](https://github.com/libtmux/libtmux-ruby#readme).
@@ -338,8 +341,10 @@ connected sessions: 1
 sessions after client close: 1
 ```
 
-- [`Endpoint.new`][endpoint-new] takes an explicit socket path or socket name.
-  [`Endpoint.from_env`][endpoint-from_env] is the opt-in for `$TMUX`.
+- [`Endpoint.new`][endpoint-new] takes a socket path or socket name. With
+  neither, it picks the socket tmux would: `LIBTMUX_SOCKET_PATH`,
+  `LIBTMUX_SOCKET`, the server `$TMUX` names, then tmux's default socket.
+  [`Endpoint.from_env`][endpoint-from_env] follows `$TMUX` alone.
 - A binding keeps a private link to the socket it bound, so commands never
   reach a different daemon that later takes the same path.
 - A ref is valid on the server that issued it. Another server raises
@@ -708,8 +713,11 @@ server and lists every option.
   [Live handles][behavior-live-handles].
 - **A terminal emulator.** [`Pane#capture`][pane-capture] returns the bytes
   tmux holds for the screen, with the flags above to shape them.
-- **An implied server.** [`Endpoint.new`][endpoint-new] needs an explicit
-  socket, and no API in the recipes uses the default server.
+- **A server it starts on its own.** [`Server.new`][server-new] and
+  [`Server.open`][server-open] bind a running server and never start one. With
+  no socket named, [`Endpoint.new`][endpoint-new] picks the one tmux would:
+  `LIBTMUX_SOCKET_PATH`, `LIBTMUX_SOCKET`, the server `TMUX` names, then tmux's
+  default socket. The recipes name a socket or own one.
 - **Replay.** A reconnected control connection reports a gap and never replays
   requests or missed output. See [Control flow][behavior-control-flow].
 - **Transactions.** A [group][server-run_group] runs in order and keeps the
@@ -735,10 +743,11 @@ See the [changelog](../../CHANGELOG.md).
   [optional feature table](../../docs/reference/behavior.md#optional-tmux-features)
   lists the other per-release requirements.
 - **Linux, including WSL, and macOS.** The [compatibility workflow][compat]
-  runs Ruby 3.3, 3.4 and 4.0 with tmux 3.3a through 3.8 on Ubuntu 24.04.
-  macOS is supported on a best-effort basis, and CI coverage for it is highly
+  runs Ruby 3.3, 3.4 and 4.0 with tmux 3.3a through 3.8 on Ubuntu 24.04. A push
+  and a pull request run the oldest and newest of those releases, 3.3a and 3.8,
+  and a release runs all of them. macOS is supported on a best-effort basis, and CI coverage for it is highly
   limited.
-- **tmux master and old daemons.** On Ubuntu the workflow also runs the suite
+- **tmux master and old daemons.** On Ubuntu a release also runs the suite
   against a pinned tmux master, and checks that tmux 3.0a, 3.1c, 3.2a and 3.3
   daemons are refused.
 - **Per-revision results.** Read the workflow's results for your revision

data/lib/libtmux/capabilities.rb

@@ -91,10 +91,10 @@ module LibTmux
           summary: "Apply main-horizontal-mirrored and main-vertical-mirrored.",
           apis: ["LibTmux::Window#select_layout"],
           commands: [Command.new(command: "select-layout")]),
-        Capability.new(id: "layout-json", name: "JSON layout strings", since: "3.8-rc2",
+        Capability.new(id: "layout-json", name: "JSON layout strings", since: "3.8",
           handling: :refuse, error: ERROR,
           summary: "Apply a layout saved in the JSON form tmux reports.",
-          apis: ["LibTmux::Window#select_layout"],
+          apis: ["LibTmux::Window#select_layout", "LibTmux::Server#run", "LibTmux::ControlConnection#exchange"],
           commands: [Command.new(command: "select-layout")]),
         Capability.new(id: "clipboard-query", name: "Clipboard query", since: "3.6a", handling: :refuse, error: ERROR,
           summary: "Ask an attached client's terminal for its clipboard with refresh-client -l.",

data/lib/libtmux/endpoint.rb

@@ -5,38 +5,52 @@ require "securerandom"
 require_relative "errors"
 
 module LibTmux
-  # Explicit executable and socket selection. Construction starts no clients.
+  # Executable and socket selection. Construction starts no clients.
+  #
+  # {#initialize Endpoint.new} takes a `socket_path:` or a `socket_name:`.
+  # With neither, it picks the socket as tmux does when it is given none, and
+  # `environment:` (the process environment by default) decides which: the
+  # path in `LIBTMUX_SOCKET_PATH`, else the name in `LIBTMUX_SOCKET`, else the
+  # socket `TMUX` names when run inside tmux, else tmux's `default` socket. A
+  # variable that is empty counts as unset, and a socket given as an argument
+  # ignores the variables. {.from_env} skips the `LIBTMUX_*` variables.
   class Endpoint
     attr_reader :executable, :socket_path
 
-    def initialize(socket_path: nil, socket_name: nil, executable: "tmux", socket_directory: nil)
-      unless [socket_path, socket_name].count { |value| !value.nil? } == 1
-        raise ArgumentError, "choose exactly one socket_path or socket_name"
+    def initialize(socket_path: nil, socket_name: nil, executable: "tmux", socket_directory: nil, environment: ENV)
+      unless socket_path.nil? || socket_name.nil?
+        raise ArgumentError, "choose at most one socket_path or socket_name"
+      end
+      origin = path_label = nil
+      if socket_path.nil? && socket_name.nil?
+        raise ArgumentError, "socket_directory applies only to socket_name" if socket_directory
+        socket_path, socket_name, origin = Internal::SocketChoice.call(environment)
       end
       if socket_name
-        validate_string(socket_name, "socket_name")
+        label = origin || "socket_name"
+        validate_string(socket_name, label)
         if socket_name.include?("/") || [".", ".."].include?(socket_name)
-          raise ArgumentError, "socket_name must be a single filename"
+          raise ArgumentError, "#{label} must be a single filename"
         end
-        directory = socket_directory || ENV["TMUX_TMPDIR"] || "/tmp"
+        directory = socket_directory || Internal::SocketChoice.present(environment["TMUX_TMPDIR"]) || "/tmp"
         validate_string(directory, "socket_directory")
+        path_label = socket_directory ? "socket_directory" : "TMUX_TMPDIR"
         socket_path = File.join(directory, "tmux-#{Process.uid}", socket_name)
       elsif socket_directory
         raise ArgumentError, "socket_directory applies only to socket_name"
       end
-      validate_string(socket_path, "socket_path")
+      validate_string(socket_path, origin || "socket_path")
       validate_string(executable, "executable")
-      @socket_path = File.expand_path(socket_path).freeze
+      @socket_path = expand(socket_path, path_label || origin || "socket_path").freeze
       @executable = resolve_executable(executable).freeze
       freeze
     end
 
+    # The socket of the tmux server this process runs inside, else tmux's
+    # `default` socket. It ignores `LIBTMUX_SOCKET_PATH` and `LIBTMUX_SOCKET`.
     def self.from_env(env = ENV, **options)
-      if env["TMUX"] && !env["TMUX"].empty?
-        new(socket_path: env["TMUX"].split(",", 3).first, **options)
-      else
-        new(socket_name: "default", socket_directory: env["TMUX_TMPDIR"], **options)
-      end
+      socket_path, socket_name = Internal::SocketChoice.tmux(env)
+      new(socket_path: socket_path, socket_name: socket_name, environment: env, **options)
     end
 
     def ==(other)
@@ -49,11 +63,19 @@ module LibTmux
     end
 
     def inspect
-      "#<#{self.class} explicit Unix socket>"
+      "#<#{self.class} Unix socket>"
     end
 
     private
 
+    # File.expand_path puts the user it cannot find in its message, so the
+    # message here names the argument or variable instead.
+    def expand(path, label, base = nil)
+      base ? File.expand_path(path, base) : File.expand_path(path)
+    rescue ArgumentError
+      raise ArgumentError, "#{label} cannot be expanded to a path; its leading ~ names no home directory"
+    end
+
     def validate_string(value, name)
       unless value.is_a?(String) && !value.empty? && !value.include?("\0")
         raise ArgumentError, "#{name} must be a nonempty String without NUL"
@@ -62,10 +84,10 @@ module LibTmux
 
     def resolve_executable(value)
       candidates = if value.include?(File::SEPARATOR)
-        [File.expand_path(value)]
+        [expand(value, "executable")]
       else
         ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map do |directory|
-          File.expand_path(value, directory.empty? ? Dir.pwd : directory)
+          expand(value, "executable", directory.empty? ? Dir.pwd : directory)
         end
       end
       candidates.find { |path| File.file?(path) && File.executable?(path) } ||
@@ -74,6 +96,37 @@ module LibTmux
   end
 
   module Internal
+    # Picks the socket tmux would use if it were given neither -S nor -L, from
+    # the variables that stand for them and the ones tmux reads itself: -S
+    # beats -L, and -L beats TMUX. Each pick is [path, name, variable], with
+    # the variable named so that a bad value is reported by name.
+    module SocketChoice
+      module_function
+
+      def call(environment)
+        if (path = present(environment["LIBTMUX_SOCKET_PATH"]))
+          [path, nil, "LIBTMUX_SOCKET_PATH"]
+        elsif (name = present(environment["LIBTMUX_SOCKET"]))
+          [nil, name, "LIBTMUX_SOCKET"]
+        else
+          tmux(environment)
+        end
+      end
+
+      # tmux ignores a TMUX that is empty or starts with a comma, and takes
+      # the socket path before the first comma of one that does not.
+      def tmux(environment)
+        inside = present(environment["TMUX"])
+        return [nil, "default", nil] if inside.nil? || inside.start_with?(",")
+
+        [inside.split(",", 2).first, nil, "TMUX"]
+      end
+
+      def present(value)
+        value if value.is_a?(String) && !value.empty?
+      end
+    end
+
     # Keep the socket inode alive and route through it; PID timestamps can repeat.
     class SocketIdentity
       attr_reader :key, :release

data/lib/libtmux/entity.rb

@@ -135,7 +135,7 @@ module LibTmux
       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.
-      # tmux 3.8-rc2 and later report and accept saved layouts as JSON.
+      # tmux 3.8 and later report and accept saved layouts as JSON.
       saved = /\A[0-9a-fA-F]{4},/.match?(value)
       if !saved && value.start_with?("{")
         json = Internal::Capabilities.capability("layout-json")

data/lib/libtmux/native_guard.rb

@@ -317,11 +317,17 @@ module LibTmux
       end
 
       # tmux 3.3a faults on a header that is not four hex digits and a comma, so
-      # only checksummed layouts and built-in names pass before 3.4.
+      # only checksummed layouts and built-in names pass before 3.4. A JSON layout
+      # needs tmux 3.8.
       def check_layout(item, command, release)
+        given = flags(item, command)
+        json = Internal::Capabilities.capability("layout-json")
+        if !json.available?(release) && operands(item, command).first.to_s.start_with?("{") && given.slice("E", "n", "p").empty?
+          raise UnsupportedFeatureError.new("JSON layouts require tmux #{json.since} or newer " \
+            "(connected version #{release.text})", phase: :admission, delivery: :not_sent)
+        end
         return if Internal::Capabilities.capability("layout-without-checksum").available?(release)
 
-        given = flags(item, command)
         return if given.key?("E") || given.key?("n") || given.key?("p")
 
         layout = operands(item, command).first

data/lib/libtmux/server.rb

@@ -32,7 +32,10 @@ module LibTmux
   #
   # **Connecting.** {#initialize Server.new} and {Server.open} bind an endpoint
   # that already exists; {Server.open} with a block closes the server when the
-  # block ends. {Server.start} starts a private daemon instead, creates no
+  # block ends. Given no `endpoint:`, `socket_path:` or `socket_name:`, they
+  # bind the socket {Endpoint#initialize Endpoint.new} picks from
+  # `LIBTMUX_SOCKET_PATH`, `LIBTMUX_SOCKET`, `TMUX` and tmux's default socket,
+  # in that order. {Server.start} starts a private daemon instead, creates no
   # session, and owns the daemon's exit. {#endpoint} answers the {Endpoint}
   # and {#owned?} says whether this server started its daemon. {#diagnostics}
   # reports the request and control slots in use, and the limits. {#close}

data/lib/libtmux/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LibTmux
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/sig/libtmux.rbs

@@ -58,7 +58,7 @@ module LibTmux
   class Endpoint
     attr_reader executable: String
     attr_reader socket_path: String
-    def initialize: (?socket_path: String?, ?socket_name: String?, ?executable: String, ?socket_directory: String?) -> void
+    def initialize: (?socket_path: String?, ?socket_name: String?, ?executable: String, ?socket_directory: String?, ?environment: untyped) -> void
     def self.from_env: (?untyped, **untyped) -> Endpoint
     def ==: (untyped) -> bool
     alias eql? ==

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libtmux
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - libtmux contributors
@@ -131,7 +131,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/libtmux/libtmux-ruby
-  documentation_uri: https://libtmux.org/en/ruby/v0.1.0/
+  documentation_uri: https://libtmux.org/en/ruby/v0.1.1/
 rdoc_options: []
 require_paths:
 - lib