tmux 0.1.0

data/lib/tmux/format_compiler.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Tmux
+  # Formats are compiled for the places tmux expands them with the time
+  # (status line, window tabs, pane borders, titles, display-message): tmux
+  # runs strftime over the top level and again over each conditional branch it
+  # chooses, so a literal "%" in text needs doubling once per level.
+  class FormatCompiler
+    def compile(nodes, depth: 0)
+      nodes.map { |node| compile_node(node, depth) }.join
+    end
+
+    private
+
+    def compile_node(node, depth)
+      branch = depth.positive?
+      case node
+      when Node::Text
+        Escape.literal(node.value, branch:).gsub("%", "%" * (2**(depth + 1)))
+      when Node::Strftime
+        Escape.literal(node.value, branch:)
+      when Node::Dynamic
+        branch ? Escape.structural(node.expression.source) : node.expression.source
+      when Node::Style
+        "#[#{node.attributes.join(branch ? '#,' : ',')}]"
+      when Node::ExpandOption
+        "#{'#{'}E:#{node.name}}"
+      when Node::Command
+        "#(#{branch ? Escape.structural(node.command) : node.command})"
+      when Node::Conditional
+        condition = node.condition.condition_source
+        on_true = compile(node.on_true, depth: depth + 1)
+        on_false = compile(node.on_false, depth: depth + 1)
+        "#{'#{'}?#{condition},#{on_true},#{on_false}}"
+      else
+        raise Error, "unknown format node: #{node.inspect}"
+      end
+    end
+  end
+  private_constant :FormatCompiler
+end

data/lib/tmux/glyph.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Tmux
+  # Named edge/separator glyphs (Powerline private-use codepoints), so configs
+  # write `:left_triangle` instead of an opaque "\u{e0b2}". Referenced by name in
+  # the flag helpers, or reachable directly as Tmux::Glyph::LEFT_TRIANGLE.
+  module Glyph
+    CHARS = {
+      right_triangle: "\u{e0b0}", right_thin: "\u{e0b1}",
+      left_triangle: "\u{e0b2}",  left_thin: "\u{e0b3}",
+      right_round: "\u{e0b4}",    right_round_thin: "\u{e0b5}",
+      left_round: "\u{e0b6}",     left_round_thin: "\u{e0b7}",
+      lower_left_triangle: "\u{e0b8}", upper_left_triangle: "\u{e0bc}",
+      lower_right_triangle: "\u{e0ba}", upper_right_triangle: "\u{e0be}"
+    }.freeze
+    CHARS.each { |name, char| const_set(name.to_s.upcase, char) }
+
+    # Shapes describe an edge independently of its position. A slant keeps
+    # its slope on both sides, using complementary filled triangles.
+    SHAPES = {
+      triangle: {left: :left_triangle, right: :right_triangle},
+      thin: {left: :left_thin, right: :right_thin},
+      round: {left: :left_round, right: :right_round},
+      round_thin: {left: :left_round_thin, right: :right_round_thin},
+      rslant: {left: :lower_right_triangle, right: :upper_left_triangle},
+      lslant: {left: :upper_right_triangle, right: :lower_left_triangle}
+    }.transform_values(&:freeze).freeze
+    private_constant :SHAPES
+
+    THIN_GLYPHS = CHARS.values_at(:left_thin, :right_thin, :left_round_thin, :right_round_thin).freeze
+    private_constant :THIN_GLYPHS
+
+    def self.[](name) = CHARS.fetch(name) { raise Error, "unknown glyph: #{name}" }
+    def self.thin?(glyph) = THIN_GLYPHS.include?(glyph)
+
+    def self.resolve(value, side: nil)
+      return value.to_s unless value.is_a?(Symbol)
+
+      if (shape = SHAPES[value])
+        value = shape.fetch(side) { raise Error, "glyph #{value.inspect} needs a side (:left or :right)" }
+      end
+      self[value]
+    end
+  end
+end

data/lib/tmux/option_tree.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Tmux
+  def self.style_string(attributes)
+    attributes.flat_map do |name, value|
+      case name
+      when :attrs then Array(value).map(&:to_s)
+      when :fg, :bg
+        raise Error, "style #{name}: needs a color, got nil" if value.nil?
+
+        "#{name}=#{value}"
+      else raise Error, "unknown style attribute: #{name}"
+      end
+    end.join(",")
+  end
+
+  class OptionNode
+    def self.root(builder, scope)
+      root = {children: {}, prefix: nil}
+      builder.target.catalog.scopes.fetch(scope).each do |name, metadata|
+        parts = name.split("-")
+        paths = [parts]
+        paths << parts.drop(1) if scope == :window && parts.first == "window"
+        paths.each do |path|
+          node = root
+          offset = parts.length - path.length
+          path.each_with_index do |key, index|
+            node = (node[:children][key.to_sym] ||= {
+              children: {}, prefix: parts.take(index + offset + 1).join("-")
+            })
+          end
+          node.merge!(option: name, array: metadata[:array], style: style?(name))
+        end
+      end
+      # Ergonomic aliases, not a list of valid options. Their availability is
+      # still checked against the selected target, including in version gates.
+      if scope == :window
+        clock = root[:children][:clock] ||= {children: {}, prefix: "clock"}
+        clock[:children][:colour] = {children: {}, prefix: "clock-mode-colour", option: "clock-mode-colour"}
+        clock[:children][:hour_format] = {children: {}, prefix: "clock-mode-style", option: "clock-mode-style"}
+      end
+      new(builder, root, scope: scope)
+    end
+
+    def self.style?(name) = name.end_with?("-style") && name != "clock-mode-style"
+
+    def initialize(builder, descriptor, scope:)
+      @builder = builder
+      @descriptor = descriptor
+      @scope = scope
+      # Kernel#display otherwise swallows namespaces such as display-panes.
+      # Exact-name brackets remain available for collisions with this proxy's
+      # own API (for example a future option literally named "set").
+      inherited = Object.public_instance_methods - OptionNode.public_instance_methods(false)
+      (descriptor[:children].keys & inherited).each do |key|
+        define_singleton_method(key) do |*arguments|
+          raise Error, "#{key} takes no arguments" unless arguments.empty?
+
+          node_for(key.to_s)
+        end
+      end
+    end
+
+    def <<(value)
+      write(value, append: true)
+      self
+    end
+
+    def unset
+      @builder.__send__(:remove_option, settable!("unset"), scope: @scope)
+    end
+
+    def set(*arguments, append: false, expand: true)
+      return node_for("set") if arguments.empty? && known_child("set")
+      raise Error, "set expects one value" unless arguments.length == 1
+
+      write(arguments.first, append: append, expand: expand)
+      self
+    end
+
+    # Exact tmux names also cover custom @options and names that collide with
+    # Ruby methods. On a leaf, integer indexing selects a tmux array element.
+    def [](key)
+      name = if @descriptor[:prefix].nil?
+        key.to_s.start_with?("@") ? key.to_s : key.to_s.tr("_", "-")
+      else
+        unless key.is_a?(Integer) && key >= 0
+          raise Error, "option array index must be a nonnegative Integer"
+        end
+        "#{settable!('[]')}[#{key}]"
+      end
+      OptionNode.new(@builder, {children: {}, prefix: name, option: name, style: OptionNode.style?(name)}, scope: @scope)
+    end
+
+    def []=(key, value)
+      self[key].__send__(:write, value)
+      value
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      !!known_child(name.to_s.delete_suffix("=")) || super
+    end
+
+    def method_missing(name, *arguments)
+      key = name.to_s
+      if key.end_with?("=")
+        raise Error, "#{key} expects one value" unless arguments.length == 1
+
+        node_for(key.delete_suffix("=")).__send__(:write, arguments.first)
+        return arguments.first
+      end
+      raise Error, "#{key} takes no arguments" unless arguments.empty?
+
+      node_for(key)
+    end
+
+    private
+
+    def known_child(key)
+      return @descriptor[:children][key.to_sym] if @descriptor[:children].key?(key.to_sym)
+
+      key.split("_").reduce(@descriptor) { |node, part| node && node[:children][part.to_sym] }
+    end
+
+    def node_for(key)
+      descriptor = known_child(key)
+      unless descriptor
+        prefix = [@descriptor[:prefix], key.tr("_", "-")].compact.join("-")
+        descriptor = {children: {}, prefix: prefix, style: OptionNode.style?(prefix)}
+      end
+      OptionNode.new(@builder, descriptor, scope: @scope)
+    end
+
+    def settable!(operation)
+      return @descriptor[:option] if @descriptor[:option]
+      return @descriptor[:prefix] if @descriptor[:children].empty? && @descriptor[:prefix]
+
+      raise Error, "#{operation} needs a settable option, not a namespace"
+    end
+
+    def write(value, append: false, expand: true)
+      name = settable!("assignment")
+      value = Tmux.style_string(value) if @descriptor[:style] && value.is_a?(Hash)
+      @builder.__send__(:write_option, name, value, scope: @scope, append: append, expand: expand)
+    end
+  end
+  private_constant :OptionNode
+end

data/lib/tmux/target.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+require "did_you_mean"
+
+module Tmux
+  # A target is an executable, not a guessed list keyed by a version string.
+  # Each discovered catalog belongs to the exact binary (including its stat),
+  # so changing PATH or replacing a binary cannot reuse another build's data.
+  class Target
+    CONTEXT_KEY = :tmux_rb_target
+
+    def self.current = Thread.current[CONTEXT_KEY] || for_executable("tmux")
+
+    def self.with(target)
+      previous = Thread.current[CONTEXT_KEY]
+      Thread.current[CONTEXT_KEY] = target
+      yield
+    ensure
+      Thread.current[CONTEXT_KEY] = previous
+    end
+
+    def self.for_executable(executable)
+      return executable if executable.is_a?(self)
+
+      name = executable.to_s
+      path = if name.include?(File::SEPARATOR)
+        File.expand_path(name)
+      else
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |dir| File.expand_path(name, dir) }
+          .find { |candidate| File.file?(candidate) && File.executable?(candidate) }
+      end
+      unless path && File.file?(path) && File.executable?(path)
+        raise Error, "tmux executable not found: #{name.inspect}; install tmux or select it with --tmux PATH"
+      end
+
+      real = File.realpath(path)
+      stat = File.stat(real)
+      key = [real, stat.ino, stat.size, stat.mtime, stat.ctime]
+      @targets ||= {}
+      @targets[key] ||= new(real)
+    end
+
+    attr_reader :executable
+
+    def initialize(executable)
+      @executable = executable
+    end
+
+    def version
+      @version ||= begin
+        output = run!("-V").strip
+        unless output.start_with?("tmux ") && output.length > 5
+          raise Error, "not a tmux executable: #{executable.inspect} (-V returned #{output.inspect})"
+        end
+        output.delete_prefix("tmux ")
+      end
+    end
+
+    def at_least?(threshold)
+      actual = version.match(/(\d+)\.(\d+)/)
+      return true unless actual # Match the DSL's treatment of unnumbered master builds.
+
+      expected = threshold.split(".").map(&:to_i)
+      (actual.captures.map(&:to_i) <=> expected) >= 0
+    end
+
+    def catalog
+      version
+      @catalog ||= isolated do |socket|
+        scopes = {global: "-g", server: "-s", window: "-gw"}.to_h do |scope, flags|
+          stdout, _stderr, status = run("-S", socket, "show-options", "#{flags}H")
+          stdout = run!("-S", socket, "show-options", flags) unless status.success?
+          [scope, OptionCatalog.parse(stdout)]
+        end
+        OptionCatalog.new(self, scopes)
+      end
+    end
+
+    # Resolve aliases using tmux itself. This also handles aliases introduced by
+    # newer builds, without maintaining a second hardcoded compatibility list.
+    def canonical_name(name)
+      isolated do |socket|
+        stdout, _stderr, status = run("-S", socket, "show-options", "-g", name)
+        next unless status.success?
+
+        stdout.lines.first&.split&.first&.sub(/\[\d+\]\z/, "")
+      end
+    end
+
+    def run(*arguments) = Open3.capture3(executable, *arguments)
+
+    def run!(*arguments)
+      stdout, stderr, status = run(*arguments)
+      raise Error, "tmux #{version_label} #{arguments.first} failed: #{stderr.strip}" unless status.success?
+
+      stdout
+    end
+
+    def isolated
+      Dir.mktmpdir("tmux-rb-options") do |directory|
+        socket = File.join(directory, "tmux.sock")
+        begin
+          run!("-S", socket, "-f", "/dev/null", "new-session", "-d", "-s", "tmux_rb_options", "sleep 3600")
+          yield socket
+        ensure
+          run("-S", socket, "kill-server")
+        end
+      end
+    end
+
+    private
+
+    def version_label = @version || executable
+  end
+
+  class OptionCatalog
+    def self.parse(output)
+      output.each_line.each_with_object({}) do |line, entries|
+        token, value = line.strip.split(/\s+/, 2)
+        next unless token&.match?(/\A[a-z0-9][a-z0-9-]*(?:\[\d+\])?\z/)
+
+        name = token.sub(/\[\d+\]\z/, "")
+        entries[name] = {array: token.include?("[") || value.nil?}.freeze
+      end.freeze
+    end
+
+    attr_reader :target, :scopes
+
+    def initialize(target, scopes)
+      @target = target
+      @scopes = scopes.freeze
+      @aliases = {}
+    end
+
+    def validate!(name, scope: nil)
+      return name if name.start_with?("@") && name.length > 1
+
+      match = name.match(/\A([a-z0-9][a-z0-9-]*)(?:\[(\d+)\])?\z/)
+      unknown!(name) unless match
+      base, index = match.captures
+      canonical = canonical(base)
+      unknown!(name) unless canonical
+      owners = scopes.keys.select { |owner| scopes.fetch(owner).key?(canonical) }
+      if scope && !owners.include?(scope)
+        raise Error, "#{name.inspect} is not a #{scope} option in tmux #{target.version}; " \
+          "use #{owners.first}.#{canonical.tr('-', '_')}"
+      end
+      if index && !scopes.fetch(owners.first).fetch(canonical).fetch(:array)
+        raise Error, "#{base.inspect} is not an array option in tmux #{target.version}"
+      end
+      name
+    end
+
+    private
+
+    def canonical(base)
+      return base if scopes.values.any? { |entries| entries.key?(base) }
+      return @aliases[base] if @aliases.key?(base)
+
+      resolved = target.canonical_name(base)
+      @aliases[base] = if resolved && scopes.values.any? { |entries| entries.key?(resolved) }
+        resolved
+      end
+    end
+
+    def unknown!(name)
+      suggestions = DidYouMean::SpellChecker.new(dictionary: scopes.values.flat_map(&:keys).uniq).correct(name)
+      hint = suggestions.empty? ? "" : "; did you mean #{suggestions.first.inspect}?"
+      raise Error, "unknown option #{name.inspect} for tmux #{target.version}#{hint}"
+    end
+  end
+
+  # Validate both shell branches (either may run), but only the applicable
+  # version branch. Imports are rechecked against the destination's target.
+  class OptionValidator
+    def initialize(target) = @target = target
+
+    def validate(nodes)
+      nodes.each do |node|
+        case node
+        when ConfigNode::SetOption, ConfigNode::UnsetOption
+          next if node.name.start_with?("@") && node.name.length > 1
+
+          @target.catalog.validate!(node.name, scope: node.scope)
+        when ConfigNode::IfShell
+          validate(node.success)
+          validate(node.failure)
+        when ConfigNode::Condition
+          active = @target.at_least?(node.version)
+          active = !active if node.direction == :below
+          validate(active ? node.body : node.otherwise)
+        end
+      end
+    end
+  end
+
+  private_constant :Target, :OptionCatalog, :OptionValidator
+end

data/lib/tmux/version.rb

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

data/lib/tmux/zone_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Tmux
+  # Collects left/centre/right zone blocks and assembles them, in that order
+  # regardless of definition order, into one aligned format — for a status line
+  # or pane border. Each zone's body is an ordinary format block.
+  class ZoneBuilder
+    def left(&block) = @left = block
+    def center(&block) = @center = block
+    def centre(&block) = @center = block
+    def right(&block) = @right = block
+
+    def to_format
+      left, center, right = @left, @center, @right
+      Tmux.format do
+        evaluate(left) if left
+        if center
+          reset_style
+          style attrs: "align=centre"
+          evaluate(center)
+        end
+        if right
+          reset_style
+          style attrs: "align=right"
+          evaluate(right)
+        end
+      end
+    end
+  end
+  private_constant :ZoneBuilder
+end

data/lib/tmux.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "tmux/version"
+require_relative "tmux/errors"
+require_relative "tmux/escape"
+require_relative "tmux/evaluation"
+require_relative "tmux/expression"
+require_relative "tmux/glyph"
+require_relative "tmux/format"
+require_relative "tmux/format_compiler"
+require_relative "tmux/format_builder"
+require_relative "tmux/zone_builder"
+require_relative "tmux/config"
+require_relative "tmux/config_compiler"
+require_relative "tmux/command_builder"
+require_relative "tmux/target"
+require_relative "tmux/config_builder"
+require_relative "tmux/option_tree"
+require_relative "tmux/condition_compiler"
+require_relative "tmux/dsl"
+
+module Tmux
+  # Evaluates a configuration file and returns the Tmux::Config or
+  # Tmux::Format its final expression produces. The file runs inside a fresh
+  # anonymous module, which keeps its constants and methods out of the global
+  # namespace. Configuration files are trusted Ruby: the module is not a
+  # sandbox. Logical operators in DSL conditions are captured before Ruby
+  # evaluates them, so && / || build deferred tmux expressions.
+  def self.load_file(path, tmux: nil)
+    target = tmux ? Target.for_executable(tmux) : Target.current
+    Target.with(target) { evaluate_file(path) }
+  end
+
+  def self.evaluate_file(path)
+    absolute = File.expand_path(path)
+    namespace = Module.new
+    # Top-level `def` helpers become callable from the file's own code,
+    # including blocks that take the builder as a parameter.
+    namespace.extend(namespace)
+    source = ConditionCompiler.rewrite(File.read(absolute), absolute)
+    result = namespace.module_eval(source, absolute)
+    return result if result.is_a?(Config) || result.is_a?(Format)
+
+    raise Error, "#{path} must evaluate to a Tmux::Config or Tmux::Format"
+  end
+  private_class_method :evaluate_file
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: tmux
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nick deLannoy
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.19'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: |
+  tmux.rb compiles structured Ruby into deterministic tmux configuration and
+  format strings. Ruby runs only while building; tmux evaluates the output
+  natively, so status rendering never spawns Ruby.
+executables:
+- tmux.rb
+- tmux_rb
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/tmux.rb
+- bin/tmux_rb
+- lib/tmux.rb
+- lib/tmux/cli.rb
+- lib/tmux/command_builder.rb
+- lib/tmux/condition_compiler.rb
+- lib/tmux/config.rb
+- lib/tmux/config_builder.rb
+- lib/tmux/config_compiler.rb
+- lib/tmux/dsl.rb
+- lib/tmux/errors.rb
+- lib/tmux/escape.rb
+- lib/tmux/evaluation.rb
+- lib/tmux/expression.rb
+- lib/tmux/format.rb
+- lib/tmux/format_builder.rb
+- lib/tmux/format_compiler.rb
+- lib/tmux/glyph.rb
+- lib/tmux/option_tree.rb
+- lib/tmux/target.rb
+- lib/tmux/version.rb
+- lib/tmux/zone_builder.rb
+homepage: https://github.com/cosmicbuffalo/tmux.rb
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/cosmicbuffalo/tmux.rb
+  changelog_uri: https://github.com/cosmicbuffalo/tmux.rb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/cosmicbuffalo/tmux.rb/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A readable Ruby DSL that compiles to native tmux configuration
+test_files: []