tmux 0.1.0

data/lib/tmux/config_builder.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+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.
+  class ConfigBuilder
+    include Evaluation
+
+    attr_reader :target
+
+    def initialize(target: Target.current)
+      @target = target
+      @nodes = []
+      @else_filled = {}
+      @conditional_states = {}
+    end
+
+    def switch(cases) = Tmux.switch(cases)
+    def shell(command, background: false) = Tmux.shell(command, background:)
+
+    def blank
+      @nodes << ConfigNode::Blank.new
+      self
+    end
+
+    # Verbatim tmux commands, one node per line. A line ending in "\\" keeps
+    # the next line in the same command, matching tmux's line continuation.
+    def raw(command)
+      pending = nil
+      command.to_s.each_line(chomp: true) do |line|
+        pending = pending ? "#{pending}\n#{line}" : line
+        next if pending[/\\*\z/].length.odd?
+
+        @nodes << (pending.empty? ? ConfigNode::Blank.new : ConfigNode::Command.new(pending))
+        pending = nil
+      end
+      @nodes << ConfigNode::Command.new(pending) if pending
+      self
+    end
+
+    # Scoped options are generated from the selected target's complete catalog.
+    def global = option_root(:global)
+    def server = option_root(:server)
+    def window = option_root(:window)
+
+    def environment(name, value)
+      raw "set-environment -g #{ConfigCompiler.quote(name)} #{ConfigCompiler.quote(value)}"
+    end
+
+    # Build a reusable tmux command sequence. This makes ordinary Ruby helper
+    # methods composable with bind, e.g. `bind "r", reload_config`.
+    def commands(&block)
+      builder = CommandBuilder.new
+      Evaluation.run(builder, block)
+      builder.build
+    end
+
+    # A reusable command sequence that recompiles and loads a Ruby config, with
+    # an optional success message. Intended to be returned from ordinary Ruby
+    # helper methods and passed directly to #bind.
+    def load_config(path, executable: "tmux.rb", message: nil)
+      commands do
+        load_config(path, executable:)
+        display_message message if message
+      end
+    end
+
+    def unbind(key, table: nil, no_prefix: false)
+      raise Error, "unbind cannot combine table: and no_prefix:" if table && no_prefix
+
+      raw [
+        "unbind-key",
+        ("-n" if no_prefix),
+        ("-T #{ConfigCompiler.quote(table)}" if table),
+        ConfigCompiler.quote(key)
+      ].compact.join(" ")
+    end
+
+    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(" ")
+    end
+
+    # 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)}")
+
+    def run_shell(command, background: false)
+      raw "run-shell#{' -b' if background} #{ConfigCompiler.quote(command)}"
+    end
+
+    # Runtime configuration branches, using either a tmux expression or a
+    # deferred shell check. Branches remain native tmux command blocks.
+    def if?(condition, background: false, &block)
+      node = conditional_branch(condition, block, background:)
+      index = @nodes.size
+      @nodes << node
+      @conditional_states[index] = [node]
+      @else_filled[index] = false
+      ConfigConditional.new(self, index)
+    end
+
+    def fill_elsif(index, condition, block, background: false)
+      open_conditional(index, ".elsif?")
+      branch = conditional_branch(condition, block, background:)
+      @conditional_states.fetch(index) << branch
+      rebuild_conditional(index, [])
+    end
+
+    def fill_else(index, block)
+      node = @nodes[index]
+      unless (node.is_a?(ConfigNode::IfShell) || node.is_a?(ConfigNode::Condition)) && @else_filled.key?(index)
+        raise Error, ".else must directly follow the if?, tmux_from, or tmux_below it belongs to"
+      end
+      raise Error, "this conditional already has an else branch" if @else_filled[index]
+
+      otherwise = capture(block)
+      @else_filled[index] = true
+      if node.is_a?(ConfigNode::IfShell)
+        rebuild_conditional(index, otherwise)
+      else
+        @nodes[index] = node.with(otherwise: otherwise)
+      end
+      self
+    end
+
+    # Version-gated config: the block applies only when the running tmux server
+    # is older than / at least `version` ("major.minor"). Compiles to a %if on
+    # tmux's own #{version}, so no shell runs and no tmux binary on PATH is
+    # consulted.
+    def tmux_below(version, &block) = version_gate(:below, version, block)
+    def tmux_from(version, &block) = version_gate(:from, version, block)
+
+    def append(config)
+      @nodes.concat(config.nodes)
+      self
+    end
+
+    # Import another tmux config object into this config. `component` is anything
+    # implementing #to_config (returning a Tmux::Config) — e.g. a plugin's Ruby
+    # package. Splices its nodes in call order.
+    def use(component) = append(component.to_config)
+
+    def build = Config.new(@nodes, target: target).validate!
+
+    private
+
+    def conditional_branch(condition, block, background:)
+      if condition.is_a?(ShellCondition)
+        test = condition.command
+        background ||= condition.background
+        format = false
+      else
+        test = Tmux.expression(condition).source
+        format = true
+      end
+      ConfigNode::IfShell.new(test, capture(block), [], format, background)
+    end
+
+    def open_conditional(index, method)
+      unless @nodes[index].is_a?(ConfigNode::IfShell) && @conditional_states.key?(index)
+        raise Error, "#{method} must follow the if? it belongs to"
+      end
+      raise Error, "this conditional already has an else branch" if @else_filled[index]
+    end
+
+    def rebuild_conditional(index, otherwise)
+      @nodes[index] = @conditional_states.fetch(index).reverse_each.reduce(otherwise) do |failure, branch|
+        [branch.with(failure:)]
+      end.first
+    end
+
+    def write_option(name, value, scope:, append: false, expand: true)
+      @nodes << ConfigNode::SetOption.new(normalize_option(name), value, scope, append, expand)
+    end
+
+    def remove_option(name, scope:)
+      @nodes << ConfigNode::UnsetOption.new(normalize_option(name), scope)
+    end
+
+    def option_root(scope)
+      @option_roots ||= {}
+      @option_roots[scope] ||= OptionNode.root(self, scope)
+    end
+
+    # Runs a branch block on this same builder with a fresh node buffer, so
+    # helper methods and instance variables stay visible in nested blocks.
+    def capture(block)
+      return [] unless block
+
+      saved = [@nodes, @else_filled, @conditional_states]
+      @nodes = []
+      @else_filled = {}
+      @conditional_states = {}
+      evaluate(block)
+      @nodes
+    ensure
+      @nodes, @else_filled, @conditional_states = saved if saved
+    end
+
+    def normalize_option(name)
+      value = name.to_s
+      value.start_with?("@") ? value : value.tr("_", "-")
+    end
+
+    def version_gate(direction, version, block)
+      @nodes << ConfigNode::Condition.new(version_condition(direction, version), capture(block), [], version, direction)
+      @else_filled[@nodes.size - 1] = false
+      Else.new(self, @nodes.size - 1)
+    end
+
+    # #{version} as major * 1000 + minor, so 3.10 sorts after 3.9 and "3.5a",
+    # "next-3.6", or "openbsd-7.5" compare by their numbers. A version without
+    # a number (a "master" build) counts as newest.
+    VERSION_NUMBER = '#{?#{m/r:[0-9]+[.][0-9]+,#{version}},' \
+      '#{e|+:#{e|*:#{s/^[^0-9]*([0-9]+)[.]([0-9]+).*$/\1/:version},1000},' \
+      '#{s/^[^0-9]*([0-9]+)[.]([0-9]+).*$/\2/:version}},999999}'
+
+    # Thresholds from 3.2 compare numerically with #{e|...}. tmux before 3.2
+    # expands that to empty, which reads as "not at least", so "below" is
+    # written as its negation and stays correct there. Older thresholds compare
+    # the version string, which orders every 3.x and 4.x release correctly.
+    def version_condition(direction, version)
+      match = version.to_s.match(/\A(\d+)\.(\d+)\z/)
+      raise Error, "invalid tmux version: #{version.inspect} (expected \"major.minor\", e.g. \"3.2\")" unless match
+
+      major, minor = match.captures.map(&:to_i)
+      if major > 3 || (major == 3 && minor >= 2)
+        at_least = "#{'#{'}e|>=:#{VERSION_NUMBER},#{major * 1000 + minor}}"
+        direction == :from ? at_least : "#{'#{'}?#{at_least},0,1}"
+      else
+        "#{'#{'}#{direction == :from ? '>=' : '<'}:#{'#{'}version},#{major}.#{minor}}"
+      end
+    end
+  end
+end

data/lib/tmux/config_compiler.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Tmux
+  class ConfigCompiler
+    INDENT = "  "
+
+    class << self
+      def quote(value, expand: true)
+        return value.to_s if value.is_a?(Numeric)
+        return "on" if value.equal?(true)
+        return "off" if value.equal?(false)
+        escaped = value.to_s.gsub("\\") { "\\\\" }.gsub('"') { '\\"' }
+        escaped = escaped.gsub("$", "\\$").sub(/\A~/, "\\~") unless expand
+        "\"#{escaped}\""
+      end
+    end
+
+    def compile(nodes)
+      lines(nodes).join("\n") + "\n"
+    end
+
+    private
+
+    def lines(nodes)
+      nodes.flat_map do |node|
+        text = compile_node(node)
+        text.empty? ? [""] : text.split("\n", -1)
+      end
+    end
+
+    def compile_node(node)
+      case node
+      when ConfigNode::Blank then ""
+      when ConfigNode::Command then node.text
+      when ConfigNode::SetOption then compile_option(node)
+      when ConfigNode::UnsetOption then compile_unset(node)
+      when ConfigNode::IfShell then compile_if_shell(node)
+      when ConfigNode::Condition then compile_condition(node)
+      else raise Error, "unknown config node: #{node.inspect}"
+      end
+    end
+
+    def scope_flags(scope) = {global: "-g", window: "-gw", server: "-s"}.fetch(scope)
+
+    def compile_option(node)
+      flags = scope_flags(node.scope)
+      flags += "a" if node.append
+      value = node.value.is_a?(Format) ? node.value.to_tmux : node.value
+      "set-option #{flags} #{node.name} #{self.class.quote(value, expand: node.expand)}"
+    end
+
+    def compile_unset(node)
+      "set-option #{scope_flags(node.scope)}u #{node.name}"
+    end
+
+    # if-shell with { } command blocks, one command per line.
+    def compile_if_shell(node)
+      parts = ["if-shell"]
+      parts << "-b" if node.background
+      parts << "-F" if node.format
+      parts << self.class.quote(node.test)
+      text = "#{parts.join(' ')} #{block(node.success)}"
+      text += " #{block(node.failure)}" unless node.failure.empty?
+      text
+    end
+
+    def block(nodes)
+      body = lines(nodes).map { |line| line.empty? ? line : "#{INDENT}#{line}" }
+      ["{", *body, "}"].join("\n")
+    end
+
+    # The condition is generated by tmux.rb and never contains a single quote;
+    # single quotes keep tmux from treating its backslashes as escapes.
+    def compile_condition(node)
+      text = ["%if '#{node.condition}'", *lines(node.body)]
+      text.concat(["%else", *lines(node.otherwise)]) unless node.otherwise.empty?
+      text << "%endif"
+      text.join("\n")
+    end
+  end
+  private_constant :ConfigCompiler
+end

data/lib/tmux/dsl.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Tmux
+  # Builds a Tmux::Format. The block runs on a FormatBuilder; give it one
+  # parameter (`do |f| ... end`) to keep Ruby's normal scoping instead.
+  def self.format(&block)
+    builder = FormatBuilder.new
+    Evaluation.run(builder, block)
+    builder.build
+  end
+
+  # A reusable conditional format, with the same elsif? / else chain as if?
+  # inside a format block.
+  def self.if?(condition, &block)
+    builder = FormatBuilder.new
+    ConditionalFormat.new(builder, builder.if?(condition, &block))
+  end
+
+  # left/centre/right zones assembled into one aligned format (see ZoneBuilder).
+  def self.pane_border(&block)
+    builder = ZoneBuilder.new
+    Evaluation.run(builder, block)
+    builder.to_format
+  end
+
+  # Builds a Tmux::Config. The block runs on a ConfigBuilder; give it one
+  # parameter (`do |c| ... end`) to keep Ruby's normal scoping instead.
+  def self.configure(tmux: nil, &block)
+    target = tmux ? Target.for_executable(tmux) : Target.current
+    Target.with(target) do
+      builder = ConfigBuilder.new(target: target)
+      Evaluation.run(builder, block)
+      builder.build
+    end
+  end
+
+  # Coerces tmux format source: an Expression, or a String, Symbol, or Numeric
+  # used verbatim. Ruby booleans and nil cannot represent runtime conditions.
+  def self.expression(value)
+    case value
+    when Expression then value
+    when String, Symbol, Numeric then raw(value)
+    when true, false, nil
+      raise Error, "expected a tmux expression, got #{value.inspect}; " \
+        "use a tmux variable or expression comparison"
+    else
+      raise Error, "expected a tmux expression, String, Symbol, or Numeric, got #{value.class}"
+    end
+  end
+
+  # An Expression from raw tmux format source, e.g. Tmux.raw("#{pane_id}").
+  def self.raw(source) = Expression.new(source.to_s)
+
+  # A deferred shell exit-status check for configuration conditionals.
+  def self.shell(command, background: false)
+    ShellCondition.new(command.to_s, background)
+  end
+
+  # A runtime conditional color/value, e.g.
+  #   switch(prefix => colors.orange, copy_mode => colors.green, else: colors.tab)
+  # compiles to #{?client_prefix,#ff8800,#{?pane_in_mode,#6a9955,#2d2d30}} — a
+  # single expression usable anywhere a color is (fg:/bg:), so one mapping can
+  # drive several attributes. The first case is the outermost condition; `else:`
+  # is the fallback and is required. Values are tmux format source (colors,
+  # expressions, or #{...} strings); stray "," and "}" are escaped, and so is
+  # the "#" of an upper-case hex color, which tmux would otherwise read as a
+  # variable like #F or #D once the branch is chosen.
+  def self.switch(cases)
+    default = cases.fetch(:else) { raise Error, "switch needs an else: value" }
+    branches = cases.reject { |condition, _| condition.equal?(:else) }
+    source = branches.reverse_each.reduce(switch_value(default)) do |rest, (condition, value)|
+      "#{'#{'}?#{expression(condition).condition_source},#{switch_value(value)},#{rest}}"
+    end
+    raw(source)
+  end
+
+  def self.switch_value(value)
+    source = Escape.structural(expression(value).source)
+    source.gsub(/(?<!#)#(?=[A-F][0-9A-Fa-f]{5}(?![0-9A-Za-z]))/, "##")
+  end
+  private_class_method :switch_value
+
+  def self.variable(name, shorthand: nil) = Variable.new(name, shorthand:)
+
+  # Built-in tmux format variables, exposed as readers on the Tmux module so
+  # any config can reach them directly (e.g. Tmux.pane_current_path). Keyed by
+  # tmux's own variable name; the value is a shorthand (#S) where tmux has one.
+  STANDARD_VARIABLES = {
+    client_prefix: nil,
+    pane_in_mode: nil,
+    pane_input_off: nil,
+    pane_mode: nil,
+    pane_active: nil,
+    pane_index: nil,
+    pane_current_path: nil,
+    pane_current_command: nil,
+    pane_synchronized: nil,
+    window_zoomed_flag: nil,
+    window_index: "#I",
+    window_name: "#W",
+    session_name: "#S",
+    host: "#H",
+    host_short: "#h"
+  }.freeze
+
+  STANDARD_VARIABLES.each do |variable_name, shorthand|
+    define_singleton_method(variable_name) { variable(variable_name, shorthand:) }
+  end
+
+  def self.user_option(name)
+    option = normalize_user_option(name)
+    Expression.new("#{'#{'}#{option}}", condition_source: option)
+  end
+
+  def self.normalize_user_option(name)
+    "@#{name.to_s.delete_prefix('@')}"
+  end
+end

data/lib/tmux/errors.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tmux
+  class Error < StandardError; end
+end

data/lib/tmux/escape.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Tmux
+  # tmux format escaping. "#" is tmux's escape character: "##", "#," and "#}"
+  # stand for a literal "#", "," and "}". Inside a conditional branch (or an
+  # operator argument) an unescaped "," or "}" ends that branch, so content
+  # placed there needs all three escaped. Escapes do not compound with nesting:
+  # tmux unescapes each branch once, when it expands the branch it chose.
+  module Escape
+    module_function
+
+    # Literal text that tmux must not interpret at all.
+    def literal(value, branch: false)
+      escaped = value.to_s.gsub("#", "##")
+      branch ? escaped.gsub(",", "#,").gsub("}", "#}") : escaped
+    end
+
+    # Format source (#{...}, #[...], #(...) written on purpose) placed inside
+    # a branch: only the "," and "}" outside any #{...} would end the branch,
+    # so only those are escaped. Existing "#x" escapes are left alone.
+    def structural(source)
+      result = +""
+      each_top_level(source) do |token, top_level|
+        # A lone trailing "#" would escape whatever follows the branch.
+        result << (top_level && [",", "}", "#"].include?(token) ? "##{token}" : token)
+      end
+      result
+    end
+
+    # tmux matches parentheses inside #(...), so "$(cmd)" is fine, but an
+    # unmatched ")" ends the command early (and "(" swallows the rest of the
+    # format). tmux counts them everywhere, even inside #{...}, and neither can
+    # be escaped.
+    def unbalanced_parens?(source)
+      depth = 0
+      source.to_s.each_char do |char|
+        depth += 1 if char == "("
+        depth -= 1 if char == ")"
+        return true if depth.negative?
+      end
+      !depth.zero?
+    end
+
+    # Yields each character (or two-character "#x" sequence) with whether it
+    # sits outside every #{...}.
+    def each_top_level(source)
+      chars = source.to_s.chars
+      depth = 0
+      index = 0
+      while index < chars.length
+        if chars[index] == "#" && index + 1 < chars.length
+          token = chars[index, 2].join
+          yield token, depth.zero?
+          depth += 1 if token == '#{'
+          index += 2
+        elsif chars[index] == "}" && depth.positive?
+          depth -= 1
+          yield "}", false
+          index += 1
+        else
+          yield chars[index], depth.zero?
+          index += 1
+        end
+      end
+    end
+  end
+  private_constant :Escape
+end

data/lib/tmux/evaluation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Tmux
+  # How DSL blocks run. A block without parameters is instance_exec'd on the
+  # builder, so builder methods can be called bare. A block that takes one
+  # parameter (`do |c| ... end`) is called with the builder instead, keeping
+  # Ruby's normal scoping for self, instance variables, and methods.
+  module Evaluation
+    def self.run(target, block)
+      block.arity == 1 ? block.call(target) : target.instance_exec(&block)
+    end
+
+    private
+
+    def evaluate(block) = Evaluation.run(self, block)
+  end
+  private_constant :Evaluation
+end

data/lib/tmux/expression.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Tmux
+  class Expression
+    attr_reader :source, :condition_source
+
+    def initialize(source, condition_source: source)
+      @source = source
+      @condition_source = condition_source
+    end
+
+    # The tmux source, so expressions interpolate into text, binding commands,
+    # and `append` source: "#{Tmux.session_name}" is "#{session_name}".
+    def to_s = source
+
+    # Logical negation. Written as #{?expr,0,1} because tmux's own #{!:...}
+    # only exists from tmux 3.6.
+    def ! = Expression.new("#{'#{'}?#{condition_source},0,1}")
+
+    # String comparisons build tmux expressions, rather than Ruby booleans.
+    def ==(other) = compare("==", other)
+    def !=(other) = compare("!=", other)
+    alias_method :eq, :==
+    alias_method :not_eq, :!=
+
+    # Structural equality for hashes and the library's format/style snapshots.
+    def eql?(other)
+      other.is_a?(Expression) && source.eql?(other.source) && condition_source.eql?(other.condition_source)
+    end
+    def hash = [Expression, source, condition_source].hash
+
+    # Numeric comparisons (#{e|>:...}, tmux 3.2+); tmux's plain #{>:...}
+    # compares strings, so 10 would sort before 9.
+    def >(other) = compare("e|>", other)
+    def <(other) = compare("e|<", other)
+    def >=(other) = compare("e|>=", other)
+    def <=(other) = compare("e|<=", other)
+
+    # Regex match. A String pattern is literal regex text; the compiler escapes
+    # the characters tmux itself would interpret.
+    def matches(pattern)
+      Expression.new("#{'#{'}m/r:#{argument(pattern)},#{source}}")
+    end
+
+    # Regex substitution. The delimiter is chosen automatically from characters
+    # absent in the pattern and replacement, since tmux cannot escape it. A ":"
+    # cannot appear in either: tmux ends the modifier there.
+    def substitute(pattern, replacement)
+      pattern = argument(pattern)
+      replacement = argument(replacement)
+      if pattern.include?(":") || replacement.include?(":")
+        raise Error, "tmux's substitute modifier cannot contain \":\" (got #{pattern.inspect} -> #{replacement.inspect})"
+      end
+      delimiter = SUBSTITUTE_DELIMITERS.find do |candidate|
+        !pattern.include?(candidate) && !replacement.include?(candidate)
+      end
+      raise Error, "substitute pattern and replacement use every delimiter (#{SUBSTITUTE_DELIMITERS.join})" unless delimiter
+
+      d = delimiter
+      Expression.new("#{'#{'}s#{d}#{pattern}#{d}#{replacement}#{d}:#{subject_source}}")
+    end
+
+    SUBSTITUTE_DELIMITERS = %w[| / ! @ ~ + = ^ &].freeze
+
+    private
+
+    # The text after a modifier's ":" — a bare variable name when possible,
+    # otherwise the full nested format (which tmux expands).
+    def subject_source
+      source.match?(/\A#\{[^{}:]+\}\z/) ? source[2...-1] : source
+    end
+
+    def argument(value)
+      return value.source if value.is_a?(Expression)
+      return Escape.literal(value, branch: true) if value.is_a?(String) || value.is_a?(Symbol) || value.is_a?(Numeric)
+
+      raise Error, "expected an expression, String, Symbol, or Numeric operand, got #{value.inspect}"
+    end
+
+    def operation(operator, other)
+      Expression.new("#{'#{'}#{operator}:#{source},#{Tmux.expression(other).source}}")
+    end
+
+    # Comparison operands that aren't expressions are literal values.
+    def compare(operator, other)
+      Expression.new("#{'#{'}#{operator}:#{source},#{argument(other)}}")
+    end
+  end
+
+  # A single built-in tmux format variable, e.g. #{pane_current_path}. Behaves
+  # as an Expression, so comparisons, #substitute and #matches all work on it.
+  class Variable < Expression
+    attr_reader :name, :shorthand
+
+    def initialize(name, shorthand: nil)
+      @name = name
+      @shorthand = shorthand
+      super(shorthand || "#{'#{'}#{name}}", condition_source: name.to_s)
+    end
+
+    # Always the long form, which is unambiguous wherever it is embedded and
+    # which FormatBuilder#text recognizes as a dynamic part.
+    def to_s = "#{'#{'}#{name}}"
+
+    private
+
+    def subject_source = name.to_s
+  end
+end