tmux 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 94ce03b8025bac7e2d13c5732de26e231259eb402c23c727bb071eece1e6bc6c
4
- data.tar.gz: 1c1d49bdc328d9432c06097b9a7d4024a30cb8098fc1d69d1c529a695560072f
3
+ metadata.gz: 23df323bead080f14d354e022382c975a8abfd8a1e9bf2e1cc97e48a4a58adfe
4
+ data.tar.gz: 19f81109a746188a54ab245f7f072823bc776b47480c22ae9bbe5d56bb96cd06
5
5
  SHA512:
6
- metadata.gz: ca1563f81d135988a54d60342f89dcaa3ca5d1ebc6a40a474ac7a2338ee2f7eb7826c948b2f4c8bf101e5f6cac754a3d79c64eb4b981fdd6b75cf54410efd984
7
- data.tar.gz: dd67416dba50395f82d136a9327bb72093c4b4618f64e31838b8aaf146e3309dbc4432e09460c882c1c182108840ccaedd1fba2b447c09751d5d42916954ea6e
6
+ metadata.gz: 128d863c330c583c0dde063c580703be9acb1b09beaa65cbacc0f94ed1468b5ea46a26d50ae7908a8803abdf7ed8cbb84dcbf9225b619a17acf2edefc899313c
7
+ data.tar.gz: 3779b8111d62b90df1f6f6112245e46aba9086a3ad52c498797b41930e4eefa0729819f686730a48fca3093b2d07c08a8a3032aa283706d0c9d37237f6dddd33
data/CHANGELOG.md CHANGED
@@ -1,5 +1,34 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.0 (2026-11-02)
4
+
5
+ ### Library
6
+
7
+ - Configuration files can `require` the Ruby module of an installed tmux
8
+ plugin by name, such as `require "tmux-ai-attn"`. tmux.rb looks in each
9
+ `--plugin-path`, then `TMUX_RB_PLUGIN_PATH`, then TPM's plugin directory,
10
+ and adds the `lib` directory of each plugin that ships
11
+ `lib/<its directory name>.rb` to the end of the load path. The first copy
12
+ of a plugin found wins.
13
+ - `use` writes a `# --- Name (file) ---` comment above each component it
14
+ splices in, naming the component and the file that defines its
15
+ `to_config`, so the generated config shows where each part begins.
16
+ `append` still splices without one.
17
+ This changes the output of configurations that use `use`: regenerate
18
+ any compiled config you compare against a checked-in copy.
19
+ - `Tmux.segments` holds named format blocks that compile, in order, to one
20
+ format. `insert` (`before:`/`after:`), `replace`, and `remove` adjust them
21
+ by name, so one part of a configuration can change a status line another
22
+ part defines. Options accept them, and anything else with `to_format`, as
23
+ values.
24
+
25
+ ### Development
26
+
27
+ - Merging a version bump to main tags it and creates a GitHub release once
28
+ CI passes on that commit, with the version's CHANGELOG section as the
29
+ notes (`script/release-notes VERSION` prints it). A test fails if the
30
+ current version has no CHANGELOG section.
31
+
3
32
  ## 0.2.0 (2026-10-23)
4
33
 
5
34
  ### Library
data/README.md CHANGED
@@ -38,12 +38,16 @@ Tmux.configure do
38
38
  global.base_index = 1
39
39
  window.mode_keys = :vi
40
40
 
41
- bind("|").split(:horizontal, cwd: :current)
42
- bind("-").split(:vertical, cwd: :current)
43
- bind("r").source("~/.tmux.conf").display_message("Reloaded")
41
+ bind("|").split(:h, cwd: :current)
42
+ bind("-").split(:v, cwd: :current)
43
+ bind("r")
44
+ .source("~/.tmux.conf")
45
+ .display_message("Reloaded")
44
46
 
45
47
  global.status.right = Tmux.format do
46
- if?(Tmux.window_zoomed_flag) { style(fg: :yellow) { text "ZOOM " } }
48
+ if?(Tmux.window_zoomed_flag) do
49
+ style(fg: :yellow) { text "ZOOM " }
50
+ end
47
51
  text Tmux.session_name
48
52
  end
49
53
  end
@@ -654,6 +658,31 @@ end
654
658
 
655
659
  </details>
656
660
 
661
+ ### Named segments
662
+
663
+ `Tmux.segments` holds format blocks under names and compiles them, in order,
664
+ to one format, so part of a configuration can adjust a status line another
665
+ part defines: `insert` a segment `before:` or `after:` a named one, `replace`
666
+ one in place, or `remove` some. Each block is an ordinary format block, and
667
+ all of them run on one builder, so powerline edges join their neighbors as if
668
+ written together. Assign the result to an option like any format.
669
+
670
+ ```ruby
671
+ # Shared by every machine.
672
+ right = Tmux.segments do
673
+ segment(:path) { left_segment Tmux.pane_current_path, bg: "#2d2d30", fg: :white }
674
+ segment(:host) { left_segment [Tmux.session_name, "@", Tmux.host], bg: "#5eaceb", fg: :black }
675
+ end
676
+
677
+ # One machine adds a clock; a phone-sized variant drops the path.
678
+ right.insert(:clock, before: :host) { left_segment(bg: "#4e4e4e", fg: :white) { strftime " %H:%M " } }
679
+ right.remove(:path) if compact
680
+
681
+ Tmux.configure { global.status.right = right }
682
+ ```
683
+
684
+ An unknown name raises an error listing the segments there are.
685
+
657
686
  ### Expanding options
658
687
 
659
688
  `expand_option` inserts a user option's value and expands it as a format, for
@@ -1153,7 +1182,10 @@ end
1153
1182
  `raw` passes tmux commands through verbatim (one per line; a trailing `\`
1154
1183
  continues a line), and `blank` adds an empty line. `append` includes another
1155
1184
  configuration's statements, and `use` accepts any object that responds to
1156
- `to_config`, such as a plugin's Ruby package.
1185
+ `to_config`, such as a plugin's Ruby package or one part of a configuration
1186
+ split across files. `use` writes a comment above the part naming it and the
1187
+ file its `to_config` is defined in (relative to the calling file's directory
1188
+ when it is inside it), so the generated config shows where each part begins.
1157
1189
 
1158
1190
  ```ruby
1159
1191
  shared = Tmux.configure { global.history_limit = 50_000 } # set-option -g history-limit 50000
@@ -1170,10 +1202,45 @@ Tmux.configure do
1170
1202
 
1171
1203
  # Another configuration's statements, in place.
1172
1204
  append shared
1173
- use clipboard
1205
+ use clipboard # preceded by "# --- Object (config.rb) ---"
1174
1206
  end
1175
1207
  ```
1176
1208
 
1209
+ ### Plugins
1210
+
1211
+ A configuration file can `require` the Ruby module of an installed tmux
1212
+ plugin by the plugin's name, however it was installed:
1213
+
1214
+ ```ruby
1215
+ require "tmux-ai-attn"
1216
+
1217
+ Tmux.configure do
1218
+ use TmuxAiAttn
1219
+ end
1220
+ ```
1221
+
1222
+ A plugin opts in by shipping `lib/<its directory name>.rb`, such as
1223
+ `tmux-ai-attn/lib/tmux-ai-attn.rb`. tmux.rb looks for plugins in this order;
1224
+ each place is either a plugin checkout or a directory of them, and the first
1225
+ copy of a plugin found wins:
1226
+
1227
+ 1. each `--plugin-path DIR` given to `build`, `check`, `diff`, or `load`
1228
+ 2. each entry of `TMUX_RB_PLUGIN_PATH`, separated by `:` like `PATH`
1229
+ 3. [TPM](https://github.com/tmux-plugins/tpm)'s plugin directory:
1230
+ `$TMUX_PLUGIN_MANAGER_PATH`, which TPM sets inside tmux, or else
1231
+ `~/.tmux/plugins` and `~/.config/tmux/plugins`
1232
+
1233
+ So a plugin installed with TPM needs no setup, and one cloned anywhere else
1234
+ needs only its location:
1235
+
1236
+ ```bash
1237
+ TMUX_RB_PLUGIN_PATH=~/src/tmux-ai-attn tmux.rb build tmux.rb --output ~/.tmux.conf
1238
+ ```
1239
+
1240
+ Only opted-in plugins' `lib` directories join Ruby's load path, after the
1241
+ entries already there, so `-I` and `RUBYLIB` take precedence. A failed
1242
+ `require` reports where tmux.rb looked.
1243
+
1177
1244
  ## Development
1178
1245
 
1179
1246
  ```bash
@@ -1181,6 +1248,10 @@ bundle install
1181
1248
  bundle exec rake test
1182
1249
  ```
1183
1250
 
1251
+ `mise.toml` pins the Ruby that CI packages and releases with (3.4), so with
1252
+ [mise](https://mise.jdx.dev) installed, `mise install` in the checkout gets
1253
+ it, Bundler included.
1254
+
1184
1255
  `bundle exec rake test` uses the tmux on your `PATH`.
1185
1256
  `bundle exec rake test:tmux` builds each tmux version CI tests (3.2a, the
1186
1257
  newest release of each later minor version, and the development branch)
data/lib/tmux/cli.rb CHANGED
@@ -20,6 +20,7 @@ module Tmux
20
20
  @stdout = stdout
21
21
  @stderr = stderr
22
22
  @tmux_executable = "tmux"
23
+ @plugin_path = []
23
24
  end
24
25
 
25
26
  def run(arguments)
@@ -125,6 +126,9 @@ module Tmux
125
126
  opts.banner = "usage: tmux.rb #{synopsis}"
126
127
  yield opts if block_given?
127
128
  opts.on("--tmux PATH", "Target this tmux executable (default: tmux on PATH)") { |path| @tmux_executable = path }
129
+ opts.on("--plugin-path DIR", "Look for plugins in DIR (a plugin or a directory of them) first; repeatable") do |dir|
130
+ @plugin_path << dir
131
+ end
128
132
  opts.on("-h", "--help", "Show this help") { early = :help }
129
133
  opts.on("--version", "Show the tmux.rb version") { early = :version }
130
134
  end
@@ -145,14 +149,23 @@ module Tmux
145
149
  # Errors raised while the configuration runs are reported with the line
146
150
  # in the configuration file that raised them.
147
151
  def load_source(path)
148
- Tmux.load_file(path, tmux: @tmux_executable)
152
+ Tmux.load_file(path, tmux: @tmux_executable, plugin_path: @plugin_path)
149
153
  rescue SyntaxError => error
150
154
  raise Error, error.message
151
155
  rescue StandardError, ScriptError => error
152
156
  location = location_in(error, File.expand_path(path))
153
157
  raise if location.nil? && (error.is_a?(Error) || error.is_a?(SystemCallError))
154
158
 
155
- raise Error, "#{location || path}: #{error.message} (#{error.class})"
159
+ raise Error, "#{location || path}: #{error.message} (#{error.class})#{plugin_hint(error)}"
160
+ end
161
+
162
+ # For a failed require: where tmux.rb looked for plugins.
163
+ def plugin_hint(error)
164
+ return "" unless error.is_a?(LoadError)
165
+
166
+ "\n(plugins are looked up in #{Plugins.search_path(extra: @plugin_path).join(", ")}; " \
167
+ "add others with --plugin-path or TMUX_RB_PLUGIN_PATH. " \
168
+ "A plugin is found by name when it ships lib/<its directory name>.rb)"
156
169
  end
157
170
 
158
171
  # The innermost backtrace frame inside the configuration file itself.
@@ -185,8 +185,17 @@ module Tmux
185
185
 
186
186
  # Import another tmux config object into this config. `component` is anything
187
187
  # implementing #to_config (returning a Tmux::Config) — e.g. a plugin's Ruby
188
- # package. Splices its nodes in call order.
189
- def use(component) = append(component.to_config)
188
+ # package. Splices its nodes in call order, under a comment naming the
189
+ # component and the file that defines it, so the generated config shows
190
+ # where each part begins. Use #append to splice without the comment.
191
+ def use(component)
192
+ config = component.to_config
193
+ blank unless @nodes.empty? || @nodes.last.is_a?(ConfigNode::Blank)
194
+ # A configuration file is evaluated, so its frames have only a path.
195
+ caller = caller_locations(1, 1).first
196
+ comment "--- #{component_label(component, caller && (caller.absolute_path || caller.path))} ---"
197
+ append config
198
+ end
190
199
 
191
200
  def build
192
201
  if (open = @open_bindings.find(&:empty?))
@@ -223,6 +232,28 @@ module Tmux
223
232
  end.first
224
233
  end
225
234
 
235
+ # "Name (path)" for #use: a module's own name or an object's class name,
236
+ # and the file defining its to_config, relative to the calling file's
237
+ # directory when it is inside it, otherwise with the home directory as ~.
238
+ def component_label(component, caller_path)
239
+ name = component.is_a?(Module) ? component.name : component.class.name
240
+ file = begin
241
+ component.method(:to_config).source_location&.first
242
+ rescue NameError # to_config answered by method_missing
243
+ nil
244
+ end
245
+ [name, file && "(#{display_path(file, caller_path)})"].compact.join(" ")
246
+ end
247
+
248
+ def display_path(file, caller_path)
249
+ file = File.expand_path(file)
250
+ base = caller_path && "#{File.dirname(caller_path)}/"
251
+ return file.delete_prefix(base) if base && file.start_with?(base)
252
+
253
+ home = "#{Dir.home}/"
254
+ file.start_with?(home) ? "~/#{file.delete_prefix(home)}" : file
255
+ end
256
+
226
257
  def write_option(name, value, scope:, append: false, expand: true)
227
258
  @nodes << ConfigNode::SetOption.new(normalize_option(name), value, scope, append, expand)
228
259
  end
data/lib/tmux/dsl.rb CHANGED
@@ -16,6 +16,10 @@ module Tmux
16
16
  ConditionalFormat.new(builder, builder.if?(condition, &block))
17
17
  end
18
18
 
19
+ # Named format blocks that can be inserted, replaced, or removed by name
20
+ # before they compile to one format (see Segments).
21
+ def self.segments(&block) = Segments.new(&block)
22
+
19
23
  # left/centre/right zones assembled into one aligned format (see ZoneBuilder).
20
24
  def self.pane_border(&block)
21
25
  builder = ZoneBuilder.new
@@ -141,6 +141,7 @@ module Tmux
141
141
  def write(value, append: false, expand: true)
142
142
  name = settable!("assignment")
143
143
  value = Tmux.style_string(value) if @descriptor[:style] && value.is_a?(Hash)
144
+ value = value.to_format if !value.is_a?(Format) && value.respond_to?(:to_format)
144
145
  @builder.__send__(:write_option, name, value, scope: @scope, append: append, expand: expand)
145
146
  end
146
147
  end
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Tmux
4
+ # Lets a configuration file `require` the Ruby module of an installed tmux
5
+ # plugin by name, such as `require "tmux-ai-attn"`, however the plugin was
6
+ # installed: by TPM, by hand, or by another tool.
7
+ #
8
+ # A plugin opts in by shipping lib/<its directory name>.rb. Its lib
9
+ # directory then joins the end of $LOAD_PATH, after -I, RUBYLIB, and
10
+ # anything already there. Plugins that have not opted in are never added,
11
+ # so their files cannot shadow another library.
12
+ module Plugins
13
+ # Where plugins are looked up, in order: each --plugin-path, then each
14
+ # entry of TMUX_RB_PLUGIN_PATH (separated like PATH), then TPM's plugin
15
+ # directory. Each is a plugin checkout or a directory of them. The first
16
+ # copy of a plugin found wins, so an explicit path overrides TPM's copy.
17
+ def self.search_path(env = ENV, extra: [])
18
+ configured = env.fetch("TMUX_RB_PLUGIN_PATH", "").split(File::PATH_SEPARATOR).reject(&:empty?)
19
+ (extra + configured + tpm_directories(env)).map { |path| File.expand_path(path) }.uniq
20
+ end
21
+
22
+ # TMUX_PLUGIN_MANAGER_PATH, which TPM sets in tmux's global environment,
23
+ # or else TPM's default locations.
24
+ def self.tpm_directories(env = ENV)
25
+ if (path = env["TMUX_PLUGIN_MANAGER_PATH"]) && !path.empty?
26
+ return [path]
27
+ end
28
+
29
+ config_home = env["XDG_CONFIG_HOME"]
30
+ config_home = File.join(Dir.home, ".config") if config_home.nil? || config_home.empty?
31
+ [File.join(Dir.home, ".tmux", "plugins"), File.join(config_home, "tmux", "plugins")]
32
+ end
33
+
34
+ # The lib directories of the opted-in plugins on the search path, one per
35
+ # plugin name, in search order.
36
+ def self.load_paths(env = ENV, extra: [])
37
+ found = {}
38
+ search_path(env, extra:).each do |path|
39
+ checkouts = opted_in?(path) ? [path] : Dir.glob(File.join(path, "*")).sort.select { |dir| opted_in?(dir) }
40
+ checkouts.each { |checkout| found[File.basename(checkout)] ||= File.join(checkout, "lib") }
41
+ end
42
+ found.values
43
+ end
44
+
45
+ def self.add_to_load_path(env = ENV, extra: [])
46
+ load_paths(env, extra:).each { |lib| $LOAD_PATH << lib unless $LOAD_PATH.include?(lib) }
47
+ end
48
+
49
+ def self.opted_in?(checkout) = File.file?(File.join(checkout, "lib", "#{File.basename(checkout)}.rb"))
50
+ private_class_method :opted_in?
51
+ end
52
+ end
@@ -0,0 +1,74 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Tmux
4
+ # An ordered list of named format blocks that compiles to one format, so a
5
+ # status line built in one place can be adjusted in another: a machine's
6
+ # config inserts, replaces, or removes segments by name before the format is
7
+ # assigned. Blocks run in order on a single format builder when the format
8
+ # is built, so powerline edges join neighbors as if written in one block.
9
+ #
10
+ # right = Tmux.segments do
11
+ # segment(:path) { left_segment Tmux.pane_current_path, bg: "colour236", fg: :white }
12
+ # segment(:host) { left_segment Tmux.host, bg: :blue, fg: :black }
13
+ # end
14
+ # right.insert(:clock, before: :host) { left_segment "%H:%M", bg: "colour238", fg: :white }
15
+ # global.status.right = right
16
+ class Segments
17
+ def initialize(&block)
18
+ @segments = []
19
+ Evaluation.run(self, block) if block
20
+ end
21
+
22
+ # The segment names, in order.
23
+ def names = @segments.map(&:first)
24
+
25
+ # Adds a segment at the end.
26
+ def segment(name, &block)
27
+ raise Error, "segment #{name.inspect} needs a block" unless block
28
+ raise Error, "segment #{name.inspect} is already defined" if names.include?(name)
29
+
30
+ @segments << [name, block]
31
+ self
32
+ end
33
+
34
+ # Adds a segment just before or after an existing one.
35
+ def insert(name, before: nil, after: nil, &block)
36
+ raise Error, "insert #{name.inspect}: give before: or after:, not both" if before && after
37
+ raise Error, "insert #{name.inspect}: give before: or after:" unless before || after
38
+ raise Error, "segment #{name.inspect} needs a block" unless block
39
+ raise Error, "segment #{name.inspect} is already defined" if names.include?(name)
40
+
41
+ index = position(before || after)
42
+ @segments.insert(after ? index + 1 : index, [name, block])
43
+ self
44
+ end
45
+
46
+ # Swaps an existing segment's block for a new one, keeping its place.
47
+ def replace(name, &block)
48
+ raise Error, "segment #{name.inspect} needs a block" unless block
49
+
50
+ @segments[position(name)] = [name, block]
51
+ self
52
+ end
53
+
54
+ def remove(*names_to_remove)
55
+ names_to_remove.each { |name| @segments.delete_at(position(name)) }
56
+ self
57
+ end
58
+
59
+ def to_format
60
+ blocks = @segments.map(&:last)
61
+ Tmux.format { blocks.each { |block| evaluate(block) } }
62
+ end
63
+
64
+ def to_tmux = to_format.to_tmux
65
+ alias_method :to_s, :to_tmux
66
+
67
+ private
68
+
69
+ def position(name)
70
+ names.index(name) or
71
+ raise Error, "no segment #{name.inspect}; segments are #{names.map(&:inspect).join(', ')}"
72
+ end
73
+ end
74
+ end
data/lib/tmux/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Tmux
4
- VERSION = "0.2.0"
4
+ VERSION = "0.3.0"
5
5
  end
data/lib/tmux.rb CHANGED
@@ -18,6 +18,8 @@ require_relative "tmux/config_builder"
18
18
  require_relative "tmux/option_tree"
19
19
  require_relative "tmux/condition_compiler"
20
20
  require_relative "tmux/dsl"
21
+ require_relative "tmux/plugins"
22
+ require_relative "tmux/segments"
21
23
 
22
24
  module Tmux
23
25
  # Evaluates a configuration file and returns the Tmux::Config or
@@ -25,9 +27,12 @@ module Tmux
25
27
  # anonymous module, which keeps its constants and methods out of the global
26
28
  # namespace. Configuration files are trusted Ruby: the module is not a
27
29
  # sandbox. Logical operators in DSL conditions are captured before Ruby
28
- # evaluates them, so && / || build deferred tmux expressions.
29
- def self.load_file(path, tmux: nil)
30
+ # evaluates them, so && / || build deferred tmux expressions. The file can
31
+ # `require` the Ruby module of an installed plugin by name (see Plugins);
32
+ # `plugin_path` adds directories to search first.
33
+ def self.load_file(path, tmux: nil, plugin_path: [])
30
34
  target = tmux ? Target.for_executable(tmux) : Target.current
35
+ Plugins.add_to_load_path(extra: plugin_path)
31
36
  Target.with(target) { evaluate_file(path) }
32
37
  end
33
38
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: tmux
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Nick deLannoy
@@ -61,6 +61,8 @@ files:
61
61
  - lib/tmux/format_compiler.rb
62
62
  - lib/tmux/glyph.rb
63
63
  - lib/tmux/option_tree.rb
64
+ - lib/tmux/plugins.rb
65
+ - lib/tmux/segments.rb
64
66
  - lib/tmux/target.rb
65
67
  - lib/tmux/version.rb
66
68
  - lib/tmux/zone_builder.rb
@@ -86,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
86
88
  - !ruby/object:Gem::Version
87
89
  version: '0'
88
90
  requirements: []
89
- rubygems_version: 3.6.7
91
+ rubygems_version: 3.6.9
90
92
  specification_version: 4
91
93
  summary: A readable Ruby DSL that compiles to native tmux configuration
92
94
  test_files: []