appear 1.1.1 → 1.2.0

data/lib/appear/terminal.rb

@@ -0,0 +1,127 @@
+require 'appear/service'
+require 'appear/constants'
+
+module Appear
+  # A base service that retrieves a usable Terminal instance, suitable for
+  # spawning command-line programs.
+  class Terminals
+    def initialize(terminals)
+      @terminals = terminals
+    end
+
+    # Get the Terminal instance
+    #
+    # @return [Terminal::MacTerminal]
+    def get
+      current || default
+    end
+
+    private
+
+    def current
+      @terminals.find { |t| t.running? }
+    end
+
+    def default
+      # TODO: select terminals based on OS support or should that happen
+      # upstream? in the creator of the Terminals instance? No. It should
+      # happen here.
+      @terminals.find { |t| t.class == TerminalApp }
+    end
+  end
+
+  # This module contains Terminal service implementations. So far, we're only
+  # concerned with Mac usrs, so you can look at {MacTerminal} to read the
+  # interface.
+  module Terminal
+    # Base class for mac terminal support
+    class MacTerminal < Service
+      require_service :mac_os
+      require_service :processes
+
+      # @abstract subclasses must implement this method.
+      # @return [String] "app name" on OS X. Both the process name of processes
+      #   of this app, and the name used by Applescript to send events to this
+      #   app.
+      def app_name
+        raise NotImplemented
+      end
+
+      # @return [Boolean] true if the app has a running process, false
+      #   otherwise.
+      def running?
+        services.processes.pgrep(app_name).length > 0
+      end
+
+      # Enumerate the panes (seperate interactive sessions) that this terminal
+      # program has.
+      #
+      # @abstract subclasses must implement this method.
+      # @return [Array<#tty>] any objects with a tty field
+      def panes
+        raise NotImplemented
+      end
+
+      # Reveal a pane. Subclasses must implement this method.
+      #
+      # @abstract subclasses must implement this method.
+      # @param pane [#tty] any object with a tty field
+      def reveal_pane(pane)
+        raise NotImplemented
+      end
+    end # MacTerminal
+
+    # TerminalApp support service.
+    class TerminalApp < MacTerminal
+      # @see MacTerminal#app_name
+      def app_name
+        'Terminal'
+      end
+
+      # @see MacTerminal#panes
+      def panes
+        pids = services.processes.pgrep(app_name)
+        services.mac_os.call_method('terminal_panes').map do |hash|
+          hash[:pids] = pids
+          OpenStruct.new(hash)
+        end
+      end
+
+      # @see MacTerminal#reveal_pane
+      def reveal_pane(pane)
+        services.mac_os.call_method('terminal_reveal_tty', pane.tty)
+      end
+    end
+
+    # Iterm2 support service.
+    class Iterm2 < MacTerminal
+      # @see MacTerminal#app_name
+      def app_name
+        'iTerm2'
+      end
+
+      # @see MacTerminal#panes
+      def panes
+        pids = services.processes.pgrep(app_name)
+        services.mac_os.call_method('iterm2_panes').map do |hash|
+          hash[:pids] = pids
+          OpenStruct.new(hash)
+        end
+      end
+
+      # @see MacTerminal#reveal_pane
+      def reveal_pane(pane)
+        services.mac_os.call_method('iterm2_reveal_tty', pane.tty)
+      end
+
+      # Create a new window running the given command.
+      #
+      # @param command_str [String] command to run
+      # @return [#tty] pane
+      def new_window(command_str)
+        res = services.mac_os.call_method('iterm2_new_window', command_str)
+        OpenStruct.new(res)
+      end
+    end
+  end
+end

data/lib/appear/tmux.rb

@@ -1,5 +1,6 @@
-require 'ostruct'
 require 'appear/service'
+require 'appear/util/command_builder'
+require 'appear/util/value_class'
 
 module Appear
   # The Tmux service is in charge of interacting with `tmux` processes. It is
@@ -11,67 +12,312 @@ module Appear
   class Tmux < Service
     delegate :run, :runner
 
+    # Base value class for Tmux values. This class works in concert with the
+    # Tmux service to make a fluent Tmux API easy.
+    #
+    # TmuxValues all have a reference to the Tmux service that created them, so
+    # that they can implement methods that proxy Tmux service interaction.
+    class TmuxValue < ::Appear::Util::ValueClass
+      # @return [Tmux] the tmux service that created this pane
+      property :tmux
+
+      # @option opts [Symbol] :tmux tmux format string name of this attribute
+      # @option opts [#to_proc] :parse proc taking a String (read from tmux) and
+      # returns the type-coerced version of this field. A symbol can be used,
+      # just like with usual block syntax.
+      def self.property(name, opts = {})
+        var = super(name, opts)
+        @tmux_attrs ||= {}
+        @tmux_attrs[var] = opts if opts[:tmux]
+      end
+
+      # The format string we pass to Tmux when we expect a result of this
+      # class's type. This format string should cause Tmux to return a value we
+      # can hand to {self.parse}
+      #
+      # @return [String]
+      def self.format_string
+        result = ""
+        @tmux_attrs.each do |var, opts|
+          next unless opts[:tmux]
+          part = ' ' + var.to_s + ':#{' + opts[:tmux].to_s + '}'
+          result += part
+        end
+        result
+      end
+
+      # Parse a raw data has as returned by the {Tmux} service into an instance
+      # of this class.
+      #
+      # @param tmux_hash [Hash]
+      # @param tmux [Tmux] the tmux service
+      def self.parse(tmux_hash, tmux)
+        result = { :tmux => tmux }
+        tmux_hash.each do |var, tmux_val|
+          parser = @tmux_attrs[var][:parse]
+          if parser
+            result[var] = parser.to_proc.call(tmux_val)
+          else
+            result[var] = tmux_val
+          end
+        end
+        self.new(result)
+      end
+    end
+
+    # A tmux pane.
+    class Pane < TmuxValue
+      # @return [Fixnum] pid of the process running in the pane
+      property :pid, tmux: :pane_pid, parse: :to_i
+
+      # @return [String] session name
+      property :session, tmux: :session_name
+
+      # @return [Fixnum] window index
+      property :window, tmux: :window_index, parse: :to_i
+
+      # @return [Fixnum] pane index
+      property :pane, tmux: :pane_index, parse: :to_i
+
+      # @return [Boolean] is this pane the active pane in this session
+      property :active?, var: :active, tmux: :pane_active, parse: proc {|a| a.to_i != 0 }
+
+      # @return [String] command running in this pane
+      property :command_name, tmux: :pane_current_command
+
+      # @return [String] pane current path
+      property :current_path, tmux: :pane_current_path
+
+      # @return [String] window id
+      property :id, :tmux => :pane_id
+
+      # String suitable for use as the "target" specifier for a Tmux command
+      #
+      # @return [String]
+      def target
+        # "#{session}:#{window}.#{pane}"
+        id
+      end
+
+      # Split this pane
+      #
+      # @param opts [Hash]
+      def split(opts = {})
+        tmux.split_window(opts.merge(:t => target))
+      end
+
+      # Reveal this pane
+      def reveal
+        tmux.reveal_pane(self)
+      end
+
+      # Send keys to this pane
+      #
+      # @param keys [String]
+      # @param opts [Hash]
+      def send_keys(keys, opts = {})
+        tmux.send_keys(self, keys, opts)
+      end
+    end
+
+    # A tmux session.
+    # Has many windows.
+    class Session < TmuxValue
+      # @return [String] session name
+      property :session, tmux: :session_name
+
+      # @return [String] tmux id of this session
+      property :id, :tmux => :session_id
+
+      # @return [Fixnum] number of clients attached to this session
+      property :attached, :tmux => :session_attached, :parse => :to_i
+
+      # @return [Fixnum] width, in text columns
+      property :width, :tmux => :session_width, :parse => :to_i
+
+      # @return [Fixnum] height, in text rows
+      property :height, :tmux => :session_height, :parse => :to_i
+
+      # String suitable for use as the "target" specifier for a Tmux command
+      #
+      # @return [String]
+      def target
+        # session
+        id
+      end
+
+      # @return [Array<Window>] the windows in this session
+      def windows
+        tmux.windows.select { |w| w.session == session }
+      end
+
+      # @return [Array<Client>] all clients attached to this session
+      def clients
+        tmux.clients.select { |c| c.session == session }
+      end
+
+      # Create a new window in this session. By default, the window will be
+      # created at the end of the session.
+      #
+      # @param opts [Hash]
+      def new_window(opts = {})
+        win = windows.last.window || -1
+        tmux.new_window(opts.merge(:t => "#{target}:#{win + 1}"))
+      end
+    end
+
+    # A tmux window.
+    # Has many panes.
+    class Window < TmuxValue
+      # @return [String] session name
+      property :session, :tmux => :session_name
+
+      # @return [Fixnum] window index
+      property :window, :tmux => :window_index, :parse => :to_i
+
+      # @return [String] window id
+      property :id, :tmux => :window_id
+
+      # @return [Boolean] is the window active?
+      property :active?,
+        :tmux => :window_active,
+        :var => :active,
+        :parse => proc {|b| b.to_i != 0}
+
+      # @return [Array<Pane>]
+      def panes
+        tmux.panes.select { |p| p.session == session && p.window == window }
+      end
+
+      # String suitable for use as the "target" specifier for a Tmux command
+      #
+      # @return [String]
+      def target
+        # "#{session}:#{window}"
+        id
+      end
+    end
+
+    # A tmux client.
+    class Client < TmuxValue
+      # @return [String] path to the TTY device of this client
+      property :tty, :tmux => :client_tty
+
+      # @return [String] term name
+      property :term, :tmux => :client_termname
+
+      # @return [String] session name
+      property :session, :tmux => :client_session
+
+      # String suitable for use as the "target" specifier for a Tmux command
+      #
+      # @return [String]
+      def target
+        tty
+      end
+    end
+
+    def initialize(svcs = {})
+      super(svcs)
+      @memo = ::Appear::Util::Memoizer.new
+    end
+
+    # List all the tmux clients on the system
+    #
+    # @return [Array<Client>]
     def clients
-      ipc([
-        'list-clients',
-        '-F',
-        format_string(
-          :tty => :client_tty,
-          :term => :client_termname,
-          :session => :client_session
-      ),
-      ])
+      ipc_returning(command('list-clients'), Client)
     end
 
+    # List all the tmux panes on the system
+    #
+    # @return [Array<Pane>]
     def panes
-      panes = ipc([
-        'list-panes',
-        '-a',
-        '-F',
-        format_string(
-          :pid => :pane_pid,
-          :session => :session_name,
-          :window => :window_index,
-          :pane => :pane_index,
-          :command_name => :pane_current_command,
-          :active => :pane_active)
-      ])
+      ipc_returning(command('list-panes').flags(:a => true), Pane)
+    end
 
-      panes.each do |pane|
-        pane.window = pane.window.to_i
-        pane.pid = pane.pid.to_i
-        pane.active = pane.active.to_i != 0
-      end
+    # List all the tmux sessions on the system
+    #
+    # @return [Array<Session>]
+    def sessions
+      ipc_returning(command('list-sessions'), Session)
+    end
 
-      panes
+    # List all the tmux windows in any session on the system
+    #
+    # @return [Array<Window>]
+    def windows
+      ipc_returning(command('list-windows').flags(:a => true), Window)
     end
 
+    # Reveal a pane in tmux.
+    #
+    # @param pane [Pane] a pane
     def reveal_pane(pane)
-      ipc(['select-pane', '-t', "#{pane.session}:#{pane.window}.#{pane.pane}"])
-      ipc(['select-window', '-t', "#{pane.session}:#{pane.window}"])
+      ipc(command('select-pane').flags(:t => pane.target))
+      # TODO: how do we use a real target for this?
+      ipc(command('select-window').flags(:t => "#{pane.session}:#{pane.window}"))
+      pane
+    end
+
+    # Create a new window
+    def new_window(opts = {})
+      ipc_returning_one(command('new-window').flags(opts), Window)
+    end
+
+    # Split a window
+    def split_window(opts = {})
+      ipc_returning_one(command('split-window').flags(opts), Pane)
+    end
+
+    # Create a new session
+    def new_session(opts = {})
+      ipc_returning_one(command('new-session').flags(opts), Session)
+    end
+
+    # Send keys to a pane
+    def send_keys(pane, keys, opts = {})
+      ipc(command('send-keys').flags(opts.merge(:t => pane.target)).args(*keys))
+    end
+
+    # Construct a command that will attach the given session when run
+    #
+    # @param session [String] use Session#target
+    # @return [Appear::Util::CommandBuilder]
+    def attach_session_command(session)
+      command('attach-session').flags(:t => session)
     end
 
     private
 
-    def ipc(args)
-      res = run(['tmux'] + args)
+    def command(subcommand)
+      Appear::Util::CommandBuilder.new(['tmux', subcommand])
+    end
+
+    def ipc(cmd)
+      res = run(cmd.to_a)
       res.lines.map do |line|
         info = {}
         line.strip.split(' ').each do |pair|
           key, *value = pair.split(':')
           info[key.to_sym] = value.join(':')
         end
-        OpenStruct.new(info)
+        info
       end
     end
 
-    def format_string(spec)
-      result = ""
-      spec.each do |key, value|
-        part = ' ' + key.to_s + ':#{' + value.to_s + '}'
-        result += part
+    def ipc_returning(cmd, klass)
+      @memo.call(cmd, klass) do
+        cmd.flags(:F => klass.format_string)
+        ipc(cmd).map do |row|
+          klass.parse(row, self)
+        end
       end
-      result
+    end
+
+    def ipc_returning_one(cmd, klass)
+      # -P in tmux is usually required to print information about newly created objects
+      ipc_returning(cmd.flags(:P => true), klass).first
     end
   end
 end

data/lib/appear/util/command_builder.rb

@@ -0,0 +1,148 @@
+module Appear
+  module Util
+    # Builds command strings.
+    #
+    # @example A tmux query command
+    #   tmux_panes = CommandBuilder.new(%w(tmux list-panes)).
+    #     flags(:a => true, :F => '#{session_name} #{pane_index}')
+    #   output, status = Open3.capture2e(*tmux_panes.to_a)
+    class CommandBuilder
+      # @param command [#to_s, Array<#to_s>] the command. Use an array if you
+      #   need multiple words before we start listing arguments, eg `%w(vagrant
+      #   up)`
+      #
+      # @param opts [Hash] options hash
+      # @option opts [Boolean] :single_dash_long_flags When true, flags like
+      #   :foo will be printed like "-foo" instead of the default "--foo"
+      # @option opts [Boolean] :dashdash_after_flags When true, a "--" argument
+      #   will be inserted after the flags but before the arguments.
+      #
+      # @example dashdash_after_flags
+      #   c = CommandBuilder.new('ssh', :dashdash_after_flags => true)
+      #     .flags(:foo => 1, :b => true).args('a', 'b').to_s
+      #   "ssh --foo 1 -b -- a b"
+      def initialize(command, opts = {})
+        @command = command
+        @flags = opts.delete(:flags) || Hash.new { |h, k| h[k] = [] }
+        @argv = opts.delete(:argv) || []
+        @options = {
+          :single_dash_long_flags => false,
+          :dashdash_after_flags => false,
+        }.merge(opts)
+      end
+
+      # Add a flag to this command
+      #
+      # @param name [#to_s] flag name, eg 'cached' for --cached
+      # @param val [Boolean, #to_s] flag value, eg '3fdb21'. Can pass "true"
+      #   for boolean, set-only flags.
+      # @return [self]
+      def flag(name, val)
+        @flags[name] << val
+        self
+      end
+
+      # Add a bunch of flags at once, using a map of flag => argument.
+      #
+      # @param flag_map [Hash<#to_s, [TrueClass, #to_s, Array<#to_s>]>]
+      # @return [self]
+      #
+      # @example multiple duplicate args
+      #   CommandBuilder.new('foo').flags(:o => ['Val1', 'Val2]).to_s
+      #   # "foo -o Val1 -o Val2"
+      def flags(flag_map)
+        flag_map.each do |f, v|
+          if v.is_a?(Array)
+            v.each do |v_prime|
+              flag(f, v_prime)
+            end
+          else
+            flag(f, v)
+          end
+        end
+        self
+      end
+
+      # Add arguments to this command. Arguments always come after flags, and
+      # may be seperated from flags with -- if you pass :dashdash_after_flags
+      # option in the constructor.
+      #
+      # @param args [Array<#to_s>] args to add
+      # @return [self]
+      def args(*args)
+        @argv.concat(args)
+        self
+      end
+
+      # Add a subcommand, with its own flags arguments, after the current
+      # command. This is useful for eg building calls to nested commands.
+      #
+      # @param name [#to_s, Array<#to_s>] the subcommand, see {#initialize}
+      # @param opts [Hash] see {#initialize}
+      # @yield [subc] Add flags and arguments to the subcommand
+      # @yieldparam [CommandBuilder] subc the subcommand
+      # @return [self]
+      #
+      # @example eg, vagrant
+      #   v_up = CommandBuilder.new('vagrant').flags(:root => pwd).subcommand('up') do |up|
+      #     up.flags(:provider => :virtualbox', 'no-provision' => true).args('apollo')
+      #   end
+      def subcommand(name, opts = {})
+        # use our options as the defaults
+        # then use the given options as the overrides
+        subc = CommandBuilder.new(name, @options.merge(opts))
+        yield(subc)
+        args(*subc.to_a)
+        self
+      end
+
+      # Render this command to an array of strings, suitable for execution with
+      # `system` or other methods that take an ARGV array.
+      #
+      # @return [Array<String>] the command
+      def to_a
+        res = [@command].flatten
+        @flags.each do |name, params|
+          flag = flag_name_to_arg(name)
+          params.each do |param|
+            res << flag
+            res << param.to_s unless param == true
+          end
+        end
+        res << '--' if @options[:dashdash_after_flags]
+        res.concat(@argv)
+        res.map { |v| v.to_s }
+      end
+
+      # Render this command as a string, suitable for execution with `sh` or
+      # `system` or other methods that take a command string.
+      #
+      # @return [String] the command
+      def to_s
+        to_a.shelljoin
+      end
+
+      # Duplicate this {CommandBuilder} instance.
+      #
+      # @return [CommandBuilder]
+      def dup
+        opts = @options.dup
+        opts[:argv] = @argv.dup
+        opts[:flags] = @flags.dup
+        self.class.new(@command.dup, opts)
+      end
+
+      private
+
+      # @param flag [#to_s]
+      # @return [String]
+      def flag_name_to_arg(flag)
+        if flag.to_s.length == 1 || @options[:single_dash_long_flags]
+          "-#{flag}"
+        else
+          "--#{flag}"
+        end
+      end
+    end
+  end
+end