vimrunner 0.2.1 → 0.3.0

data/README.md

@@ -12,7 +12,8 @@ contributions are very welcome on the
 
 ## Usage
 
-Vimrunner can be used in one of two main ways:
+If you don't already have a running Vim server, Vimrunner can be used in one
+of two main ways:
 
 ```ruby
 # Vim will automatically be started and killed.
@@ -66,33 +67,75 @@ you can control Vim. For a full list of methods you can invoke on the remote
 Vim instance, check out the [`Client`
 documentation](http://rubydoc.info/gems/vimrunner/Vimrunner/Client).
 
+If you already have a remote-capable Vim server running, you can connect
+Vimrunner to it directly by using `Vimrunner.connect` or `Vimrunner.connect!`
+like so:
+
+```ruby
+# Assuming a running Vim server called FOO...
+vim = Vimrunner.connect("FOO")
+if vim
+  vim.insert("Hello world!")
+end
+
+# Or, if you're confident there's a running server...
+vim = Vimrunner.connect!("FOO")
+vim.insert("Hello world!")
+```
+
+In case of failure to find the server `FOO`, the first form will return `nil`,
+while the second form will raise an exception.
+
 ## Testing
 
-If you're using Vimrunner for testing vim plugins, take a look at the
-documentation for the
-[Vimrunner::Testing](http://rubydoc.info/gems/vimrunner/Vimrunner/Testing)
-module. It contains a few simple helpers that may make it a bit easier to write
-regression tests in rspec. With them, it could work something like this:
+If you're using Vimrunner for testing vim plugins, a simple way to get up and
+running is by requiring the `vimrunner/rspec` file. With that, your
+`spec_helper.rb` would look like this:
 
 ``` ruby
-require 'spec_helper'
-require 'vimrunner/testing'
+require 'vimrunner'
+require 'vimrunner/rspec'
 
-describe "My Vim plugin" do
-  let(:vim) { some_instance_of_vim }
+Vimrunner::RSpec.configure do |config|
+  # Use a single Vim instance for the test suite. Set to false to use an
+  # instance per test (slower, but can be easier to manage).
+  config.reuse_server = true
+
+  # Decide how to start a Vim instance. In this block, an instance should be
+  # spawned and set up with anything project-specific.
+  config.start_vim do
+    vim = Vimrunner.start
 
-  around :each do |example|
-    # needed only once for any Vim instance:
-    vim.add_plugin(File.expand_path('../my_plugin_path'), 'plugin/my_plugin.vim')
+    # Or, start a GUI instance:
+    # vim = Vimrunner.start_gvim
 
-    # ensure a clean temporary directory for each test:
-    Vimrunner::Testing.tmpdir(vim) do
-      example.call
-    end
+    # Setup your plugin in the Vim instance
+    plugin_path = File.expand_path('.')
+    vim.add_plugin(plugin_path, 'plugin/my_plugin.vim')
+
+    # The returned value is the Client available in the tests.
+    vim
   end
+end
+```
+
+This will result in:
+
+- A `vim` helper in every rspec example, returning the configured
+  `Vimrunner::Client` instance.
+- Every example is executed in a separate temporary directory to make it easier
+  to manipulate files.
+- A few helper methods from the `Vimrunner::Testing` module
+  ([documentation](http://rubydoc.info/gems/vimrunner/Vimrunner/Testing)).
 
+The specs would then look something like this:
+
+``` ruby
+require 'spec_helper'
+
+describe "My Vim plugin" do
   specify "some behaviour" do
-    Vimrunner::Testing.write_file('test.rb', <<-EOF)
+    write_file('test.rb', <<-EOF)
       def foo
         bar
       end
@@ -102,7 +145,7 @@ describe "My Vim plugin" do
     do_plugin_related_stuff_with(vim)
     vim.write
 
-    IO.read('test.rb').should eq Vimrunner::Testing.normalize_string_indent(<<-EOF)
+    IO.read('test.rb').should eq normalize_string_indent(<<-EOF)
       def bar
         foo
       end
@@ -111,9 +154,8 @@ describe "My Vim plugin" do
 end
 ```
 
-It's possible to make this a lot more concise by including
-`Vimrunner::Testing`, by making your own helper methods that wrap common
-behaviour, by extracting some code to `spec_helper.rb`, and so on.
+If you need a different setup, please look through the file
+`lib/vimrunner/rspec.rb` for ideas on how to build your own testing scaffold.
 
 ## Requirements
 

data/lib/vimrunner.rb

@@ -23,7 +23,7 @@ module Vimrunner
   #
   # Returns a Client for the started Server.
   def self.start(vim = Platform.vim, &blk)
-    Server.new(vim).start(&blk)
+    Server.new(:executable => vim).start(&blk)
   end
 
   # Public: Start a Vim process with a GUI and return a Client through which
@@ -46,6 +46,36 @@ module Vimrunner
   #
   # Returns a Client for the started Server.
   def self.start_gvim(&blk)
-    Server.new(Platform.gvim).start(&blk)
+    Server.new(:executable => Platform.gvim).start(&blk)
+  end
+
+  # Public: Connect to an existing Vim process by name. Returns nil in case of
+  # failure.
+  #
+  # name - The String name of the Vim server to connect to.
+  #
+  # Examples
+  #
+  #   client = Vimrunner.connect("FOO")
+  #   # => #<Vimrunner::Client>
+  #
+  # Returns a Client for the named server.
+  def self.connect(name)
+    Server.new(:name => name).connect
+  end
+
+  # Public: Connect to an existing Vim process by name. Raises an exception in
+  # case of failure.
+  #
+  # name - The String name of the Vim server to connect to.
+  #
+  # Examples
+  #
+  #   client = Vimrunner.connect("FOO")
+  #   # => #<Vimrunner::Client>
+  #
+  # Returns a Client for the named server.
+  def self.connect!(name)
+    Server.new(:name => name).connect!
   end
 end

data/lib/vimrunner/client.rb

@@ -25,6 +25,19 @@ module Vimrunner
       command("runtime #{entry_script}") if entry_script
     end
 
+    # Public: source a script in Vim server
+    #
+    # script - The Vim script to be sourced
+    #
+    # Examples
+    #
+    #   vim.source '/path/to/plugin/rails.vim'
+    #
+    # Returns nothing.
+    def source(script)
+      feedkeys(":\\<C-u>source #{escape_filename(script)}\\<CR>")
+    end
+
     # Public: Appends a directory to Vim's runtimepath
     #
     # dir - The directory added to the path
@@ -96,6 +109,28 @@ module Vimrunner
       command "echo #{expressions.join(' ')}"
     end
 
+    # Public: Send keys as if they come from a mapping or typed by a user.
+    #
+    # Vim's usual remote-send functionality to send keys to a server does not
+    # respect mappings. As a workaround, the feedkeys() function can be used
+    # to more closely simulate user input.
+    #
+    # Any keys are sent in a double-quoted string so that special keys such as
+    # <CR> and <C-L> can be used. Note that, as per Vim documentation, such
+    # keys should be preceded by a backslash, e.g. '\<CR>' for a carriage
+    # return, '<CR>' will send those four characters separately.
+    #
+    # Examples
+    #
+    #   vim.command 'map <C-R> ihello'
+    #   vim.feedkeys '\<C-R>'
+    #
+    # Returns nothing.
+    def feedkeys(string)
+      string = string.gsub('"', '\"')
+      server.remote_expr(%Q{feedkeys("#{string}")})
+    end
+
     # Public: Sets a setting in Vim. If +value+ is nil, the setting is
     # considered to be a boolean.
     #
@@ -122,7 +157,7 @@ module Vimrunner
     #
     # Returns the Client instance.
     def edit(filename)
-      command "edit #{filename}"
+      command "edit #{escape_filename(filename)}"
       self
     end
 
@@ -132,7 +167,7 @@ module Vimrunner
     #
     # Returns the Client instance.
     def edit!(filename)
-      command "edit! #{filename}"
+      command "edit! #{escape_filename(filename)}"
       self
     end
 
@@ -142,9 +177,7 @@ module Vimrunner
     # Returns the String output.
     # Raises InvalidCommandError if the command is not recognised by vim.
     def command(commands)
-      expression = "VimrunnerEvaluateCommandOutput('#{escape(commands)}')"
-
-      server.remote_expr(expression).tap do |output|
+      server.remote_expr("VimrunnerEvaluateCommandOutput('#{escape_single_quote(commands)}')").tap do |output|
         raise InvalidCommandError.new(output) if output =~ /^Vim:E\d+:/
       end
     end
@@ -156,7 +189,11 @@ module Vimrunner
 
     private
 
-    def escape(string)
+    def escape_filename(name)
+      name.gsub(/([^A-Za-z0-9_\-.,:\/@\n])/, "\\\\\\1")
+    end
+
+    def escape_single_quote(string)
       string.to_s.gsub("'", "''")
     end
   end

data/lib/vimrunner/rspec.rb

@@ -0,0 +1,69 @@
+require 'vimrunner'
+require 'vimrunner/testing'
+
+module Vimrunner
+  module RSpec
+    class Configuration
+      attr_accessor :reuse_server
+
+      def start_vim(&block)
+        @start_vim_method = block
+      end
+
+      def start_vim_method
+        @start_vim_method || lambda { Vimrunner.start }
+      end
+    end
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.configure
+      yield configuration
+    end
+  end
+
+  module Testing
+    class << self
+      attr_accessor :instance
+    end
+
+    def vim
+      Testing.instance ||= Vimrunner::RSpec.configuration.start_vim_method.call
+    end
+  end
+end
+
+# Default configuration
+Vimrunner::RSpec.configure do |config|
+  config.reuse_server = false
+end
+
+RSpec.configure do |config|
+
+  # Include the Testing DSL into all examples.
+  config.include(Vimrunner::Testing)
+
+  # Each example is executed in a separate directory
+  config.around(:each) do |example|
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        vim.command("cd #{dir}")
+        example.run
+      end
+    end
+  end
+
+  config.before(:each) do
+    unless Vimrunner::RSpec.configuration.reuse_server
+      Vimrunner::Testing.instance.kill if Vimrunner::Testing.instance
+      Vimrunner::Testing.instance = nil
+    end
+  end
+
+  # Kill the Vim server after all tests are over.
+  config.after(:suite) do
+    Vimrunner::Testing.instance.kill if Vimrunner::Testing.instance
+  end
+end

data/lib/vimrunner/server.rb

@@ -3,25 +3,41 @@ require "pty"
 
 require "vimrunner/errors"
 require "vimrunner/client"
+require "vimrunner/platform"
 
 module Vimrunner
 
   # Public: A Server has the responsibility of starting a Vim process and
   # communicating with it through the clientserver interface. The process can
-  # be started with "start" and stopped with "kill". A Client would be
-  # necessary as the actual interface, though it is possible to use a Server
-  # directly to invoke --remote commands on its Vim instance.
+  # be started with "start" and stopped with "kill". If given the servername of
+  # an existing Vim instance, it can control that instance without the need to
+  # start a new process.
+  #
+  # A Client would be necessary as there's a ctual interface, though it is possible
+  # to use a Server directly to invoke --remote commands on its Vim instance.
   class Server
-    VIMRC = File.expand_path("../../../vim/vimrc", __FILE__)
+    VIMRC        = File.expand_path("../../../vim/vimrc", __FILE__)
+    VIMRUNNER_RC = File.expand_path("../../../vim/vimrunner_rc", __FILE__)
 
-    attr_reader :name, :executable
+    attr_reader :name, :executable, :vimrc
 
     # Public: Initialize a Server
     #
-    # executable - a String representing a Vim executable.
-    def initialize(executable)
-      @executable = executable
-      @name = "VIMRUNNER#{rand}"
+    # options - The Hash options used to define a server (default: {}):
+    #           :executable - The String Vim executable to use (optional)
+    #                         (default: Platform.vim).
+    #           :name       - The String name of the Vim server (optional)
+    #                         (default: "VIMRUNNER#{rand}").
+    #           :vimrc      - The String vimrc file to source in the client (optional)
+    #                         (default: Server::VIMRC).
+    #           :foreground - Boolean, whether to start Vim with the -f option (optional)
+    #                         (default: true).
+    #
+    def initialize(options = {})
+      @executable = options.fetch(:executable) { Platform.vim }
+      @name       = options.fetch(:name) { "VIMRUNNER#{rand}" }
+      @vimrc      = options.fetch(:vimrc) { VIMRC }
+      @foreground = options.fetch(:foreground, true)
     end
 
     # Public: Start a Server. This spawns a background process.
@@ -38,27 +54,64 @@ module Vimrunner
     # Returns a new Client instance initialized with this Server.
     # Yields a new Client instance initialized with this Server.
     def start
+      @r, @w, @pid = spawn
+
       if block_given?
-        spawn do |r, w, pid|
-          begin
-            wait_until_started
-            @result = yield(new_client)
-          ensure
-            r.close
-            w.close
-            Process.kill(9, pid) rescue Errno::ESRCH
-          end
+        begin
+          @result = yield(connect!)
+        ensure
+          @r.close
+          @w.close
+          Process.kill(9, @pid) rescue Errno::ESRCH
         end
-
         @result
       else
-        @r, @w, @pid = spawn
-        wait_until_started
-
-        new_client
+        connect!
       end
     end
 
+    # Public: Connects to the running server by name, blocking if need be.
+    # Returns nil if no server was found in the given time.
+    #
+    # options - An optional Hash. For now, only used for specifying a timeout
+    #           (default: {}):
+    #
+    #           :timeout - The Integer timeout to wait for a running server (optional)
+    #                      (default: 5).
+    #
+    # Returns a new Client instance initialized with this Server.
+    def connect(options = {})
+      connect!(options)
+    rescue TimeoutError
+      nil
+    end
+
+    # Public: Connects to the running server by name, blocking if need be.
+    # Raises a TimeoutError if no server was found in the given time in
+    # seconds.
+    #
+    # options - An optional Hash. For now, only used for specifying a timeout
+    #           (default: {}):
+    #
+    #           :timeout - The Integer timeout to wait for a running server
+    #                      (default: 5).
+    #
+    # Returns a new Client instance initialized with this Server.
+    def connect!(options = {})
+      wait_until_running(options[:timeout] || 5)
+
+      client = new_client
+      client.source(VIMRUNNER_RC)
+      client
+    end
+
+    # Public: Checks if there's a running Vim instance with the server's name.
+    #
+    # Returns a Boolean
+    def running?
+      serverlist.include?(name)
+    end
+
     # Public: Kills the Vim instance in the background.
     #
     # Returns self.
@@ -107,17 +160,21 @@ module Vimrunner
 
     private
 
+    def foreground_option
+      @foreground ? '-f' : ''
+    end
+
     def execute(command)
       IO.popen(command) { |io| io.read.strip }
     end
 
-    def spawn(&blk)
-      PTY.spawn(executable, "-f", "--servername", name, "-u", VIMRC, &blk)
+    def spawn
+      PTY.spawn("#{executable} #{foreground_option} --servername #{name} -u #{vimrc}")
     end
 
-    def wait_until_started
-      Timeout.timeout(5, TimeoutError) do
-        sleep 0.1 while !serverlist.include?(name)
+    def wait_until_running(seconds)
+      Timeout.timeout(seconds, TimeoutError) do
+        sleep 0.1 while !running?
       end
     end
   end

data/lib/vimrunner/testing.rb

@@ -6,28 +6,6 @@ module Vimrunner
   # testing purposes.
   module Testing
 
-    # Public: Within the given block, switches to a temporary directory for
-    # isolation purposes.
-    #
-    # Example:
-    #
-    #   tmpdir(vim) do
-    #     puts vim.command('pwd')
-    #   end
-    #
-    # vim - a Vimrunner::Client instance
-    #
-    # Returns nothing.
-    # Yields nothing.
-    def tmpdir(vim)
-      Dir.mktmpdir do |dir|
-        Dir.chdir(dir) do
-          vim.command("cd #{dir}")
-          yield
-        end
-      end
-    end
-
     # Public: Writes the given string to the file identified by "filename".
     #
     # Uses #normalize_string_indent to ensure consistent indentation when given

data/lib/vimrunner/version.rb

@@ -1,3 +1,3 @@
 module Vimrunner
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/vim/vimrc

@@ -10,17 +10,4 @@ set noswapfile nobackup
 set runtimepath-=~/.vim
 set runtimepath-=~/.vim/after
 
-function! VimrunnerEvaluateCommandOutput(command)
-  let base_command = split(a:command, '\s\+')[0]
-  let base_command = substitute(base_command, '!$', '', '')
-
-  if !exists(':'.base_command)
-    let output = 'Vim:E492: Not an editor command: '.base_command
-  else
-    redir => output
-    silent exe a:command
-    redir END
-  endif
-
-  return output
-endfunction
+execute "source " . expand('<sfile>:p:h') . "/vimrunner_rc"

data/vim/vimrunner_rc

@@ -0,0 +1,56 @@
+let has_error_handling_bugfix =
+      \ v:version > 703 ||
+      \ v:version == 703 && has('patch860')
+
+if has_error_handling_bugfix
+  function! VimrunnerEvaluateCommandOutput(command)
+    let output = ''
+
+    try
+      redir => output
+      silent exe a:command
+      redir END
+
+      let output = s:StripSilencedErrors(output)
+    catch
+      let output = v:exception
+    endtry
+
+    return output
+  endfunction
+else
+  " Use some fake error handling to provide at least rudimentary errors for
+  " missing commands.
+  function! VimrunnerEvaluateCommandOutput(command)
+    let base_command = split(a:command, '\s\+')[0]
+    let base_command = substitute(base_command, '!$', '', '')
+
+    if !exists(':'.base_command)
+      let output = 'Vim:E492: Not an editor command: '.base_command
+    else
+      redir => output
+      silent exe a:command
+      redir END
+    endif
+
+    return output
+  endfunction
+endif
+
+" Remove errors from the output that have been silenced by :silent!. These are
+" visible in the captured output since all messages are captured by :redir.
+function! s:StripSilencedErrors(output)
+  let processed_output = []
+
+  for line in reverse(split(a:output, "\n"))
+    if line =~ '^E\d\+:'
+      break
+    endif
+
+    call add(processed_output, line)
+  endfor
+
+  return join(reverse(processed_output), "\n")
+endfunction
+
+" vim: set ft=vim

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vimrunner
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-17 00:00:00.000000000 Z
+date: 2013-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -66,7 +66,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.13.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -74,7 +74,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.13.0
 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 can be used to integration test Vim script.\n"
@@ -88,10 +88,12 @@ files:
 - lib/vimrunner.rb
 - lib/vimrunner/client.rb
 - lib/vimrunner/testing.rb
+- lib/vimrunner/rspec.rb
 - lib/vimrunner/errors.rb
 - lib/vimrunner/version.rb
 - lib/vimrunner/server.rb
 - lib/vimrunner/platform.rb
+- vim/vimrunner_rc
 - vim/vimrc
 - bin/vimrunner
 - LICENSE
@@ -110,7 +112,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3996768695942180221
+      hash: -1164770989909868074
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: