vim_client-ruby 0.1.0

data/ext/vim_client/vim_client.h

@@ -0,0 +1,82 @@
+#ifndef VIM_CLIENT_H
+#define VIM_CLIENT_H
+
+#include <ruby.h>
+#include <ruby/encoding.h>
+
+#ifdef HAVE_SYS_SELECT_H
+# include <sys/select.h>
+#else
+# include <sys/poll.h>
+  struct        pollfd;            /* for poll __ARGS */
+  extern int    poll __ARGS((struct pollfd *, long, int));
+#endif
+
+#include <signal.h>
+#include <X11/Intrinsic.h>
+#include <X11/Xatom.h>
+
+/* VimClient::Exception < Exception
+ *     VimClient::NoMemoryError            ex_NoMemoryError
+ *     VimClient::XIOError                 ex_XIOError
+ * VimClient::Error < StandardError    e_Error
+ *     VimClient::TimeoutError             e_TimeoutError
+ *     VimClient::ExprError                e_ExprError
+ */
+VALUE ex_NoMemoryError, ex_XIOError, e_Error, e_TimeoutError, e_ExprError;
+
+/*
+ * Shorthand for unsigned variables. Many systems, but not all, have u_char
+ * already defined, so we use char_u to avoid trouble.
+ */
+typedef unsigned char   char_u;
+typedef unsigned int    int_u;
+typedef unsigned long   long_u;
+
+#ifndef __ARGS
+    /* The AIX VisualAge cc compiler defines __EXTENDED__ instead of __STDC__
+     * because it includes pre-ansi features. */
+# if defined(__STDC__) || defined(__GNUC__) || defined(__EXTENDED__)
+#  define __ARGS(x) x
+# else
+#  define __ARGS(x) ()
+# endif
+#endif
+
+#define OK      1
+#define FAIL    0
+#define NUL     '\000'
+/* Used for setting the vimProperty on the commWindow */
+#define VIM_VERSION_SHORT   "7.3"
+
+#define STRLEN(s) strlen((char *)(s))
+#define STRCMP(d, s) strcmp((char *)(d), (char *)(s))
+
+#ifdef HAVE_STRCASECMP
+# define STRICMP(d, s)	    strcasecmp((char *)(d), (char *)(s))
+#else
+# ifdef HAVE_STRICMP
+#  define STRICMP(d, s)	    stricmp((char *)(d), (char *)(s))
+# else
+int vim_stricmp __ARGS((char *s1, char *s2));
+#  define STRICMP(d, s)	    vim_stricmp((char *)(d), (char *)(s))
+# endif
+#endif
+#ifdef HAVE_STRNCASECMP
+# define STRNICMP(d, s, n)  strncasecmp((char *)(d), (char *)(s), (size_t)(n))
+#else
+# ifdef HAVE_STRNICMP
+#  define STRNICMP(d, s, n) strnicmp((char *)(d), (char *)(s), (size_t)(n))
+# else
+int vim_strnicmp __ARGS((char *s1, char *s2, size_t len));
+#  define STRNICMP(d, s, n) vim_strnicmp((char *)(d), (char *)(s), (size_t)(n))
+# endif
+#endif
+
+char_u *vim_strsave __ARGS((char_u *string));
+char_u *alloc __ARGS((long_u size));
+void vim_free __ARGS((void *x));
+VALUE vim2rb_enc_str __ARGS((char_u **res, char_u *server_enc));
+char_u *rb2vim_enc_str __ARGS((VALUE str, char_u **cmd_enc));
+
+#endif // VIM_CLIENT_H

data/lib/vim_client/version.rb

@@ -0,0 +1,3 @@
+module VimClient
+  VERSION = '0.1.0'
+end

data/lib/vim_client.rb

@@ -0,0 +1,300 @@
+require 'vim_client/version'
+require 'vim_client/vim_client.so'
+
+# This module provides methods for communicating with Vim, using it's
+# [+clientserver][] feature.
+#
+# It provides a persistent connection to the X11 server for communicating with
+# a Vim server, much like another running instance of Vim.
+#
+# {.send\_keys} is like using [remote_send()][], and {.send\_expr} is like
+# [remote_expr()][].
+#
+# This lets you avoid having to shell-out to Vim for each command you need to
+# send (using `--remote-send` and `--remote-expr`).
+#
+# {.send\_keys2} would be like using [remote_send()][] ending with a call to
+# [server2client()][] on the remote, then following that call with [remote_read()][].
+#
+# This allows you to send `keys`, then evaluate an expression on the server
+# _after_ those keys are processed and receive the result of that expression.
+# This may also be used to simply block until the sent keys have been processed.
+#
+# Usage
+# -----
+#
+# Install the gem using:
+#
+# ```
+# gem install vim_client-ruby
+# ```
+#
+# Or, add it to your project's Gemfile.
+#
+# ```ruby
+# gem 'vim_client-ruby'
+# ```
+#
+# Require VimClient:
+#
+# ```ruby
+# require 'vim_client'
+# ```
+#
+# Then, be sure to set the name of your Vim server:
+#
+# ```ruby
+# VimClient.server_name = 'vim_server1'
+# VimClient.timeout_sec = 30 # and optionally change the default timeout
+# ```
+#
+# If {.server\_name} is not set, an {Error} will be raised.  
+# Both {.server\_name} and {.timeout\_sec} may be updated at any time.
+#
+#
+# Character Encodings
+# -------------------
+#
+# Vim's default encoding is `latin1 (ISO-8859-1)`. If compiled with the
+# [+multi_byte][] feature, Vim supports many other [encodings][].  
+#
+# All returned strings from {.send\_expr} and {.send\_keys2} will be set
+# to the encoding that is set on the Vim server. If the server is using
+# `latin1`, then strings returned will be marked as `ISO-8859-1`. If the
+# server is using `utf-8`, then strings returned will be marked as `UTF-8`.  
+# _No transcoding is performed on the strings returned from the server._
+# The strings are simply marked using the encoding reported by the server.
+#
+# Vim handles all Unicode strings as UTF-8. This means if the server's encoding
+# is set to any Unicode encoding, the returned string will be in UTF-8. Vim
+# also expects that any command string being sent (as `keys` or an `expr`) will
+# be in UTF-8. Therefore, any string you send which is in a Vim supported
+# Unicode encoding will be transcoded to UTF-8 before being sent to the remote
+# server.
+#
+# For other Vim supported encodings, Vim will be told which of it's supported
+# encodings the sent string is using. If the string you send is using a
+# different encoding than the 'encoding' set on the server, Vim will convert
+# it and the response returned will be in the remote server's encoding.
+#
+# For a list of Vim's supported encodings and their corresponding Ruby
+# encoding names, see the source in [ext/vim_client/misc.c][]. You can also
+# view the specs to get a better idea of how this works.
+#
+# Basically, as long as the `keys` or `expr` strings you're sending are in
+# an encoding supported by Vim, then you'll have no problems. Just remember
+# that the returned string will be in the server's encoding, and that this
+# will always be UTF-8 for Unicode strings.
+#
+#
+# Signals and Errors
+# ------------------
+#
+# If SIGINT is received while VimClient is waiting for a response from the server,
+# the wait loop will be aborted, the SIGINT handler that was present when we
+# entered the loop will be restored, and SIGINT will be re-raised to the calling
+# process group. If this signal is ignored, the process will continue and the calling
+# method `(send_expr/send_keys2)` will return `nil`.
+#
+# If `timeout_sec` expires while waiting for a response, {TimeoutError} will be raised,
+# which you may rescue.
+#
+# In either case, be aware that any response received from the remote server for this
+# request will be lost. Also, there is no way of knowing what state the server is in;
+# especially in the case of a timeout. It could have reported an error and be waiting
+# for an acknowledgement. In which case, the next sent command may simply hang as well.
+# In such case, it may be best to simply stop your server and restart it before sending
+# any further commands.
+#
+# [+clientserver]: http://vimdoc.sourceforge.net/htmldoc/remote.html#clientserver
+# [remote_send()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#remote_send()
+# [remote_expr()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#remote_expr()
+# [server2client()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#server2client()
+# [remote_read()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#remote_read()
+# [+multi_byte]: http://vimdoc.sourceforge.net/htmldoc/mbyte.html
+# [encodings]: http://vimdoc.sourceforge.net/htmldoc/mbyte.html#mbyte-encoding
+# [ext/vim_client/misc.c]: http://github.com/burns/vim_client-ruby/tree/master/ext/vim_client/misc.c
+module VimClient
+  class << self
+    # Sets the name of the remote Vim server to send messages to.
+    #
+    # This may be changed at any time, as this value is read before
+    # each call to {.send\_keys}, {.send\_keys2} and {.send\_expr}.
+    #
+    # **If no server name is specified, an Error will be raised.**
+    #
+    # @return [String]
+    # @!attribute [rw] server_name
+
+    # Sets the timeout in seconds to wait for a response.
+    #
+    # This may be changed at any time, as this value is read before
+    # each call to {.send\_keys2} and {.send\_expr}.
+    #
+    # **Defaults to 60 seconds if not specified.**
+    #
+    # @return [Integer]
+    # @!attribute [rw] timeout_sec
+
+    # Send Keys to the remote Vim server.
+    #
+    # This method is analogous to Vim's [remote_send()][] function.
+    #
+    # The `keys` string is sent to the remote server as input keys
+    # and the method returns immediately. If you need this call to block
+    # until the commands are processed, use {.send\_keys2}.
+    #
+    # Note that if the commands sent result in an error on the server,
+    # it will not be reported and may cause subsequent commands to fail.
+    #
+    # Use `<cr>` to insert a carriage return. If omitted, the next call
+    # to `send_keys` will be appended. Each new line in `keys` should
+    # begin with a colon `( : )`. Commands may also be separated using
+    # a pipe `( | )`.
+    #
+    # For example, the following two commands are equivalent:
+    #
+    # ```ruby
+    #   VimClient.send_keys(":e ++ff=dos #{ some_file } | setlocal ff=unix | w | bd<cr>")
+    #
+    #   VimClient.send_keys(":e ++ff=dos #{ some_file }<cr>:setlocal ff=unix<cr>:w | bd<cr>")
+    # ```
+    #
+    # These two commands would be equivalent as well:
+    #
+    # ```ruby
+    #   VimClient.send_keys(":e ++ff=dos #{ some_file } | setlocal ff=unix") # no `<cr>`
+    #   VimClient.send_keys(" | w | bd<cr>") # appends to the previously sent keys
+    # ```
+    #
+    # The basic equivalent non-VimClient call for this method would be:
+    #
+    # ```ruby
+    #   system('gvim', '--servername', 'server_name', '--remote-send',
+    #     ":e ++ff=dos #{ some_file } | setlocal ff=unix | w | bd<cr>")
+    # ```
+    #
+    # [remote_send()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#remote_send()
+    #
+    # @param keys [String] Input keys to send to the remote server.
+    # @return [Nil]
+    # @!method send_keys(keys)
+
+    # Send Keys to the remote server and wait for a reply.
+    #
+    # This method is similar to {.send\_keys}, except that it adds a callback
+    # to the end of the keys sent, then returns the result of `expr`.
+    #
+    # The `keys` parameter follows the same rules as {.send\_keys}.
+    # The `expr` parameter follows the same rules as {.send\_expr}, except
+    # that this expression must return a String; whereas {.send\_expr} will
+    # automatically convert a List (Array) into a String.
+    #
+    # For example, the following would be equivalent:
+    #
+    # ```ruby
+    #   VimClient.send_expr('setline(1,["line one", "line two"])')
+    #   VimClient.send_expr('getline(1,"$")') # => "line one\nline two"
+    #
+    #   VimClient.send_keys2(
+    #     ':call setline(1,["line one", "line two"])<cr>',
+    #     'join(getline(1,"$"), "\\n")'
+    #   ) # => "line one\nline two"
+    # ```
+    #
+    # If no `expr` is given, then the `expr` will simply return an empty string.
+    #
+    # Note: While `setline()` can be used with {.send\_keys} and {.send\_keys2}
+    # (i.e. `--remote-send`) to set the buffer text, any [keycodes][] within
+    # these command strings (including within string-literals) will be interpreted.
+    #
+    # To understand this better, what this method actually does is append
+    # a call to Vim's [server2client()][] function.  
+    # It then waits for the reply, like calling [remote_read()][].
+    #
+    # ```ruby
+    #   # When you send the following:
+    #   VimClient.send_keys2(":sleep 1<cr>")
+    #
+    #   # What actually gets sent is:
+    #   # :sleep 1<cr>server2client(expand("<client>"), "")<cr>
+    #
+    #   # When sending:
+    #   VimClient.send_keys2(":sleep 1<cr>", "localtime()")
+    #
+    #   # This is sent:
+    #   # :sleep 1<cr>server2client(expand("<client>"), localtime())<cr>
+    # ```
+    #
+    # The strings given for `keys` and `expr` must be in the same encoding
+    # or an {Error} will be raised.
+    #
+    # A call to {.send\_keys2} may be preceded by other calls to {.send\_keys},
+    # as keys sent asynchronously and added to the server's typeahead buffer.
+    #
+    # As with {.send\_keys}, any error reported by the server will not be
+    # reported. This includes any error evaluating the `expr` given to
+    # [server2client()][]. However, since this call is waiting for a reply,
+    # a {TimeoutError} would be raised.
+    #
+    # The basic equivalent non-VimClient call for this method would be:
+    #
+    # ```ruby
+    #   response = %x{
+    #     gvim -fes -u NONE +'call remote_send("server_name",  \
+    #     '\\'':sleep 1 | call server2client(expand("<client>"), localtime())<cr>'\\'', "sid")'  \
+    #     +'redir >> /dev/stdout | echo remote_read(sid) | redir END | q'
+    #   }
+    # ```
+    #
+    # [server2client()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#server2client()
+    # [remote_read()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#remote_read()
+    # [keycodes]: http://vimdoc.sourceforge.net/htmldoc/intro.html#keycodes
+    #
+    # @param keys [String] Input keys to send to the remote server.
+    # @param expr [String] Expression to evaluate on the remote server after
+    #     the given `keys` are processed.
+    # @return [String] Result of evaluated expression.
+    # @return [Nil] If aborted by SIGINT.
+    # @raise [TimeoutError] if no response is returned before {.timeout\_sec} expires.
+    # @!method send_keys2(keys, expr = '""')
+
+    # Evaluate an expression on the remote Vim server.
+    #
+    # This method is analogous to Vim's [remote_expr()][] function.
+    #
+    # If the expression results in a List (Array), Vim will return the items
+    # separated by newlines using: `join(list, "\n")`
+    #
+    # For example, to evaluate a simple expression:
+    #
+    # ```ruby
+    #   ret = VimClient.send_expr('2+2')
+    #   # ret == '4'
+    # ```
+    #
+    # To retrieve all lines in the current buffer:
+    #
+    # ```ruby
+    #   ret = VimClient.send_expr('getline(1,"$")')
+    #   # ret == "line one\nline two\nline three"
+    # ```
+    #
+    # The basic equivalent non-VimClient call for this method would be:
+    #
+    # ```ruby
+    #   %x{ gvim --servername server_name --remote-expr 'getline(1,"$")' }
+    # ```
+    #
+    # [remote_expr()]: http://vimdoc.sourceforge.net/htmldoc/eval.html#remote_expr()
+    #
+    # @param expr [String] Expression to evaluate on the remote server.
+    # @return [String] Result of evaluated expression.
+    # @return [Nil] If aborted by SIGINT.
+    # @raise [ExprError] if the server reports an error. The error message
+    #     will contain the error message from the server.
+    # @raise [TimeoutError] if no response is returned before
+    #     {.timeout\_sec} expires.
+    # @!method send_expr(expr)
+  end
+end

data/spec/vim_client_spec.rb

@@ -0,0 +1,296 @@
+# encoding: utf-8
+require 'bundler/setup'
+require 'rspec/autorun'
+require 'vim_client'
+
+module VimServer
+  class << self
+
+    # This will run the server in the foreground and leave it open.
+    # Only good for checking a specific test, as it will only allow the
+    # server to be started once. This is a good thing :)
+    # e.g. change test to: it 'debug' do
+    #      then use: rspec spec/ --example debug
+    DEBUG = false
+
+    # Place the server in 'visual' mode.
+    # Note that this does not bring the server to the foreground.
+    # If you do use visual mode, also note that each new line of keys
+    # must be prefixed with a colon (:). Using Ex mode (-e or -E),
+    # this will cause lines to begin with two colons (::). However,
+    # this has no ill effects. So, it's best to use them so that
+    # switching between modes is possible.
+    VISUAL = false
+
+    def running
+      !!(/#{ server_name }/im =~ `gvim --serverlist`)
+    end
+
+    # Each test starts and stops a separate server.
+    # Cycling this quickly with the same server name does not work well,
+    # so each will be assigned it's own serial number.
+    def server_name(update = false)
+      @serial = @serial.to_i + 1 if update
+      "vim_server#{ @serial }"
+    end
+
+    def start
+      return if @pid
+
+      opts = DEBUG ? '-nfE' : '-nfEs'
+      @pid = spawn(
+        *%W{ gvim #{ opts } -u NONE --servername #{ server_name(true) } },
+        [:out, :err] => '/dev/null'
+      )
+      @thr = Process.detach(@pid)
+
+      t = 0; until running; t += 1; sleep 0.1
+        abort "VimServer #{ server_name } failed to start" if t > 30; end
+
+      %x{ gvim --servername #{ server_name } \
+              --remote-expr 'feedkeys(":visual\\<cr>")' } if VISUAL
+
+      VimClient.server_name = server_name
+      VimClient.timeout_sec = 10
+    end
+
+    def stop
+      return if (DEBUG || !@pid)
+
+      if running
+        system(*%W{ gvim --servername #{ server_name }
+                  --remote-send :q!<cr> })
+        t = 0; until !running; t += 1; sleep 0.1; break if t > 30; end
+      end
+
+      if @thr.alive?
+        warn 'Killing Server!'
+        Process.kill(:TERM, @pid, Process::WNOHANG) rescue nil
+      end
+
+      @pid = nil
+    end
+  end
+end
+
+describe 'VimClient' do
+  before(:each) { VimServer.start }
+  after(:each)  { VimServer.stop }
+
+  describe '.send_keys' do
+
+    it 'should send keys' do
+      VimClient.send_keys(':q<cr>')
+
+      t = 0; until !VimServer.running
+          t += 1; sleep 0.1; break if t > 30; end
+      VimServer.running.should be_false
+    end
+
+    it 'should raise an error if server_name is not set' do
+      VimClient.server_name = nil
+      expect do
+        VimClient.send_keys(':foo<cr>')
+      end.to raise_error(VimClient::Error, 'server_name must be set')
+    end
+
+    it 'should raise an error if server not found' do
+      VimClient.server_name = 'unknown_server'
+      expect do
+        VimClient.send_keys(':foo<cr>')
+      end.to raise_error(
+        VimClient::Error,
+        "No registered Vim server found for 'unknown_server'"
+      )
+    end
+
+    it 'will always return nil' do
+      VimClient.send_keys(':echo "foo"<cr>').should be_nil
+    end
+
+    it 'will not report invalid commands' do
+      VimClient.send_keys(':foo<cr>').should be_nil
+    end
+
+    it 'will not block' do
+      start = Time.now
+      VimClient.send_keys(':sleep 1<cr>')
+      (Time.now - start).should be < 1
+    end
+
+  end # describe '.send_keys'
+
+  describe '.send_expr' do
+
+    it 'should send an expression' do
+      VimClient.send_expr('2+2').should == '4'
+    end
+
+    it 'should raise an error if server_name is not set' do
+      VimClient.server_name = nil
+      expect do
+        VimClient.send_expr('2+2')
+      end.to raise_error(VimClient::Error, 'server_name must be set')
+    end
+
+    it 'should raise an error if server not found' do
+      VimClient.server_name = 'unknown_server'
+      expect do
+        VimClient.send_expr('2+2')
+      end.to raise_error(
+        VimClient::Error,
+        "No registered Vim server found for 'unknown_server'"
+      )
+    end
+
+    it 'should raise an error for invalid expressions' do
+      expect do
+        VimClient.send_expr('foo')
+      end.to raise_error(VimClient::ExprError)
+    end
+
+  end # describe '.send_expr'
+
+  describe '.send_keys2' do
+
+    it 'should wait for a response, using default callback' do
+      start = Time.now
+      ret = VimClient.send_keys2(':sleep 1<cr>')
+      (Time.now - start).should be > 1
+      # default callback returns an empty string
+      ret.should == ''
+    end
+
+    it 'should wait for the callback response' do
+      VimClient.send_keys2(
+        ':call setline(1,"foo")<cr>', 'getline(1)'
+      ).should == 'foo'
+    end
+
+    # The timeout here is due to an error running server2client()
+    # on the server (E730: Using List as a String)
+    # Just like send_keys(), errors on the server are not returned.
+    it 'requires callback expression to return a string' do
+      expect do
+        VimClient.send_keys2(
+          ':call setline(1,["foo","bar"])<cr>', 'getline(1,"$")')
+      end.to raise_error(VimClient::TimeoutError)
+
+      VimClient.send_keys2(
+        ':call setline(1,["foo","bar"])<cr>', 'join(getline(1,"$"),"\n")'
+      ).should == "foo\nbar"
+    end
+
+    it 'should raise an error if keys and expr use different encodings' do
+      expect do
+        VimClient.send_keys2(
+                  ':echo "foo"', 'localtime()'.encode('ISO-8859-1'))
+      end.to raise_error(
+        VimClient::Error, "'keys' and 'expr' must use the same encoding"
+      )
+    end
+
+  end # describe '.send_keys2'
+
+  describe 'character encoding',
+        :unless => `gvim --version | grep '+multi_byte'`.empty? do
+
+    it 'should mark all Vim Unicode responses as UTF-8' do
+      %w{ ucs-2 ucs-2le utf-16 utf-16le ucs-4 ucs-4le }.each do |enc_name|
+        VimClient.send_keys2(":set enc=#{ enc_name }<cr>")
+        ret = VimClient.send_expr('&encoding')
+        # the server will report the encoding that was set
+        ret.should == enc_name
+        # however the response is actually in UTF-8, and we mark it as such.
+        ret.encoding.name.should == 'UTF-8'
+      end
+    end
+
+    # The following tests will fail due to the returned text including
+    # invalid UTF-8 if the server is running in standard Ex mode.
+    # When using send_keys/send_keys2 (i.e. --remote-send) along with
+    # setline(), the ü gets converted to <fc>. This is not the case if
+    # send_expr()/--remote-expr is used.
+    #
+    # There are two ways this can be solved:
+    #   1. Run the server in Improved Ex mode (-E).
+    #   2. Run the server in Ex mode (-e), then switch to 'visual' mode.
+
+    # Vim treats all Unicode encodings as UTF-8, so any commands sent in these
+    # encodings are converted to UTF-8 before being sent to the server.
+    it 'should convert non-UTF-8 Unicode commands to UTF-8' do
+      utf8 = "\u00FC" # ü
+      utf8_expr = "setline(1,\"#{ utf8 }\")"
+      utf8_keys = ":call setline(1,\"#{ utf8 }\")<cr>"
+      utf8_callback = 'getline(1)'
+
+      VimClient.send_keys2(":set enc=utf-8<cr>")
+
+      %w{ UTF-16BE UTF-16LE UTF-32LE UTF-32BE }.each do |enc|
+        VimClient.send_expr(utf8_expr.encode(enc))
+        VimClient.send_expr(utf8_callback).should == utf8
+
+        VimClient.send_keys2(
+          utf8_keys.encode(enc), utf8_callback.encode(enc)
+        ).should == utf8
+      end
+    end
+
+    it 'should handle encoding conversions' do
+      [ # Ruby Encoding  Vim Encoding  UTF-8      Character   Encoded
+        ['ISO-8859-1',   'latin1',      "\u00FC"],  # ü       "\xFC"
+        ['ISO-8859-15',  'iso-8859-15', "\u20AC"],  # €       "\xA4"
+        ['IBM437',       'cp437',       "\u03B4"],  # δ       "\xEB"
+        ['Shift_JIS',    'sjis',        "\u3042"],  # あ      "\x{82A0}"
+        ['EUC-JP',       'euc-jp',      "\u3042"]   # あ      "\x{A4A2}"
+      ].each do |enc, vim_enc, utf8|
+        utf8_expr = "setline(1,\"#{ utf8 }\")"
+        utf8_keys = ":call setline(1,\"#{ utf8 }\")<cr>"
+        utf8_callback = 'getline(1)'
+
+        ##
+        # Set Vim server encoding to UTF-8
+        #
+        VimClient.send_keys2(':set enc=utf-8<cr>')
+        ret = VimClient.send_expr('&encoding')
+        # response is in UTF-8
+        ret.encoding.name.should == 'UTF-8'
+        # server's encoding was set
+        ret.should == 'utf-8'
+
+        ##
+        # Commands are sent in the tested encoding.
+        # Results received as UTF-8
+        #
+        VimClient.send_expr(utf8_expr.encode(enc))
+        VimClient.send_expr(utf8_callback).should == utf8
+
+        VimClient.send_keys2(
+          utf8_keys.encode(enc), utf8_callback.encode(enc)
+        ).should == utf8
+
+        ##
+        # Set Vim server encoding to the tested encoding.
+        #
+        VimClient.send_keys2(":set enc=#{ vim_enc }<cr>")
+        ret = VimClient.send_expr('&encoding')
+        # response is in the tested encoding
+        ret.encoding.name.should == enc
+        # server's encoding was set
+        ret.should == vim_enc
+
+        ##
+        # Commands are sent as UTF-8
+        # Results received in the tested encoding
+        VimClient.send_expr(utf8_expr)
+        VimClient.send_expr(utf8_callback).should == utf8.encode(enc)
+
+        VimClient.send_keys2(
+          utf8_keys, utf8_callback
+        ).should == utf8.encode(enc)
+      end
+    end
+
+  end # describe 'character encoding'
+
+end