vimrunner 0.0.2 → 0.0.3

data/README.md

@@ -2,8 +2,60 @@ Using Vim's client/server functionality, this library exposes a way to spawn a
 Vim instance and control it programatically. Apart from being a fun party
 trick, this could be used to do integration testing on vimscript.
 
+This is still fairly experimental, so use with caution. Any issue reports or
+contributions are very welcome on the
+[github issue tracker](https://github.com/AndrewRadev/Vimrunner/issues)
+
+## Usage
+
+There are two objects that can be used to control Vim, a "server" and a
+"client". The server takes care of spawning a server vim instance that will be
+controlled, and the client is its interface.
+
+A server can be started in two ways:
+
+  - `Vimrunner::Server.start`: Starts a terminal instance. Since it's
+    "invisible", it's nice for use in automated tests. If it's impossible to
+    start a terminal instance due to missing requirements for the `vim` binary
+    (see "Requirements" below), a GUI instance will be started.
+  - `Vimrunner::Server.start(:gui => true)`: Starts a GUI instance of Vim. On
+    Linux, it'll be a `gvim`, on Mac it defaults to `mvim`.
+
+Both methods return a `Server` instance. For a more comprehensive list of
+options you can start the server with, check out
+[the docs](http://rubydoc.info/gems/vimrunner/Vimrunner/Server).
+
+To be able to send commands to the server, you need a client that knows some
+details about it:
+
+``` ruby
+server = Vimrunner::Server.start
+
+client = Vimrunner::Client.new(server)
+# or,
+client = server.new_client
+```
+
+There are also two convenience methods that start a server and return a
+connected client -- `Vimrunner.start_vim` and `Vimrunner.start_gui_vim`.
+
+For a full list of methods you can invoke on the remote vim instance, check out
+the methods on the `Client` class in
+[the docs](http://rubydoc.info/gems/vimrunner/Vimrunner/Client).
+
+## Requirements
+
+Vim needs to be compiled with `+clientserver`. This should be available with
+the `normal`, `big` and `huge` featuresets. The client/server functionality
+(regrettably) needs a running X server to function, even for a terminal vim.
+This means that if you're using it for automated tests on a remote server,
+you'll probably need to start it with xvfb.
+
+## Experimenting
+
 The `vimrunner` executable opens up an irb session with `$vim` set to a running
-`gvim` instance. A few things you can try:
+`gvim` (or `mvim`) client. You can use this for interactive experimentation. A
+few things you can try:
 
 ``` ruby
 $vim.edit 'some_file_name'  # edit a file
@@ -12,13 +64,3 @@ $vim.normal 'T,'            # go back to the nearest comma
 $vim.type 'a<cr>'           # append a newline after the comma
 $vim.write                  # write file to disk
 ```
-
-For more examples of what you can do, you could take a look at the specs, they
-should be fairly readable.
-
-Note that this should work on a Linux box, but probably won't on a Mac. I'm
-assuming you'd need to change the binary to `mvim` at the very least.
-
-This is still fairly experimental, so use with caution. Any issue reports or
-contributions are very welcome on the
-[github issue tracker](https://github.com/AndrewRadev/Vimrunner/issues)

data/bin/vimrunner

@@ -5,6 +5,6 @@ $: << File.expand_path('../../lib', __FILE__)
 require 'irb'
 require 'vimrunner'
 
-$vim = Vimrunner::Runner.start_gvim
+$vim = Vimrunner.start_gui_vim
 
 IRB.start

data/lib/vimrunner.rb

@@ -1 +1,16 @@
-require 'vimrunner/runner'
+require 'vimrunner/client'
+require 'vimrunner/server'
+
+module Vimrunner
+  # Starts a new Server with a terminal vim instance and returns a client,
+  # connected to it.
+  def self.start_vim
+    Client.new(Server.start)
+  end
+
+  # Starts a new Server with a GUI vim instance and returns a client, connected
+  # to it.
+  def self.start_gui_vim
+    Client.new(Server.start(:gui => true))
+  end
+end

data/lib/vimrunner/client.rb

@@ -0,0 +1,109 @@
+require 'vimrunner/shell'
+
+module Vimrunner
+
+  # A Client is simply a proxy to a Vim server. It's initialized with a Server
+  # instance and sends commands, keys and signals to it.
+  class Client
+    def initialize(server)
+      @server = server
+    end
+
+    # Adds a plugin to Vim's runtime. Initially, Vim is started without
+    # sourcing any plugins to ensure a clean state. This method can be used to
+    # populate the instance's environment.
+    #
+    # dir          - The base directory of the plugin, the one that contains
+    #                its autoload, plugin, ftplugin, etc. directories.
+    # entry_script - The Vim script that's runtime'd to initialize the plugin.
+    #                Optional.
+    #
+    # Example:
+    #
+    #   vim.add_plugin 'rails', 'plugin/rails.vim'
+    #
+    def add_plugin(dir, entry_script = nil)
+      command("set runtimepath+=#{dir}")
+      command("runtime #{entry_script}") if entry_script
+    end
+
+    # Invokes one of the basic actions the Vim server supports, sending a key
+    # sequence. The keys are sent as-is, so it'd probably be better to use the
+    # wrapper methods, #normal, #insert and so on.
+    def type(keys)
+      invoke_vim '--remote-send', keys
+    end
+
+    # Executes the given command in the Vim instance and returns its output,
+    # stripping all surrounding whitespace.
+    def command(vim_command)
+      normal
+
+      expression = "VimrunnerEvaluateCommandOutput('#{vim_command.to_s}')"
+
+      invoke_vim('--remote-expr', expression).strip.tap do |output|
+        raise InvalidCommandError if output =~ /^Vim:E\d+:/
+      end
+    end
+
+    # Starts a search in Vim for the given text. The result is that the cursor
+    # is positioned on its first occurrence.
+    def search(text)
+      normal
+      type "/#{text}<cr>"
+    end
+
+    # Sets a setting in Vim. If +value+ is nil, the setting is considered to be
+    # a boolean.
+    #
+    # Examples:
+    #
+    #   vim.set 'expandtab'  # invokes ":set expandtab"
+    #   vim.set 'tabstop', 3 # invokes ":set tabstop=3"
+    #
+    def set(setting, value = nil)
+      if value
+        command "set #{setting}=#{value}"
+      else
+        command "set #{setting}"
+      end
+    end
+
+    # Edits the file +filename+ with Vim.
+    #
+    # Note that this doesn't use the '--remote' Vim flag, it simply types in
+    # the command manually. This is necessary to avoid the Vim instance getting
+    # focus.
+    def edit(filename)
+      command "edit #{filename}"
+    end
+
+    # Writes the file being edited to disk. Note that you probably want to set
+    # the file's name first by using Runner#edit.
+    def write
+      command :write
+    end
+
+    # Switches Vim to insert mode and types in the given text.
+    def insert(text = '')
+      normal "i#{text}"
+    end
+
+    # Switches Vim to normal mode and types in the given keys.
+    def normal(keys = '')
+      type "<c-\\><c-n>#{keys}"
+    end
+
+    # Kills the server it's connected to.
+    def kill
+      @server.kill
+    end
+
+    private
+
+    def invoke_vim(*args)
+      args = [@server.vim_path, '--servername', @server.name, *args]
+      Shell.run *args
+    end
+  end
+end

data/lib/vimrunner/errors.rb

@@ -1,3 +1,9 @@
 module Vimrunner
   class InvalidCommandError < RuntimeError; end
+
+  class TimeoutError < RuntimeError
+    def message
+      "Timed out while waiting for serverlist. Is an X11 server running?"
+    end
+  end
 end

data/lib/vimrunner/server.rb

@@ -0,0 +1,151 @@
+require 'timeout'
+require 'rbconfig'
+require 'pty'
+
+require 'vimrunner/errors'
+require 'vimrunner/shell'
+require 'vimrunner/client'
+
+module Vimrunner
+
+  # The Server is a wrapper around the Vim server process that is controlled by
+  # clients. It will attempt to start the most appropriate Vim binary available
+  # on the system, though there are some options that can control this
+  # behaviour. See #initialize for more details.
+  class Server
+    class << self
+
+      # A convenience method that initializes a new server and starts it.
+      def start(options = {})
+        server = new(options)
+        server.start
+      end
+
+      # A convenience method that returns a new Client instance, connected to
+      # the server.
+      def new_client
+        Client.new(self)
+      end
+
+      # Retrieve a list of names of currently running Vim servers.
+      def list
+        %x[#{vim_path} --serverlist].strip.split "\n"
+      end
+
+      # The default path to use when starting a server with a terminal Vim. If
+      # the "vim" executable is not compiled with clientserver capabilities,
+      # the GUI version is started instead.
+      def vim_path
+        if clientserver_enabled? 'vim'
+          'vim'
+        else
+          gui_vim_path
+        end
+      end
+
+      # The default path to use when starting a server with the GUI version of
+      # Vim. Defaults to "mvim" on a mac and "gvim" on linux.
+      def gui_vim_path
+        if mac?
+          'mvim'
+        else
+          'gvim'
+        end
+      end
+
+      # The path to a vimrc file containing some required vimscript. The server
+      # is started with no settings or a vimrc, apart from this one.
+      def vimrc_path
+        File.join(File.expand_path('../../..', __FILE__), 'vim', 'vimrc')
+      end
+
+      # Returns true if the current operating system is Mac OS X.
+      def mac?
+        host_os =~ /darwin/
+      end
+
+      # Returns true if the given Vim binary is compiled with support for the
+      # client/server functionality.
+      def clientserver_enabled?(vim_path)
+        vim_version = %x[#{vim_path} --version]
+        vim_version.include? '+clientserver' and vim_version.include? '+xterm_clipboard'
+      end
+
+      private
+
+      def host_os
+        RbConfig::CONFIG['host_os']
+      end
+    end
+
+    attr_accessor :pid
+    attr_reader :name, :vim_path
+
+    # A Server is initialized with two options that control its behaviour:
+    #
+    #   :gui      - Whether or not to start Vim with a GUI, either 'gvim' or 'mvim'
+    #               depending on the OS. The default is false, which means that
+    #               the server will start itself as a terminal instance. Note
+    #               that, if the terminal Vim doesn't have client/server
+    #               support, a GUI version will be started anyway.
+    #
+    #   :vim_path - A path to a custom Vim binary. If this option is not set,
+    #               the server attempts to guess an appropriate one, given the
+    #               :gui option and the current OS.
+    #
+    # Note that simply initializing a Server doesn't start the binary. You need
+    # to call the #start method to do that.
+    #
+    # Examples:
+    #
+    #   server = Server.new                              # Will start a 'vim' if possible
+    #   server = Server.new(:gui => true)                # Will start a 'gvim' or 'mvim' depending on the OS
+    #   server = Server.new(:vim_path => '/opt/bin/vim') # Will start a server with the given vim instance
+    #
+    def initialize(options = {})
+      @gui      = options.fetch(:gui) { false }
+      @vim_path = options.fetch(:vim_path) { gui? ? Server.gui_vim_path : Server.vim_path }
+
+      @name = "VIMRUNNER#{rand.to_s}"
+    end
+
+    # Starts a Vim server.
+    def start
+      command = "#{vim_path} -f -u #{Server.vimrc_path} --noplugin --servername #{name}"
+
+      if gui?
+        @pid = Kernel.spawn(command, [:in, :out, :err] => :close)
+      else
+        _out, _in, @pid = PTY.spawn(command)
+      end
+
+      wait_until_started
+      self
+    end
+
+    # Returns true if the server was initialized with :gui => true. Note that
+    # this may not be consistent with the binary that was actually started. If
+    # a terminal Vim instance was attempted, but an appropriate one was not
+    # available, it may still have a GUI.
+    def gui?
+      @gui
+    end
+
+    # Kills the Vim instance in the background by sending it a TERM signal.
+    def kill
+      Shell.kill(@pid)
+    end
+
+    private
+
+    def wait_until_started
+      Timeout.timeout(5, TimeoutError) do
+        serverlist = Server.list
+        while serverlist.empty? or not serverlist.include? name
+          sleep 0.1
+          serverlist = Server.list
+        end
+      end
+    end
+  end
+end

data/lib/vimrunner/shell.rb

@@ -12,18 +12,10 @@ module Vimrunner
       IO.popen(command) { |io| io.read.strip }
     end
 
-    # Sends a TERM signal to the given PID if it corresponds to a running
-    # process.
+    # Sends a TERM signal to the given PID. Returns true if the process was
+    # found and killed, false otherwise.
     def kill(pid)
-      Process.kill(Signal.list['TERM'], pid) if running?(pid)
-    end
-
-    private
-
-    # Checks if the given PID corresponds to a running process
-    def running?(pid)
-      return false if pid.nil?
-      Process.getpgid(pid)
+      Process.kill('TERM', pid)
       true
     rescue Errno::ESRCH
       false

data/lib/vimrunner/version.rb

@@ -1,3 +1,3 @@
 module Vimrunner
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vimrunner
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-29 00:00:00.000000000Z
+date: 2012-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &22761920 !ruby/object:Gem::Requirement
+  requirement: &23987740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22761920
+  version_requirements: *23987740
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &22761500 !ruby/object:Gem::Requirement
+  requirement: &23987320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *22761500
+  version_requirements: *23987320
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &22761000 !ruby/object:Gem::Requirement
+  requirement: &23986780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: 2.0.0
   type: :development
   prerelease: false
-  version_requirements: *22761000
+  version_requirements: *23986780
 description: ! "    Using vim's client/server functionality, this library exposes
   a way to\n    spawn a vim instance and control it programatically. Apart from being
   a fun\n    party trick, this could be used to do integration testing on vimscript.\n"
@@ -54,11 +54,12 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/vimrunner.rb
+- lib/vimrunner/errors.rb
 - lib/vimrunner/shell.rb
+- lib/vimrunner/server.rb
 - lib/vimrunner/version.rb
-- lib/vimrunner/runner.rb
-- lib/vimrunner/errors.rb
-- lib/vimrunner.rb
+- lib/vimrunner/client.rb
 - vim/vimrc
 - bin/vimrunner
 - LICENSE
@@ -77,7 +78,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4179387824099540343
+      hash: -3146226263794770349
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -86,7 +87,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: vimrunner
-rubygems_version: 1.8.11
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: Lets you control a vim instance through ruby

data/lib/vimrunner/runner.rb

@@ -1,158 +0,0 @@
-require 'vimrunner/shell'
-require 'vimrunner/errors'
-
-module Vimrunner
-
-  # The Runner class acts as the actual proxy to a vim instance. Upon
-  # initialization, a vim process is started in the background. The Runner
-  # instance's public methods correspond to actions the instance will perform.
-  #
-  # Use Runner#kill to manually destroy the background process.
-  class Runner
-    attr_reader :servername
-
-    class << self
-      def start_gvim
-        servername = "VIMRUNNER#{rand.to_s.gsub '.', ''}"
-
-        child_stdin,   parent_stdin = IO::pipe
-        parent_stdout, child_stdout = IO::pipe
-        parent_stderr, child_stderr = IO::pipe
-
-        pid = Kernel.fork do
-          [parent_stdin, parent_stdout, parent_stderr].each { |io| io.close }
-
-          STDIN.reopen(child_stdin)
-          STDOUT.reopen(child_stdout)
-          STDERR.reopen(child_stderr)
-
-          [child_stdin, child_stdout, child_stderr].each { |io| io.close }
-
-          exec 'gvim', '-f', '-u', vimrc_path, '--noplugin', '--servername', servername
-        end
-
-        [child_stdin, child_stdout, child_stderr].each { |io| io.close }
-
-        new(pid, servername)
-      end
-
-      def vimrc_path
-        File.join(File.expand_path('../../..', __FILE__), 'vim', 'vimrc')
-      end
-
-      def serverlist
-        %x[vim --serverlist].strip.split "\n"
-      end
-    end
-
-    def initialize(pid, servername)
-      @pid        = pid
-      @servername = servername
-      wait_until_started
-    end
-
-    # Adds a plugin to Vim's runtime. Initially, Vim is started without
-    # sourcing any plugins to ensure a clean state. This method can be used to
-    # populate the instance's environment.
-    #
-    # dir          - The base directory of the plugin, the one that contains
-    #                its autoload, plugin, ftplugin, etc. directories.
-    # entry_script - The vim script that's runtime'd to initialize the plugin.
-    #
-    # Example:
-    #
-    #   vim.add_plugin 'rails', 'plugin/rails.vim'
-    #
-    def add_plugin(dir, entry_script)
-      command("set runtimepath+=#{dir}")
-      command("runtime #{entry_script}")
-    end
-
-    # Invokes one of the basic actions the vim server supports, sending a key
-    # sequence. The keys are sent as-is, so it'd probably be better to use the
-    # wrapper methods, #normal, #insert and so on.
-    def type(keys)
-      invoke_vim '--remote-send', keys
-    end
-
-    # Executes the given command in the vim instance and returns its output,
-    # stripping all surrounding whitespace.
-    def command(vim_command)
-      normal
-
-      expression = "VimrunnerEvaluateCommandOutput('#{vim_command.to_s}')"
-
-      invoke_vim('--remote-expr', expression).strip.tap do |output|
-        raise InvalidCommandError if output =~ /^Vim:E\d+:/
-      end
-    end
-
-    # Starts a search in vim for the given text. The result is that the cursor
-    # is positioned on its first occurrence.
-    def search(text)
-      normal
-      type "/#{text}<cr>"
-    end
-
-    # Sets a setting in vim. If +value+ is nil, the setting is considered to be
-    # a boolean.
-    #
-    # Examples:
-    #
-    #   vim.set 'expandtab'  # invokes ":set expandtab"
-    #   vim.set 'tabstop', 3 # invokes ":set tabstop=3"
-    #
-    def set(setting, value = nil)
-      if value
-        command "set #{setting}=#{value}"
-      else
-        command "set #{setting}"
-      end
-    end
-
-    # Edits the file +filename+ with Vim.
-    #
-    # Note that this doesn't use the '--remote' vim flag, it simply types in
-    # the command manually. This is necessary to avoid the vim instance getting
-    # focus.
-    def edit(filename)
-      command "edit #{filename}"
-    end
-
-    # Writes the file being edited to disk. Note that you need to set the
-    # file's name first by using Runner#edit.
-    def write
-      command :write
-    end
-
-    # Switches vim to insert mode and types in the given text.
-    def insert(text = '')
-      normal "i#{text}"
-    end
-
-    # Switches vim to insert mode and types in the given keys.
-    def normal(keys = '')
-      type "<c-\\><c-n>#{keys}"
-    end
-
-    # Kills the vim instance in the background by sending it a TERM signal.
-    def kill
-      Shell.kill(@pid)
-    end
-
-    private
-
-    def invoke_vim(*args)
-      args = ['vim', '--servername', @servername, *args]
-      Shell.run *args
-    end
-
-    def wait_until_started
-      serverlist = Runner.serverlist
-      while serverlist.empty? or not serverlist.include? @servername
-        sleep 0.1
-        serverlist = Runner.serverlist
-      end
-    end
-  end
-end