neovim 0.0.5 → 0.0.6

data/lib/neovim/host.rb

@@ -7,6 +7,20 @@ module Neovim
 
     attr_reader :manifest
 
+    # Load plugin definitions and instantiate a new +Host+. This temporarily
+    # mutates global state on the +Neovim+ module so that +Neovim.plugin+ calls
+    # will be registered correctly with the provided +Manifest+.
+    #
+    # @overload load_from_files(rplugin_paths)
+    #   @param rplugin_paths [Array<String>] The remote plugin paths.
+    #
+    # @overload load_from_files(rplugin_paths, target_manifest)
+    #   @param rplugin_paths [Array<String>] The remote plugin paths.
+    #   @param target_manifest [Manifest] The plugin manifest.
+    #
+    # @return [Host]
+    # @see Neovim.start_host
+    # @see Neovim.plugin
     def self.load_from_files(rplugin_paths, target_manifest=Manifest.new)
       old_manifest = Neovim.__configured_plugin_manifest
       old_path = Neovim.__configured_plugin_path
@@ -26,20 +40,19 @@ module Neovim
       end
     end
 
-    def initialize(manifest)
+    def initialize(manifest, session=nil)
+      @session = session || Session.stdio
       @manifest = manifest
-      @event_loop = EventLoop.stdio
-      @msgpack_stream = MsgpackStream.new(@event_loop)
-      @async_session = AsyncSession.new(@msgpack_stream)
     end
 
+    # Run the event loop, passing received messages to the manifest.
+    #
+    # @return [void]
     def run
-      callback = Proc.new do |msg|
+      @session.run do |msg|
         debug("received #{msg.inspect}")
         @manifest.handle(msg, client)
       end
-
-      @async_session.run(callback, callback)
     rescue => e
       fatal("got unexpected error #{e}")
       debug(e.backtrace.join("\n"))
@@ -48,7 +61,7 @@ module Neovim
     private
 
     def client
-      @client ||= Client.new(Session.new(@async_session))
+      @client ||= Client.new(@session.discover_api)
     end
   end
 end

data/lib/neovim/line_range.rb

@@ -1,4 +1,5 @@
 module Neovim
+  # Provide an enumerable interface for dealing with ranges of lines.
   class LineRange
     include Enumerable
 
@@ -8,53 +9,92 @@ module Neovim
       @end = _end
     end
 
+    # @return [Array<String>]
     def to_a
       @buffer.get_line_slice(@begin, @end, true, true)
     end
 
+    # @yield [String] The current line
+    # @return [Array<String>]
     def each(&block)
       to_a.each(&block)
     end
 
-    def [](idx, len=nil)
-      case idx
+    # @overload [](index)
+    #   @param index [Fixnum]
+    #
+    # @overload [](range)
+    #   @param range [Range]
+    #
+    # @overload [](index, length)
+    #   @param index [Fixnum]
+    #   @param length [Fixnum]
+    #
+    # @example Get the first line using an index
+    #   line_range[0] # => "first"
+    # @example Get the first two lines using a +Range+
+    #   line_range[0..1] # => ["first", "second"]
+    # @example Get the first two lines using an index and length
+    #   line_range[0, 2] # => ["first", "second"]
+    def [](pos, len=nil)
+      case pos
       when ::Range
-        _end = idx.exclude_end? ? idx.end - 1 : idx.end
-        LineRange.new(@buffer, idx.begin, _end)
+        _end = pos.exclude_end? ? pos.end - 1 : pos.end
+        LineRange.new(@buffer, pos.begin, _end)
       else
         if len
-          LineRange.new(@buffer, idx, idx + len - 1)
+          LineRange.new(@buffer, pos, pos + len - 1)
         else
-          @buffer.get_line(idx)
+          @buffer.get_line(pos)
         end
       end
     end
     alias_method :slice, :[]
 
+    # @overload []=(index, string)
+    #   @param index [Fixnum]
+    #   @param string [String]
+    #
+    # @overload []=(index, length, strings)
+    #   @param index [Fixnum]
+    #   @param length [Fixnum]
+    #   @param strings [Array<String>]
+    #
+    # @overload []=(range, strings)
+    #   @param range [Range]
+    #   @param strings [Array<String>]
+    #
+    # @example Replace the first line using an index
+    #   line_range[0] = "first"
+    # @example Replace the first two lines using a +Range+
+    #   line_range[0..1] = ["first", "second"]
+    # @example Replace the first two lines using an index and length
+    #   line_range[0, 2] = ["first", "second"]
     def []=(*args)
       *target, val = args
-      idx, len = target
+      pos, len = target
 
-      case idx
+      case pos
       when ::Range
         @buffer.set_line_slice(
-          idx.begin,
-          idx.end,
+          pos.begin,
+          pos.end,
           true,
-          !idx.exclude_end?,
+          !pos.exclude_end?,
           val
         )
       else
         if len
-          @buffer.set_line_slice(idx, idx + len, true, false, val)
+          @buffer.set_line_slice(pos, pos + len, true, false, val)
         else
-          @buffer.set_line(idx, val)
+          @buffer.set_line(pos, val)
         end
       end
     end
 
-    def replace(other_ary)
-      self[0..-1] = other_ary
+    # @param other [Array] The replacement lines
+    def replace(other)
+      self[0..-1] = other
       self
     end
   end

data/lib/neovim/logging.rb

@@ -2,11 +2,15 @@ require "logger"
 require "stringio"
 
 module Neovim
+  # Mixed into classes for unified logging helper methods.
   module Logging
     class << self
       attr_writer :logger
     end
 
+    # Return the value of @logger, or construct it from the environment.
+    # $NVIM_RUBY_LOG_FILE specifies a file to log to (default +STDOUT+), while
+    # NVIM_RUBY_LOG_LEVEL specifies the level (default +WARN+)
     def self.logger
       return @logger if instance_variable_defined?(:@logger)
 

data/lib/neovim/manifest.rb

@@ -11,6 +11,9 @@ module Neovim
       @specs = {}
     end
 
+    # Register a +Plugin+ to receive +Host+ messages.
+    #
+    # @param plugin [Plugin]
     def register(plugin)
       plugin.handlers.each do |handler|
         wrapped_handler = handler.sync? ? wrap_sync(handler) : wrap_async(handler)
@@ -20,9 +23,14 @@ module Neovim
       @specs[plugin.source] = plugin.specs
     end
 
-    def handle(msg, client)
-      default_handler = msg.sync? ? default_sync_handler : default_async_handler
-      @handlers.fetch(msg.method_name, default_handler).call(client, msg)
+    # Handle messages received from the host. Sends a +Neovim::Client+ along
+    # with the message to be used in plugin callbacks.
+    #
+    # @param message [Neovim::Request, Neovim::Notification]
+    # @param client [Neovim::Client]
+    def handle(message, client)
+      default_handler = message.sync? ? default_sync_handler : default_async_handler
+      @handlers.fetch(message.method_name, default_handler).call(client, message)
     rescue => e
       fatal("got unexpected error #{e}")
       debug(e.backtrace.join("\n"))

data/lib/neovim/msgpack_stream.rb

@@ -2,6 +2,8 @@ require "neovim/logging"
 require "msgpack"
 
 module Neovim
+  # Handles serializing RPC messages to MessagePack and passing them to
+  # the event loop
   class MsgpackStream
     include Logging
 
@@ -10,35 +12,67 @@ module Neovim
       @unpacker = MessagePack::Unpacker.new
     end
 
-    def register_session(session)
-      session.api_info.types.each do |type, info|
-        klass = Neovim.const_get(type)
-        id = info.fetch("id")
-
-        @unpacker.register_type(id) do |data|
-          klass.new(MessagePack.unpack(data), session)
-        end
-      end
-    end
-
-    def send(msg)
-      debug("sending #{msg.inspect}")
-      @event_loop.send(MessagePack.pack(msg))
+    # Serialize an RPC message to and write it to the event loop.
+    #
+    # @param msg [Array] The RPC message
+    # @return [self]
+    # @example Write an RPC request
+    #   msgpack_stream.write([0, 1, :vim_strwidth, ["foobar"]])
+    def write(msg)
+      debug("writing #{msg.inspect}")
+      @event_loop.write(MessagePack.pack(msg))
       self
     end
 
-    def run(message_cb, setup_cb=nil)
-      data_cb = Proc.new do |data|
+    # Run the event loop, yielding deserialized messages to the block.
+    #
+    # @param session [Session] Used for registering msgpack +ext+ types as
+    #   described by the +vim_get_api_info+ call
+    # @return [void]
+    # @see EventLoop#run
+    def run(session=nil)
+      register_types(session)
+
+      @event_loop.run do |data|
         @unpacker.feed_each(data) do |msg|
           debug("received #{msg.inspect}")
-          message_cb.call(msg)
+          yield msg if block_given?
         end
       end
-
-      @event_loop.run(data_cb, setup_cb)
     rescue => e
       fatal("got unexpected error #{e}")
       debug(e.backtrace.join("\n"))
     end
+
+    # Stop the event loop.
+    #
+    # @return [void]
+    # @see EventLoop#stop
+    def stop
+      @event_loop.stop
+    end
+
+    # Shut down the event loop.
+    #
+    # @return [void]
+    # @see EventLoop#shutdown
+    def shutdown
+      @event_loop.shutdown
+    end
+
+    private
+
+    def register_types(session)
+      return unless session && session.api
+
+      session.api.types.each do |type, info|
+        klass = Neovim.const_get(type)
+        id = info.fetch("id")
+
+        @unpacker.register_type(id) do |data|
+          klass.new(MessagePack.unpack(data), session)
+        end
+      end
+    end
   end
 end

data/lib/neovim/notification.rb

@@ -1,4 +1,6 @@
 module Neovim
+  # An asynchronous message from +nvim+.
+  # @api private
   class Notification
     attr_reader :method_name, :arguments
 

data/lib/neovim/plugin.rb

@@ -1,103 +1,28 @@
+require "neovim/plugin/dsl"
+
 module Neovim
   class Plugin
-    def self.from_config_block(source, &block)
+    attr_accessor :handlers
+    attr_reader :source
+
+    # Entrypoint to the +Neovim.plugin+ DSL.
+    #
+    # @param source [String] The path of the plugin file.
+    # @yield [DSL] The receiver of DSL methods.
+    def self.from_config_block(source)
       new(source).tap do |instance|
-        block.call(DSL.new(instance)) if block
+        yield DSL.new(instance) if block_given?
       end
     end
 
-    attr_accessor :handlers
-    attr_reader :source
-
     def initialize(source)
       @handlers = []
       @source = source
     end
 
+    # @return [Array] Handler specs used by +nvim+ to register plugins.
     def specs
       @handlers.map(&:to_spec)
     end
-
-    class Handler
-      attr_reader :block
-
-      def initialize(source, type, name, sync, options, block)
-        @source = source
-        @type = type.to_sym
-        @name = name.to_s
-        @sync = !!sync
-        @options = options
-        @block = block || ::Proc.new {}
-      end
-
-      def qualified_name
-        if @type == :autocmd
-          pattern = @options.fetch(:pattern, "*")
-          "#{@source}:#{@type}:#{@name}:#{pattern}"
-        else
-          "#{@source}:#{@type}:#{@name}"
-        end
-      end
-
-      def sync?
-        @sync
-      end
-
-      def to_spec
-        {
-          :type => @type,
-          :name => @name,
-          :sync => @sync,
-          :opts => @options,
-        }
-      end
-
-      def call(*args)
-        @block.call(*args)
-      end
-    end
-
-    class DSL < BasicObject
-      def initialize(plugin)
-        @plugin = plugin
-      end
-
-      def command(name, options={}, &block)
-        register_handler(:command, name, options, block)
-      end
-
-      def function(name, options={}, &block)
-        register_handler(:function, name, options, block)
-      end
-
-      def autocmd(name, options={}, &block)
-        register_handler(:autocmd, name, options, block)
-      end
-
-      private
-
-      def register_handler(type, name, _options, block)
-        if type == :autocmd
-          options = _options.dup
-        else
-          options = standardize_range(_options.dup)
-        end
-
-        sync = options.delete(:sync)
-
-        @plugin.handlers.push(
-          Handler.new(@plugin.source, type, name, sync, options, block)
-        )
-      end
-
-      def standardize_range(options)
-        if options.key?(:range)
-          options[:range] = "" if options[:range] == true
-          options[:range] = ::Kernel.String(options[:range])
-        end
-
-        options
-      end
-    end
   end
 end

data/lib/neovim/plugin/dsl.rb

@@ -0,0 +1,81 @@
+require "neovim/plugin/handler"
+
+module Neovim
+  class Plugin
+    # The DSL exposed in +Neovim.plugin+ blocks.
+    class DSL < BasicObject
+      def initialize(plugin)
+        @plugin = plugin
+      end
+
+      # Register an +nvim+ command.
+      #
+      # @param name [String]
+      # @param options [Hash]
+      # @param &block [Proc, nil]
+      #
+      # @option options [Fixnum] :nargs
+      # @option options [Fixnum] :count
+      # @option options [String] :eval
+      # @option options [Boolean] :sync (false)
+      # @option options [Boolean] :bang
+      # @option options [Boolean] :register
+      # @option options [Boolean] :complete
+      # @option options [String, Boolean] :range
+      def command(name, options={}, &block)
+        register_handler(:command, name, options, block)
+      end
+
+      # Register an +nvim+ function.
+      #
+      # @param name [String]
+      # @param options [Hash]
+      # @param &block [Proc, nil]
+      #
+      # @option options [String] :eval
+      # @option options [Boolean] :sync (false)
+      # @option options [String, Boolean] :range
+      def function(name, options={}, &block)
+        register_handler(:function, name, options, block)
+      end
+
+      # Register an +nvim+ autocmd.
+      #
+      # @param event [String]
+      # @param options [Hash]
+      # @param &block [Proc, nil]
+      #
+      # @option options [String] :pattern
+      # @option options [String] :eval
+      # @option options [Boolean] :sync (false)
+      def autocmd(event, options={}, &block)
+        register_handler(:autocmd, event, options, block)
+      end
+
+      private
+
+      def register_handler(type, name, _options, block)
+        if type == :autocmd
+          options = _options.dup
+        else
+          options = standardize_range(_options.dup)
+        end
+
+        sync = options.delete(:sync)
+
+        @plugin.handlers.push(
+          Handler.new(@plugin.source, type, name, sync, options, block)
+        )
+      end
+
+      def standardize_range(options)
+        if options.key?(:range)
+          options[:range] = "" if options[:range] == true
+          options[:range] = ::Kernel.String(options[:range])
+        end
+
+        options
+      end
+    end
+  end
+end