tmux 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 225f31971e201d9baeeec68e3f920d8a72f727012a15e0617bb09d551a0af4a9
-  data.tar.gz: 103f4cbd898b274d9901e825c3eecb95fdd534d2178fe6a59428066e58448f59
+  metadata.gz: 94ce03b8025bac7e2d13c5732de26e231259eb402c23c727bb071eece1e6bc6c
+  data.tar.gz: 1c1d49bdc328d9432c06097b9a7d4024a30cb8098fc1d69d1c529a695560072f
 SHA512:
-  metadata.gz: 3006eeaaca5dbf9449c9c2f8081096cc4c172c1f2cb3b1933348409b4a9f231522749213e025f0a187e0ceccbb2eaf63a6905fca3f772d8f58682f6ab5034bbf
-  data.tar.gz: 316d61e9d40ae7c52f4352f350d38cb4f78c9b42c5bc047b2cab32d04ab66c4f1a646eeea52de19bee5b6f7111e29db325167381d5203410b5b617ef00228f8f
+  metadata.gz: ca1563f81d135988a54d60342f89dcaa3ca5d1ebc6a40a474ac7a2338ee2f7eb7826c948b2f4c8bf101e5f6cac754a3d79c64eb4b981fdd6b75cf54410efd984
+  data.tar.gz: dd67416dba50395f82d136a9327bb72093c4b4618f64e31838b8aaf146e3309dbc4432e09460c882c1c182108840ccaedd1fba2b447c09751d5d42916954ea6e

data/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## 0.1.0 (unreleased)
+## 0.2.0 (2026-10-23)
+
+### Library
+
+- `bind(key)` with no command or block returns a chain of named commands:
+  `bind("-").split(:vertical).cwd(:current)`, `bind("c").new_window`.
+- Named binding commands `split`, `new_window`, `cwd`, `resize_pane`, `zoom`,
+  `kill_pane`, `kill_window`, and `source`, and a direction for
+  `select_pane`. `split` accepts `:vertical`/`:horizontal` or the shorthand
+  `:v`/`:h`. They work in chains and in binding blocks.
+- `comment` writes `#` lines into the generated file, and `hook` sets a
+  tmux hook (command string or block, optional `index:` slot, `:global`,
+  `:window`, or `:pane` scope).
+
+### Fixes
+
+- `shell(...)` conditions reach the shell exactly as written. tmux no longer
+  expands `$` variables when the file loads or rejects shell syntax such as
+  `${VAR:-default}`.
+
+### Documentation
+
+- The README opens with a hand-written tmux.conf beside its tmux.rb version,
+  and Examples move up ahead of Why. Tests check that both versions load
+  identically and that the key binding examples match their tmux comments.
+
+## 0.1.0 (2026-10-21)
 
 First public release, as the `tmux` gem (`require "tmux"`), with the
 `tmux.rb` command (also installed as `tmux_rb`).

data/README.md

@@ -3,6 +3,55 @@
 tmux.rb is a Ruby DSL that compiles readable, structured block-based
 configuration into native tmux configuration and format strings.
 
+## At a glance
+
+A small, hand-written `~/.tmux.conf`:
+
+<!-- glance: tmux -->
+```tmux
+set -g prefix C-a
+unbind C-b
+bind C-a send-prefix
+
+set -g mouse on
+set -g base-index 1
+setw -g mode-keys vi
+
+bind | split-window -h -c "#{pane_current_path}"
+bind - split-window -v -c "#{pane_current_path}"
+bind r source-file ~/.tmux.conf \; display-message "Reloaded"
+
+set -g status-right "#{?window_zoomed_flag,#[fg=yellow]ZOOM #[fg=default],}#S"
+```
+
+The same configuration in tmux.rb, which compiles to a file tmux loads
+identically:
+
+<!-- glance: ruby -->
+```ruby
+Tmux.configure do
+  global.prefix = "C-a"
+  unbind "C-b"
+  bind("C-a").command(:send_prefix)
+
+  global.mouse = true
+  global.base_index = 1
+  window.mode_keys = :vi
+
+  bind("|").split(:horizontal, cwd: :current)
+  bind("-").split(:vertical, cwd: :current)
+  bind("r").source("~/.tmux.conf").display_message("Reloaded")
+
+  global.status.right = Tmux.format do
+    if?(Tmux.window_zoomed_flag) { style(fg: :yellow) { text "ZOOM " } }
+    text Tmux.session_name
+  end
+end
+```
+
+The payoff grows with the configuration. Status lines are where hand-written
+tmux gets hardest to read, and where the format DSL helps most:
+
 <!-- example: intro -->
 ```ruby
 # ~/.config/tmux/tmux.rb
@@ -19,7 +68,7 @@ Tmux.configure do
     left_segment "#{Tmux.session_name}@#{Tmux.host}", bg: :blue, fg: :black
   end
 
-  bind "|", %q{split-window -h -c "#{pane_current_path}"}
+  bind("|").split(:horizontal, cwd: :current)
 end
 ```
 
@@ -43,6 +92,18 @@ the status bar set to the terminal's own colors. Named colors such as `:blue`,
 everywhere. Powerline edges need a font with Powerline glyphs, such as a
 [Nerd Font](https://www.nerdfonts.com).
 
+## Examples
+
+- [examples/author_config.rb](https://github.com/cosmicbuffalo/tmux.rb/blob/main/examples/author_config.rb)
+  is the author's complete tmux configuration: structured status bars, pane
+  borders, and window tabs, plus integration with
+  [tmux-ai-attn](https://github.com/cosmicbuffalo/tmux-ai-attn).
+- [examples/popular_configs](https://github.com/cosmicbuffalo/tmux.rb/blob/main/examples/popular_configs/README.md)
+  contains ten ports of well-known public tmux configurations. Each pinned
+  upstream config sits beside its Ruby version for comparison.
+- [examples/window_status.rb](https://github.com/cosmicbuffalo/tmux.rb/blob/main/examples/window_status.rb)
+  is a standalone format file.
+
 ## Why
 
 Hand-written tmux configuration gets hard to change once it grows: status
@@ -825,11 +886,74 @@ end
 
 ### Key bindings
 
-`bind` maps a key to a tmux command string or a block of commands. Use the
-block form to pass command arguments without quoting them by hand.
-`table:` picks a key table, `no_prefix: true` binds without the prefix (`-n`),
-`repeat: true` allows repeating (`-r`), and `note:` adds a description (`-N`).
-`unbind` removes a binding.
+`bind` maps a key to commands. Name the commands in a chain, write a block of
+commands, or pass a tmux command string. `table:` picks a key table,
+`no_prefix: true` binds without the prefix (`-n`), `repeat: true` allows
+repeating (`-r`), and `note:` adds a description (`-N`). `unbind` removes a
+binding.
+
+Given only a key, `bind` returns a chain. Each method adds a command, and
+`cwd` sets the directory for the `split` or `new_window` before it:
+
+```ruby
+Tmux.configure do
+  # tmux: bind-key "-" split-window -v -c "#{pane_current_path}"
+  bind("-").split(:vertical).cwd(:current)
+
+  # tmux: bind-key "|" split-window -h -l "30%" -c "~/src"
+  bind("|").split(:horizontal, size: "30%", cwd: "~/src")
+
+  # tmux: bind-key "c" new-window
+  bind("c").new_window
+
+  # Commands run in order: a named window, then back to the last pane.
+  # tmux: bind-key "C" new-window -n "scratch" -c "#{pane_current_path}" \; select-pane -t "{last}"
+  bind("C").new_window(name: "scratch").cwd(:current).select_pane(target: "{last}")
+
+  # tmux: bind-key -r "h" select-pane -L
+  bind("h", repeat: true).select_pane(:left)
+
+  # tmux: bind-key -r "<" resize-pane -L 10
+  bind("<", repeat: true).resize_pane(:left, 10)
+
+  # tmux: bind-key -n "M-z" resize-pane -Z
+  bind("M-z", no_prefix: true).zoom
+
+  # tmux: bind-key "r" source-file "~/.tmux.conf" \; display-message "Reloaded"
+  bind("r").source("~/.tmux.conf").display_message("Reloaded")
+end
+```
+
+`split` takes tmux's direction names: `:vertical` (`-v`) puts the new pane
+below, and `:horizontal` (`-h`) puts it to the right. `:v` and `:h` are
+shorthand for them. Pane directions are
+`:left`, `:right`, `:up`, and `:down`. The named commands are `split`,
+`new_window`, `select_pane`, `resize_pane`, `zoom`, `kill_pane`,
+`kill_window`, `source`, `display_message`, `display_menu`, `copy_mode`, and
+`load_config`. Use `command` for any other tmux command (its arguments are
+quoted for you) and `raw` for a command written exactly as tmux expects it.
+
+The block form uses the same methods, one command per line, so `cwd` on its
+own line applies to the `split` above it:
+
+```ruby
+Tmux.configure do
+  # tmux: bind-key "|" split-window -h -c "some-dir"
+  bind "|" do
+    split :h # or :horizontal
+    cwd "some-dir"
+  end
+
+  # tmux: bind-key "C" new-window -n "scratch" -c "#{pane_current_path}" \; select-pane -t "{last}"
+  bind "C" do
+    new_window name: "scratch"
+    cwd :current
+    select_pane target: "{last}"
+  end
+end
+```
+
+Command strings pass through as written:
 
 ```ruby
 Tmux.configure do
@@ -869,9 +993,8 @@ Tmux.configure do
 end
 ```
 
-A binding block offers `command` for any tmux command (its arguments are
-quoted for you), `select_pane`, `copy_mode`, `display_message`,
-`display_menu`, `load_config`, and `raw`:
+Blocks suit longer bindings, such as a menu or a command with no named
+helper:
 
 ```ruby
 Tmux.configure do
@@ -888,10 +1011,10 @@ Tmux.configure do
     end
   end
 
-  # Any command, with quoted arguments; select_pane can target a pane.
-  # tmux: bind-key "N" new-window "-c" "#{pane_current_path}" \; select-pane -t "{last}"
-  bind "N" do
-    command :new_window, "-c", "\#{pane_current_path}"
+  # Any command, with quoted arguments.
+  # tmux: bind-key "S" swap-pane "-s" "{last}" \; select-pane -t "{last}"
+  bind "S" do
+    command :swap_pane, "-s", "{last}"
     select_pane target: "{last}"
   end
 
@@ -910,16 +1033,16 @@ return one and several bindings can share it:
 Tmux.configure do
   def split_here(direction)
     commands do
-      command :split_window, direction, "-c", "\#{pane_current_path}"
+      split direction, cwd: :current
       display_message "split"
     end
   end
 
-  # tmux: bind-key "|" split-window "-h" -c "#{pane_current_path}" \; display-message "split"
-  bind "|", split_here("-h")
+  # tmux: bind-key "|" split-window -h -c "#{pane_current_path}" \; display-message "split"
+  bind "|", split_here(:horizontal)
 
-  # tmux: bind-key "-" split-window "-v" -c "#{pane_current_path}" \; display-message "split"
-  bind "-", split_here("-v")
+  # tmux: bind-key "-" split-window -v -c "#{pane_current_path}" \; display-message "split"
+  bind "-", split_here(:vertical)
 end
 ```
 
@@ -1004,6 +1127,27 @@ Tmux.configure do
 end
 ```
 
+### Comments and hooks
+
+`comment` writes `#` lines into the generated file, for whoever reads or edits
+it. `hook` sets a tmux hook from a command string or a block of commands, as
+`bind` does; `index:` gives it its own slot so setting it again replaces that
+slot rather than adding a copy, and `scope:` picks `:global` (session hooks),
+`:window`, or `:pane`.
+
+```ruby
+Tmux.configure do
+  # # Snapshot sessions whenever one closes.
+  comment "Snapshot sessions whenever one closes."
+
+  # tmux: set-hook -g "session-closed[100]" "run-shell -b \"save-sessions\""
+  hook "session-closed", %q{run-shell -b "save-sessions"}, index: 100
+
+  # tmux: set-hook -gw "pane-focus-in" "display-message \"focused\""
+  hook("pane-focus-in", scope: :window) { display_message "focused" }
+end
+```
+
 ### Raw commands and composition
 
 `raw` passes tmux commands through verbatim (one per line; a trailing `\`
@@ -1030,18 +1174,6 @@ Tmux.configure do
 end
 ```
 
-## Examples
-
-- [examples/author_config.rb](https://github.com/cosmicbuffalo/tmux.rb/blob/main/examples/author_config.rb)
-  is the author's complete tmux configuration: structured status bars, pane
-  borders, and window tabs, plus integration with
-  [tmux-ai-attn](https://github.com/cosmicbuffalo/tmux-ai-attn).
-- [examples/popular_configs](https://github.com/cosmicbuffalo/tmux.rb/blob/main/examples/popular_configs/README.md)
-  contains ten ports of well-known public tmux configurations. Each pinned
-  upstream config sits beside its Ruby version for comparison.
-- [examples/window_status.rb](https://github.com/cosmicbuffalo/tmux.rb/blob/main/examples/window_status.rb)
-  is a standalone format file.
-
 ## Development
 
 ```bash

data/lib/tmux/command_builder.rb

@@ -32,6 +32,20 @@ module Tmux
   # separate entries until the binding is compiled, so callers never write tmux
   # command separators or quote command arguments by hand.
   class CommandBuilder
+    # A command built by one of the named helpers below, kept in parts so a
+    # modifier such as #cwd can still add a flag before it compiles.
+    Typed = Struct.new(:name, :flags) do
+      def to_s = [name, *flags].join(" ")
+    end
+    private_constant :Typed
+
+    # tmux's own names: a vertical split (-v) stacks the new pane below, a
+    # horizontal one (-h) puts it to the right. :v and :h are shorthand.
+    SPLIT_DIRECTIONS = { vertical: "-v", v: "-v", horizontal: "-h", h: "-h" }.freeze
+    PANE_DIRECTIONS = { left: "-L", right: "-R", up: "-U", down: "-D" }.freeze
+    CWD_COMMANDS = %w[split-window new-window].freeze
+    private_constant :SPLIT_DIRECTIONS, :PANE_DIRECTIONS, :CWD_COMMANDS
+
     def initialize = @commands = []
 
     # Any tmux command. Arguments are quoted for you; tmux expands $VARIABLES
@@ -48,13 +62,59 @@ module Tmux
       self
     end
 
-    def select_pane(target: nil)
+    # split-window. `cwd:` starts the new pane in a directory; :current is the
+    # active pane's directory. `size:` is lines/columns or a "30%" string.
+    def split(direction, cwd: nil, size: nil)
+      flag = SPLIT_DIRECTIONS.fetch(direction) do
+        raise Error, "split direction must be :vertical (:v) or :horizontal (:h), not #{direction.inspect}"
+      end
+      flags = [flag]
+      flags.concat(["-l", ConfigCompiler.quote(size)]) if size
+      typed("split-window", flags, cwd:)
+    end
+
+    def new_window(name: nil, cwd: nil)
+      flags = []
+      flags.concat(["-n", ConfigCompiler.quote(name)]) if name
+      typed("new-window", flags, cwd:)
+    end
+
+    # Start the previous command (split or new_window) in `directory`;
+    # :current is the active pane's directory.
+    def cwd(directory)
+      last = @commands.last
+      unless last.is_a?(Typed) && CWD_COMMANDS.include?(last.name)
+        raise Error, "cwd must follow split or new_window"
+      end
+      raise Error, "#{last.name} already has a directory" if last.flags.include?("-c")
+
+      last.flags.concat(["-c", ConfigCompiler.quote(directory == :current ? "\#{pane_current_path}" : directory)])
+      self
+    end
+
+    # select-pane, by direction (:left, :right, :up, :down) and/or target.
+    def select_pane(direction = nil, target: nil)
       parts = ["select-pane"]
+      parts << pane_direction(direction) if direction
       parts.concat(["-t", ConfigCompiler.quote(target)]) if target
       @commands << parts.join(" ")
       self
     end
 
+    # resize-pane by `amount` cells (tmux's default is 1) in a direction.
+    def resize_pane(direction, amount = nil)
+      @commands << ["resize-pane", pane_direction(direction), amount&.to_i].compact.join(" ")
+      self
+    end
+
+    # Toggle the active pane's zoom (resize-pane -Z).
+    def zoom = raw("resize-pane -Z")
+    def kill_pane = raw("kill-pane")
+    def kill_window = raw("kill-window")
+
+    # source-file; `quiet: true` (-q) skips a missing file without an error.
+    def source(path, quiet: false) = raw("source-file#{' -q' if quiet} #{ConfigCompiler.quote(path)}")
+
     # Send one copy-mode command (`send-keys -X`) to a pane. `count:` maps to
     # tmux's -N repeat count, used by actions such as scroll-up and scroll-down.
     def copy_mode(action, target: nil, count: nil)
@@ -91,14 +151,52 @@ module Tmux
       self
     end
 
+    def empty? = @commands.empty?
+
     def build
       raise Error, "a command block must contain at least one command" if @commands.empty?
 
-      @commands.join(" \\; ")
+      @commands.map(&:to_s).join(" \\; ")
     end
 
     private
 
+    def typed(name, flags, cwd: nil)
+      @commands << Typed.new(name, flags)
+      cwd ? self.cwd(cwd) : self
+    end
+
+    def pane_direction(direction)
+      PANE_DIRECTIONS.fetch(direction) do
+        raise Error, "pane direction must be :left, :right, :up, or :down, not #{direction.inspect}"
+      end
+    end
+
     def normalize(name) = name.to_s.tr("_", "-")
   end
+
+  # What `bind(key)` returns without a command or block. Each CommandBuilder
+  # method adds a command and rewrites the binding's configuration line, so the
+  # chain can stop anywhere: bind("c").new_window.cwd(:current)
+  class BindingChain
+    attr_reader :key
+
+    def initialize(key, prefix, nodes, index)
+      @key = key
+      @prefix = prefix
+      @nodes = nodes
+      @index = index
+      @commands = CommandBuilder.new
+    end
+
+    def empty? = @commands.empty?
+
+    (CommandBuilder.public_instance_methods(false) - %i[build empty?]).each do |name|
+      define_method(name) do |*arguments, **options, &block|
+        @commands.public_send(name, *arguments, **options, &block)
+        @nodes[@index] = ConfigNode::Command.new("#{@prefix} #{@commands.build}")
+        self
+      end
+    end
+  end
 end

data/lib/tmux/config_builder.rb

@@ -2,7 +2,8 @@
 
 module Tmux
   # The context of a Tmux.configure block. Every DSL method returns the
-  # builder (conditionals return a handle for `.else`), so calls can be chained.
+  # builder (conditionals return a handle for `.else`, and `bind(key)` a
+  # BindingChain), so calls can be chained.
   class ConfigBuilder
     include Evaluation
 
@@ -13,6 +14,7 @@ module Tmux
       @nodes = []
       @else_filled = {}
       @conditional_states = {}
+      @open_bindings = []
     end
 
     def switch(cases) = Tmux.switch(cases)
@@ -38,6 +40,32 @@ module Tmux
       self
     end
 
+    # A comment in the generated file: one "# " line per line of `text`, and a
+    # bare "#" for an empty one. tmux ignores comments; they are for whoever
+    # reads or edits the generated config.
+    def comment(text)
+      text.to_s.each_line(chomp: true) do |line|
+        @nodes << ConfigNode::Command.new(line.empty? ? "#" : "# #{line}")
+      end
+      self
+    end
+
+    # A hook, as set-hook: `name` fires `command`, a tmux command string or a
+    # block of commands as for #bind. `index:` gives the hook its own slot
+    # (name[index]), so setting it again replaces that slot instead of adding
+    # another copy. `scope:` is :global (session hooks), :window, or :pane.
+    def hook(name, command = nil, index: nil, scope: :global, &block)
+      raise ArgumentError, "hook #{name}: give a command or a block, not both" if command && block
+      raise ArgumentError, "hook #{name}: give a command or a block" unless command || block
+
+      command = commands(&block) if block
+      flag = {global: "-g", window: "-gw", pane: "-gp"}.fetch(scope) do
+        raise ArgumentError, "hook #{name}: scope must be :global, :window, or :pane"
+      end
+      slot = index.nil? ? name.to_s : "#{name}[#{Integer(index)}]"
+      raw "set-hook #{flag} #{ConfigCompiler.quote(slot)} #{ConfigCompiler.quote(command.to_s, expand: false)}"
+    end
+
     # Scoped options are generated from the selected target's complete catalog.
     def global = option_root(:global)
     def server = option_root(:server)
@@ -76,21 +104,29 @@ module Tmux
       ].compact.join(" ")
     end
 
+    # With neither a command nor a block, bind returns a chain that adds each
+    # command to the binding: `bind("-").split(:vertical).cwd(:current)`.
     def bind(key, command = nil, table: nil, repeat: false, no_prefix: false, note: nil, &block)
       raise Error, "bind cannot combine table: and no_prefix:" if table && no_prefix
       raise Error, "bind accepts either a command or a block, not both" if command && block
 
-      command = commands(&block) if block
-      raise Error, "bind requires a command or block" unless command
-
       parts = ["bind-key"]
       parts << "-r" if repeat
       parts << "-n" if no_prefix
       parts.concat(["-N", ConfigCompiler.quote(note)]) if note
       parts.concat(["-T", ConfigCompiler.quote(table)]) if table
       parts << ConfigCompiler.quote(key)
-      parts << command
-      raw parts.join(" ")
+      prefix = parts.join(" ")
+
+      unless command || block
+        chain = BindingChain.new(key, prefix, @nodes, @nodes.size)
+        @nodes << ConfigNode::Blank.new # replaced by the chain's first command
+        @open_bindings << chain
+        return chain
+      end
+
+      command = commands(&block) if block
+      raw "#{prefix} #{command}"
     end
 
     # source-file; `quiet: true` (-q) skips a missing file without an error.
@@ -152,7 +188,13 @@ module Tmux
     # package. Splices its nodes in call order.
     def use(component) = append(component.to_config)
 
-    def build = Config.new(@nodes, target: target).validate!
+    def build
+      if (open = @open_bindings.find(&:empty?))
+        raise Error, "bind #{open.key.inspect} has no command: chain one, such as .split(:vertical), or pass a command or block"
+      end
+
+      Config.new(@nodes, target: target).validate!
+    end
 
     private
 

data/lib/tmux/config_compiler.rb

@@ -58,7 +58,10 @@ module Tmux
       parts = ["if-shell"]
       parts << "-b" if node.background
       parts << "-F" if node.format
-      parts << self.class.quote(node.test)
+      # A shell test is for the shell: escape $ and a leading ~ so tmux's
+      # parser leaves them alone (it rejects shell syntax such as
+      # ${VAR:-default} in a double-quoted string).
+      parts << self.class.quote(node.test, expand: node.format)
       text = "#{parts.join(' ')} #{block(node.success)}"
       text += " #{block(node.failure)}" unless node.failure.empty?
       text

data/lib/tmux/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tmux
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nick deLannoy