tmux 0.1.0

data/bin/tmux.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "tmux/cli"
+
+exit Tmux::CLI.run(ARGV)

data/bin/tmux_rb

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+# Another name for tmux.rb.
+load File.expand_path("tmux.rb", __dir__)

data/lib/tmux/cli.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "optparse"
+require "securerandom"
+require "tempfile"
+require "tmpdir"
+require_relative "../tmux"
+
+module Tmux
+  # The tmux.rb command (also installed as tmux_rb). #run returns an exit status and never exits the
+  # process, so it is safe to call from other Ruby code.
+  class CLI
+    def self.run(arguments, stdout: $stdout, stderr: $stderr)
+      new(stdout:, stderr:).run(arguments)
+    end
+
+    def initialize(stdout:, stderr:)
+      @stdout = stdout
+      @stderr = stderr
+      @tmux_executable = "tmux"
+    end
+
+    def run(arguments)
+      arguments = arguments.dup
+      command = arguments.shift
+      case command
+      when "build" then build(arguments)
+      when "check" then check(arguments)
+      when "diff" then diff(arguments)
+      when "load" then load_config(arguments)
+      when "-v", "--version", "version"
+        @stdout.puts version_line
+        0
+      when "-h", "--help", "help"
+        @stdout.puts usage
+        0
+      else
+        @stderr.puts "tmux.rb: unknown command: #{command}" if command
+        @stderr.puts usage
+        2
+      end
+    rescue OptionParser::ParseError, Error, SystemCallError => error
+      @stderr.puts "tmux.rb: #{error.message}"
+      1
+    end
+
+    private
+
+    def build(arguments)
+      output = nil
+      return 0 unless parse_options(arguments, "build CONFIG.rb [--output TMUX.conf]") do |opts|
+        opts.on("-o", "--output PATH", "Write atomically to PATH instead of stdout") { |path| output = path }
+      end
+
+      rendered = render(require_source!(arguments))
+      output ? atomic_write(output, rendered) : @stdout.write(rendered)
+      0
+    end
+
+    def check(arguments)
+      return 0 unless parse_options(arguments, "check CONFIG.rb")
+
+      source = require_source!(arguments)
+      object = load_source(source)
+      if object.is_a?(Format)
+        @stdout.puts "#{source}: compiled to a format; formats are only parsed by tmux when it renders them"
+        return 0
+      end
+
+      validate_with_tmux(object.to_tmux, target: object.target)
+      @stdout.puts "#{source}: tmux parsed the generated configuration " \
+        "(option names validated; commands and values were not applied)"
+      0
+    end
+
+    def diff(arguments)
+      return 0 unless parse_options(arguments, "diff CONFIG.rb TMUX.conf")
+
+      source, target = arguments
+      raise Error, "usage: tmux.rb diff CONFIG.rb TMUX.conf" unless source && target && arguments.size == 2
+
+      Tempfile.create(["tmux_rb", ".conf"]) do |file|
+        file.write(render(source))
+        file.flush
+        stdout, stderr, status = Open3.capture3("diff", "-u", target, file.path)
+        @stdout.write(stdout)
+        @stderr.write(stderr)
+        return status.exitstatus || 2
+      end
+    end
+
+    def load_config(arguments)
+      target = []
+      return 0 unless parse_options(arguments, "load [-S SOCKET | -L NAME] CONFIG.rb") do |opts|
+        opts.on("-S", "--socket PATH", "Load into the server at this socket path") { |path| target = ["-S", path] }
+        opts.on("-L", "--socket-name NAME", "Load into the server with this socket name") { |name| target = ["-L", name] }
+      end
+
+      source = require_source!(arguments)
+      object = load_source(source)
+      raise Error, "#{source} must evaluate to a Tmux::Config" unless object.is_a?(Config)
+
+      server_version = object.target.run!(*target, "display-message", "-p", '#{version}').strip
+      unless server_version == object.target.version
+        raise Error, "destination server is tmux #{server_version}, but this config targets tmux #{object.target.version}; " \
+          "select a matching executable with --tmux PATH"
+      end
+
+      Tempfile.create(["tmux_rb-load", ".conf"]) do |file|
+        file.write(object.to_tmux)
+        file.flush
+        stdout, stderr, status = object.target.run(*target, "source-file", file.path)
+        raise Error, "tmux rejected generated config:\n#{stderr}#{stdout}" unless status.success?
+      end
+      0
+    end
+
+    # Parses a subcommand's options. Returns false after printing help or the
+    # version, so the caller can return 0 without exiting the process.
+    def parse_options(arguments, synopsis)
+      early = nil
+      parser = OptionParser.new do |opts|
+        opts.banner = "usage: tmux.rb #{synopsis}"
+        yield opts if block_given?
+        opts.on("--tmux PATH", "Target this tmux executable (default: tmux on PATH)") { |path| @tmux_executable = path }
+        opts.on("-h", "--help", "Show this help") { early = :help }
+        opts.on("--version", "Show the tmux.rb version") { early = :version }
+      end
+      parser.parse!(arguments)
+      @stdout.puts(early == :help ? parser.help : version_line) if early
+      early.nil?
+    end
+
+    def require_source!(arguments)
+      source = arguments.shift
+      raise Error, "expected exactly one Ruby configuration path" unless source && arguments.empty?
+
+      source
+    end
+
+    def render(path) = load_source(path).to_tmux
+
+    # Errors raised while the configuration runs are reported with the line
+    # in the configuration file that raised them.
+    def load_source(path)
+      Tmux.load_file(path, tmux: @tmux_executable)
+    rescue SyntaxError => error
+      raise Error, error.message
+    rescue StandardError, ScriptError => error
+      location = location_in(error, File.expand_path(path))
+      raise if location.nil? && (error.is_a?(Error) || error.is_a?(SystemCallError))
+
+      raise Error, "#{location || path}: #{error.message} (#{error.class})"
+    end
+
+    # The innermost backtrace frame inside the configuration file itself.
+    def location_in(error, path)
+      frame = error.backtrace_locations&.find { |location| location.absolute_path == path || location.path == path }
+      frame && "#{frame.path}:#{frame.lineno}"
+    end
+
+    # Writes beside the real destination, then renames over it, so readers
+    # never see a partial file. A symlinked destination (e.g. ~/.tmux.conf
+    # pointing into a dotfiles repository) is followed rather than replaced,
+    # and an existing file keeps its permissions.
+    def atomic_write(path, contents)
+      destination = resolve_symlinks(path)
+      temporary = nil
+      FileUtils.mkdir_p(File.dirname(destination))
+      mode = File.exist?(destination) ? File.stat(destination).mode & 0o7777 : nil
+      temporary = "#{destination}.tmp-#{Process.pid}-#{SecureRandom.hex(4)}"
+      File.open(temporary, "w") do |file|
+        file.write(contents)
+        file.fsync
+      end
+      File.chmod(mode, temporary) if mode
+      File.rename(temporary, destination)
+    ensure
+      FileUtils.rm_f(temporary) if temporary
+    end
+
+    def resolve_symlinks(path)
+      target = File.expand_path(path)
+      40.times do
+        return target unless File.symlink?(target)
+
+        target = File.expand_path(File.readlink(target), File.dirname(target))
+      end
+      raise Error, "too many levels of symbolic links: #{path}"
+    end
+
+    # The throwaway server's socket lives in a temporary directory, because
+    # tmux leaves its socket file behind when the server is killed, and its
+    # session runs `sleep` so the user's shell and rc files never start.
+    def validate_with_tmux(contents, target:)
+      Dir.mktmpdir("tmux_rb-check") do |directory|
+        config = File.join(directory, "check.conf")
+        File.write(config, contents)
+        target.isolated do |socket|
+          stdout, stderr, status = target.run("-S", socket, "source-file", "-n", config)
+          raise Error, "tmux rejected generated config:\n#{stderr}#{stdout}" unless status.success?
+        end
+      end
+    end
+
+    def version_line = "tmux.rb #{VERSION}"
+
+    def usage
+      <<~TEXT
+        usage:
+          tmux.rb build CONFIG.rb [--output TMUX.conf]
+          tmux.rb check CONFIG.rb
+          tmux.rb diff CONFIG.rb TMUX.conf
+          tmux.rb load [-S SOCKET | -L NAME] CONFIG.rb
+          tmux.rb --version
+
+        Run `tmux.rb COMMAND --help` for a command's options.
+        All commands accept --tmux PATH to select the target tmux executable.
+      TEXT
+    end
+  end
+end

data/lib/tmux/command_builder.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Tmux
+  class MenuBuilder
+    def initialize = @entries = []
+
+    def item(label, key:, command: nil, &block)
+      raise Error, "menu item accepts either a command or a block, not both" if command && block
+
+      if block
+        builder = CommandBuilder.new
+        Evaluation.run(builder, block)
+        command = builder.build
+      end
+      raise Error, "menu item requires a command or block" unless command
+
+      @entries << [label.to_s, key.to_s, command.to_s]
+      self
+    end
+
+    def separator
+      @entries << [""]
+      self
+    end
+
+    def arguments = @entries.flatten
+  end
+
+  # Builds the command list attached to a key binding. Commands are kept as
+  # separate entries until the binding is compiled, so callers never write tmux
+  # command separators or quote command arguments by hand.
+  class CommandBuilder
+    def initialize = @commands = []
+
+    # Any tmux command. Arguments are quoted for you; tmux expands $VARIABLES
+    # and a leading ~ in them unless `expand: false` is passed.
+    def command(name, *arguments, expand: true)
+      command_name = normalize(name)
+      parts = [command_name, *arguments.map { |argument| ConfigCompiler.quote(argument, expand:) }]
+      @commands << parts.join(" ")
+      self
+    end
+
+    def raw(command)
+      @commands << command.to_s
+      self
+    end
+
+    def select_pane(target: nil)
+      parts = ["select-pane"]
+      parts.concat(["-t", ConfigCompiler.quote(target)]) if target
+      @commands << parts.join(" ")
+      self
+    end
+
+    # 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)
+      parts = ["send-keys"]
+      parts.concat(["-t", ConfigCompiler.quote(target)]) if target
+      parts << "-X"
+      parts.concat(["-N", count.to_i]) if count
+      parts << normalize(action)
+      @commands << parts.join(" ")
+      self
+    end
+
+    # Compile and load a Ruby configuration into the tmux server running this
+    # command. The CLI renders through a temporary file, so callers only
+    # maintain the .rb source. #{socket_path} expands when the binding runs, so
+    # the load never follows a $TMUX that names some other (e.g. nested) server.
+    def load_config(path, executable: "tmux.rb")
+      load = Shellwords.join([executable, "load", "-S"])
+      # expand: false: the shell, not tmux's parser, must see any "$" in the path.
+      command :run_shell, "#{load} \"\#{socket_path}\" #{Shellwords.escape(path.to_s)}", expand: false
+    end
+
+    def display_message(message)
+      command :display_message, message
+    end
+
+    def display_menu(title: nil, &block)
+      menu = MenuBuilder.new
+      Evaluation.run(menu, block)
+      parts = ["display-menu"]
+      parts.concat(["-T", ConfigCompiler.quote(title)]) if title
+      parts.concat(menu.arguments.map { |argument| ConfigCompiler.quote(argument) })
+      @commands << parts.join(" ")
+      self
+    end
+
+    def build
+      raise Error, "a command block must contain at least one command" if @commands.empty?
+
+      @commands.join(" \\; ")
+    end
+
+    private
+
+    def normalize(name) = name.to_s.tr("_", "-")
+  end
+end

data/lib/tmux/condition_compiler.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Tmux
+  # Capture Ruby syntax before && / || can discard symbolic operands. This is
+  # source translation, not an override of Ruby's truthiness or short circuiting.
+  class ConditionCompiler
+    EXPRESSION_NODES = %i[
+      and_node or_node call_node arguments_node parentheses_node statements_node
+      local_variable_read_node instance_variable_read_node constant_read_node
+      constant_path_node self_node string_node interpolated_string_node
+      embedded_statements_node symbol_node interpolated_symbol_node integer_node
+      float_node true_node false_node nil_node array_node hash_node
+      keyword_hash_node assoc_node
+    ].freeze
+
+    def self.rewrite(source, path)
+      compiler = new(source, path)
+      edits = compiler.nodes.flat_map do |node|
+        compiler.conditions(node).filter_map do |argument|
+          next unless compiler.logical?(argument)
+
+          compiler.validate!(argument)
+          [argument.location, compiler.render(argument)]
+        end
+      end
+      compiler.replace(nil, edits)
+    end
+
+    attr_reader :root
+
+    def initialize(source, path)
+      @source = source
+      @path = path
+      result = Prism.parse(source, filepath: path)
+      unless result.errors.empty?
+        error = result.errors.first
+        raise Error, "#{path}:#{error.location.start_line}: #{error.message}"
+      end
+      @root = result.value
+    end
+
+    def nodes(node = root)
+      [node] + node.compact_child_nodes.flat_map { |child| nodes(child) }
+    end
+
+    def logical?(node)
+      return false if %i[block_node lambda_node].include?(node.type)
+
+      %i[and_node or_node].include?(node.type) || node.compact_child_nodes.any? { |child| logical?(child) }
+    end
+
+    def conditions(node)
+      return [] unless node.type == :call_node
+
+      argument = node.arguments&.arguments&.first
+      return [] unless argument
+      return [argument] if %i[if? elsif?].include?(node.name)
+      return [] unless %i[switch switch_style].include?(node.name)
+      return [] unless %i[hash_node keyword_hash_node].include?(argument.type)
+
+      argument.elements.filter_map { |entry| entry.key if entry.type == :assoc_node }
+    end
+
+    def validate!(node)
+      unless node && EXPRESSION_NODES.include?(node.type)
+        fail_at(node, "condition needs a single expression; assignments and control flow are not supported")
+      end
+      if node.type == :statements_node && node.body.length != 1
+        fail_at(node, "condition needs a single expression")
+      end
+      if node.type == :call_node && (node.block || node.safe_navigation?)
+        fail_at(node, "blocks and safe navigation are not supported inside a condition")
+      end
+      if %i[and_node or_node].include?(node.type) && !%w[&& ||].include?(node.operator_loc.slice)
+        fail_at(node, "use && / || rather than and / or in a condition")
+      end
+      if node.compact_child_nodes.any? { |child| child.location.end_offset > node.location.end_offset }
+        fail_at(node, "heredocs are not supported inside a captured condition; use a string or local variable")
+      end
+      node.compact_child_nodes.each { |child| validate!(child) }
+    end
+
+    def render(node)
+      if %i[and_node or_node].include?(node.type)
+        operator = node.type == :and_node ? "&&" : "||"
+        edits = [
+          [node.left.location, "::Tmux.expression((#{render(node.left)})).__send__(:operation, #{operator.inspect}, ("],
+          [node.operator_loc, ""],
+          [node.right.location, "#{render(node.right)}))"]
+        ]
+        return replace(node.location, edits)
+      end
+
+      edits = node.compact_child_nodes.map { |child| [child.location, render(child)] }
+      replace(node.location, edits)
+    end
+
+    # Prism offsets count bytes, not characters. Keep comments, whitespace and
+    # newlines intact so Unicode and error backtraces retain their original lines.
+    # An outer edit already contains the rendering of any nested edits.
+    def replace(location, edits)
+      start_offset = location&.start_offset || 0
+      end_offset = location&.end_offset || @source.bytesize
+      result = @source.byteslice(start_offset...end_offset).b
+      boundary = start_offset
+      selected = edits.sort_by { |range, _| [range.start_offset, -range.length] }.select do |range, _|
+        next false if range.start_offset < boundary
+
+        boundary = range.end_offset
+        true
+      end
+      selected.reverse_each do |range, replacement|
+        result[range.start_offset - start_offset, range.length] = replacement.b
+      end
+      result.force_encoding(@source.encoding)
+    end
+
+    private
+
+    def fail_at(node, message)
+      raise Error, "#{@path}:#{node&.location&.start_line || 1}: #{message}"
+    end
+  end
+  private_constant :ConditionCompiler
+end

data/lib/tmux/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Tmux
+  ShellCondition = Data.define(:command, :background)
+  private_constant :ShellCondition
+
+  module ConfigNode
+    Blank = Data.define
+    Command = Data.define(:text)
+    SetOption = Data.define(:name, :value, :scope, :append, :expand)
+    UnsetOption = Data.define(:name, :scope)
+    IfShell = Data.define(:test, :success, :failure, :format, :background)
+    # A %if/%else/%endif block, evaluated by tmux while it parses the file.
+    Condition = Data.define(:condition, :body, :otherwise, :version, :direction)
+  end
+
+  # A compiled configuration. #nodes is the read-only configuration AST.
+  class Config
+    attr_reader :nodes, :target
+
+    def initialize(nodes, target: Target.current)
+      @nodes = nodes.freeze
+      @target = target
+    end
+
+    def validate!
+      OptionValidator.new(@target).validate(nodes)
+      self
+    end
+
+    def to_tmux
+      validate!
+      ConfigCompiler.new.compile(nodes)
+    end
+    alias_method :to_s, :to_tmux
+    def ==(other) = other.is_a?(Config) && nodes.eql?(other.nodes)
+    alias_method :eql?, :==
+    def hash = [self.class, nodes].hash
+  end
+end