neovim 0.0.5 → 0.0.6

data/lib/neovim/buffer.rb

@@ -1,23 +1,130 @@
-require "neovim/object"
+require "neovim/remote_object"
 require "neovim/line_range"
 
 module Neovim
-  class Buffer < Neovim::Object
+  # Class representing an +nvim+ buffer.
+  class Buffer < RemoteObject
+    # A +LineRange+ object representing the buffer's lines.
+    #
+    # @return [LineRange]
+    # @see LineRange
     def lines
       @lines ||= LineRange.new(self, 0, -1)
     end
 
-    def lines=(arr)
-      lines[0..-1] = arr
+    # Replace all the lines of the buffer.
+    #
+    # @param strs [Array<String>] The replacement lines
+    # @return [Array<String>]
+    def lines=(strs)
+      lines[0..-1] = strs
     end
 
+    # A +LineRange+ object representing the buffer's selection range.
+    #
+    # @return [LineRange]
+    # @see LineRange
     def range
       @range ||= LineRange.new(self, 0, -1)
     end
 
+    # Set the buffer's current selection range.
+    #
+    # @param _range [Range] The replacement range
+    # @return [LineRange]
+    # @see LineRange
     def range=(_range)
       _end = _range.exclude_end? ? _range.end - 1 : _range.end
       @range = LineRange.new(self, _range.begin, _end)
     end
+
+# The following methods are dynamically generated.
+=begin
+@method line_count
+  @return [Fixnum]
+
+@method get_line(index)
+  @param [Fixnum] index
+  @return [String]
+
+@method set_line(index, line)
+  @param [Fixnum] index
+  @param [String] line
+  @return [void]
+
+@method del_line(index)
+  @param [Fixnum] index
+  @return [void]
+
+@method get_line_slice(start, end, include_start, include_end)
+  @param [Fixnum] start
+  @param [Fixnum] end
+  @param [Boolean] include_start
+  @param [Boolean] include_end
+  @return [Array<String>]
+
+@method set_line_slice(start, end, include_start, include_end, replacement)
+  @param [Fixnum] start
+  @param [Fixnum] end
+  @param [Boolean] include_start
+  @param [Boolean] include_end
+  @param [Array<String>] replacement
+  @return [void]
+
+@method get_var(name)
+  @param [String] name
+  @return [Object]
+
+@method set_var(name, value)
+  @param [String] name
+  @param [Object] value
+  @return [Object]
+
+@method get_option(name)
+  @param [String] name
+  @return [Object]
+
+@method set_option(name, value)
+  @param [String] name
+  @param [Object] value
+  @return [void]
+
+@method get_number
+  @return [Fixnum]
+
+@method get_name
+  @return [String]
+
+@method set_name(name)
+  @param [String] name
+  @return [void]
+
+@method is_valid
+  @return [Boolean]
+
+@method insert(lnum, lines)
+  @param [Fixnum] lnum
+  @param [Array<String>] lines
+  @return [void]
+
+@method get_mark(name)
+  @param [String] name
+  @return [Array<Fixnum>]
+
+@method add_highlight(src_id, hl_group, line, col_start, col_end)
+  @param [Fixnum] src_id
+  @param [String] hl_group
+  @param [Fixnum] line
+  @param [Fixnum] col_start
+  @param [Fixnum] col_end
+  @return [Fixnum]
+
+@method clear_highlight(src_id, line_start, line_end)
+  @param [Fixnum] src_id
+  @param [Fixnum] line_start
+  @param [Fixnum] line_end
+  @return [void]
+
+=end
   end
 end

data/lib/neovim/client.rb

@@ -1,31 +1,202 @@
 require "neovim/current"
 
 module Neovim
+  # Client to a running +nvim+ instance. The interface is generated at
+  # runtime via the +vim_get_api_info+ RPC call. Some methods return
+  # +RemoteObject+ subclasses (i.e. +Buffer+, +Window+, or +Tabpage+),
+  # which similarly have dynamically generated interfaces.
+  #
+  # @see Buffer
+  # @see Window
+  # @see Tabpage
   class Client
     attr_reader :session
 
     def initialize(session)
       @session = session
+      @api = session.api
     end
 
+    # Intercept method calls and delegate to appropriate RPC methods.
     def method_missing(method_name, *args)
-      if methods.include?(method_name)
-        @session.request("vim_#{method_name}", *args)
+      if func = @api.function("vim_#{method_name}")
+        func.call(session, *args)
       else
         super
       end
     end
 
+    # Extend +respond_to?+ to support RPC methods.
     def respond_to?(method_name)
-      super || methods.include?(method_name.to_sym)
+      super || rpc_methods.include?(method_name.to_sym)
     end
 
+    # Extend +methods+ to include RPC methods.
     def methods
-      super | @session.api_methods_for_prefix("vim_")
+      super | rpc_methods
     end
 
+    # Access to objects belonging to the current +nvim+ context.
+    #
+    # @return [Current]
+    # @example Get the current buffer
+    #   client.current.buffer
+    # @example Set the current line
+    #   client.current.line = "New line"
+    # @see Current
     def current
       Current.new(@session)
     end
+
+    private
+
+    def rpc_methods
+      @api.functions_with_prefix("vim_").map do |func|
+        func.name.sub(/\Avim_/, "").to_sym
+      end
+    end
+
+    public
+
+# The following methods are dynamically generated.
+=begin
+@method command(str)
+  @param [String] str
+  @return [void]
+
+@method feedkeys(keys, mode, escape_csi)
+  @param [String] keys
+  @param [String] mode
+  @param [Boolean] escape_csi
+  @return [void]
+
+@method input(keys)
+  @param [String] keys
+  @return [Fixnum]
+
+@method replace_termcodes(str, from_part, do_lt, special)
+  @param [String] str
+  @param [Boolean] from_part
+  @param [Boolean] do_lt
+  @param [Boolean] special
+  @return [String]
+
+@method command_output(str)
+  @param [String] str
+  @return [String]
+
+@method eval(str)
+  @param [String] str
+  @return [Object]
+
+@method call_function(fname, args)
+  @param [String] fname
+  @param [Array] args
+  @return [Object]
+
+@method strwidth(str)
+  @param [String] str
+  @return [Fixnum]
+
+@method list_runtime_paths
+  @return [Array<String>]
+
+@method change_directory(dir)
+  @param [String] dir
+  @return [void]
+
+@method get_current_line
+  @return [String]
+
+@method set_current_line(line)
+  @param [String] line
+  @return [void]
+
+@method del_current_line
+  @return [void]
+
+@method get_var(name)
+  @param [String] name
+  @return [Object]
+
+@method set_var(name, value)
+  @param [String] name
+  @param [Object] value
+  @return [Object]
+
+@method get_vvar(name)
+  @param [String] name
+  @return [Object]
+
+@method get_option(name)
+  @param [String] name
+  @return [Object]
+
+@method set_option(name, value)
+  @param [String] name
+  @param [Object] value
+  @return [void]
+
+@method out_write(str)
+  @param [String] str
+  @return [void]
+
+@method err_write(str)
+  @param [String] str
+  @return [void]
+
+@method report_error(str)
+  @param [String] str
+  @return [void]
+
+@method get_buffers
+  @return [Array<Buffer>]
+
+@method get_current_buffer
+  @return [Buffer]
+
+@method set_current_buffer(buffer)
+  @param [Buffer] buffer
+  @return [void]
+
+@method get_windows
+  @return [Array<Window>]
+
+@method get_current_window
+  @return [Window]
+
+@method set_current_window(window)
+  @param [Window] window
+  @return [void]
+
+@method get_tabpages
+  @return [Array<Tabpage>]
+
+@method get_current_tabpage
+  @return [Tabpage]
+
+@method set_current_tabpage(tabpage)
+  @param [Tabpage] tabpage
+  @return [void]
+
+@method subscribe(event)
+  @param [String] event
+  @return [void]
+
+@method unsubscribe(event)
+  @param [String] event
+  @return [void]
+
+@method name_to_color(name)
+  @param [String] name
+  @return [Fixnum]
+
+@method get_color_map
+  @return [Dictionary]
+
+@method get_api_info
+  @return [Array]
+
+=end
   end
 end

data/lib/neovim/current.rb

@@ -3,43 +3,54 @@ require "neovim/tabpage"
 require "neovim/window"
 
 module Neovim
+  # Support for +client.current+ chaining.
+  # @see Client#current
   class Current
     def initialize(session)
       @session = session
     end
 
+    # @return [String]
     def line
       @session.request(:vim_get_current_line)
     end
 
-    def line=(ln)
-      @session.request(:vim_set_current_line, ln)
+    # @param line [String] The target line contents.
+    # @return [String]
+    def line=(line)
+      @session.request(:vim_set_current_line, line)
     end
 
+    # @return [Buffer]
     def buffer
       @session.request(:vim_get_current_buffer)
     end
 
-    def buffer=(buffer_index)
-      buffer = Buffer.new(buffer_index, @session)
+    # @param buffer [Buffer, Fixnum] The target buffer or index.
+    # @return [Buffer, Fixnum]
+    def buffer=(buffer)
       @session.request(:vim_set_current_buffer, buffer)
     end
 
+    # @return [Window]
     def window
       @session.request(:vim_get_current_window)
     end
 
-    def window=(window_index)
-      window = Window.new(window_index, @session)
+    # @param window [Window, Fixnum] The target window or index.
+    # @return [Window, Fixnum]
+    def window=(window)
       @session.request(:vim_set_current_window, window)
     end
 
+    # @return [Tabpage]
     def tabpage
       @session.request(:vim_get_current_tabpage)
     end
 
-    def tabpage=(tabpage_index)
-      tabpage = Tabpage.new(tabpage_index, @session)
+    # @param tabpage [Tabpage, Fixnum] The target tabpage or index.
+    # @return [Tabpage, Fixnum]
+    def tabpage=(tabpage)
       @session.request(:vim_set_current_tabpage, tabpage)
     end
   end

data/lib/neovim/event_loop.rb

@@ -2,38 +2,63 @@ require "neovim/logging"
 require "socket"
 
 module Neovim
+  # The lowest level interface to reading from and writing to +nvim+.
   class EventLoop
     include Logging
 
+    private_class_method :new
+
+    # Connect to a TCP socket.
+    #
+    # @param host [String] The hostname or IP address
+    # @param port [Fixnum] The port
+    # @return [EventLoop]
     def self.tcp(host, port)
       socket = TCPSocket.new(host, port)
-      new(socket, socket)
+      new(socket)
     end
 
+    # Connect to a UNIX domain socket.
+    #
+    # @param path [String] The socket path
+    # @return [EventLoop]
     def self.unix(path)
       socket = UNIXSocket.new(path)
-      new(socket, socket)
+      new(socket)
     end
 
+    # Spawn and connect to a child +nvim+ process.
+    #
+    # @param argv [Array] The arguments to pass to the spawned process
+    # @return [EventLoop]
     def self.child(argv)
       argv = [ENV.fetch("NVIM_EXECUTABLE", "nvim"), "--embed"] | argv
       io = IO.popen(argv, "rb+")
-      new(io, io)
+      new(io)
     end
 
+    # Connect to the current process's standard streams. This is used to
+    # promote the current process to a Ruby plugin host.
+    #
+    # @return [EventLoop]
     def self.stdio
       new(STDIN, STDOUT)
     end
 
-    def initialize(rd, wr)
+    def initialize(rd, wr=rd)
       @rd, @wr = rd, wr
       @running = false
     end
 
-    def send(data)
+    # Write data to the underlying +IO+. This will block until all the
+    # data has been written.
+    #
+    # @param data [String] The data to write (typically message-packed)
+    # @return [self]
+    def write(data)
       start = 0
       size = data.size
-      debug("sending #{data.inspect}")
+      debug("writing #{data.inspect}")
 
       begin
         while start < size
@@ -41,20 +66,24 @@ module Neovim
         end
         self
       rescue IO::WaitWritable
-        IO.select(nil, [@wr])
+        IO.select(nil, [@wr], nil, 1)
         retry
       end
     end
 
-    def run(message_callback, setup_callback=nil)
+    # Run the event loop, reading from the underlying +IO+ and yielding
+    # received messages to the block.
+    #
+    # @yield [String]
+    # @return [void]
+    def run
       @running = true
-      setup_callback.call if setup_callback.respond_to?(:call)
 
       loop do
         break unless @running
         message = @rd.readpartial(1024 * 16)
         debug("received #{message.inspect}")
-        message_callback.call(message)
+        yield message if block_given?
       end
     rescue EOFError
       warn("got EOFError")
@@ -62,5 +91,21 @@ module Neovim
       fatal("got unexpected error #{e}")
       debug(e.backtrace.join("\n"))
     end
+
+    # Stop the event loop.
+    #
+    # @return [void]
+    def stop
+      @running = false
+    end
+
+    # Stop the event loop and close underlying +IO+s.
+    #
+    # @return [void]
+    def shutdown
+      stop
+      [@rd, @wr].each(&:close)
+    rescue IOError
+    end
   end
 end