neovim 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92074f47bd93b7fbca51aa3b74e813adb8b1004c
-  data.tar.gz: 2c19393d6a5c38342bc30350e5c5da352fff101c
+  metadata.gz: 7e20e3f4df52ff80bb9e0aa9826d5c6c723d2cc6
+  data.tar.gz: 04019ea3e3e7bb33d231d8a2160a2320f62ca365
 SHA512:
-  metadata.gz: 0c22b67f54f42edcdbc7a062ff972725508c69810627dd51e3c5ece458dd9c1187cc6e87149044dd4786302181297d5ebc3acb8ed4b29a33c069e2c61c0cb52b
-  data.tar.gz: 3c9dc7fc608a08a0db6ed8a9174b93b5487163745661174c883fe2726be02259e448b1e3e8c79bfda25b082d012e27bdc5fc22fed78e2e826f7395faf669a0f8
+  metadata.gz: d3a46053cf6e54b97ef541cf314062ee3ed597a61b642e1d3be7355c60d1b568fe35e0dd76b8b22dd9f5e82cbcdd981ca83d09a596dbbaacbb7221530169d510
+  data.tar.gz: ae0fc91672a39bda8c0a2c756c0a27db7360a8428cb5ab7cdfe9423a25a97d3f3d968d51c0fd42ac986582f32a44eb511a75d6d58213c9384b76483a47b655da

data/.travis.yml

@@ -25,6 +25,9 @@ addons:
       - g++
       - pkg-config
 
+cache:
+  - apt
+  - bundler
+
 env: REPORT_COVERAGE=1
-before_script: travis_retry bundle exec rake neovim:install
-script: bundle exec rake
+script: bundle exec rake spec:ci

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 0.0.6
+- Update Session with improved Fiber coordination
+- Documentation
+- Rename APIInfo -> API
+- Rename Object -> RemoteObject
+
+# 0.0.5
+- Various fixes for Ruby remote plugins
+- Move Current#range and #range= methods to Buffer
+- Add better logging
+
 # 0.0.4
 - Add support for loading Ruby remote plugins from nvim
 - Add Current#range to return a LineRange enumerable object

data/README.md

@@ -3,6 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/neovim.svg)](https://badge.fury.io/rb/neovim)
 [![Travis](https://travis-ci.org/alexgenco/neovim-ruby.svg?branch=master)](https://travis-ci.org/alexgenco/neovim-ruby)
 [![Coverage Status](https://coveralls.io/repos/alexgenco/neovim-ruby/badge.png)](https://coveralls.io/r/alexgenco/neovim-ruby)
+[![Code Climate](https://codeclimate.com/github/alexgenco/neovim-ruby/badges/gpa.svg)](https://codeclimate.com/github/alexgenco/neovim-ruby)
 
 Ruby bindings for [Neovim](https://github.com/neovim/neovim).
 
@@ -37,7 +38,9 @@ require "neovim"
 client = Neovim.attach_unix("/tmp/nvim.sock")
 ```
 
-The client's interface is generated at runtime from the `vim_get_api_info` RPC call. For now, you can refer to the Node client's auto-generated [API description](https://github.com/neovim/node-client/blob/master/index.d.ts). Note that methods will be in `snake_case` rather than `camelCase`.
+The client's interface is generated at runtime from the `vim_get_api_info` RPC call. Refer to the [docs](http://www.rubydoc.info/github/alexgenco/neovim-ruby/master/Neovim/Client) for details.
+
+### Plugins
 
 The `neovim-ruby-host` executable can be used to spawn Ruby plugins via the `rpcstart` command. A plugin can be defined like this:
 
@@ -52,9 +55,8 @@ Neovim.plugin do |plug|
     nvim.current.line = str
   end
 
-  # Define a function called "Sum" which sets the current line. This function
-  # is executed synchronously, so the result of the block will be returned to
-  # nvim.
+  # Define a function called "Sum" which adds two numbers. This function is
+  # executed synchronously, so the result of the block will be returned to nvim.
   plug.function(:Sum, :nargs => 2, :sync => true) do |nvim, x, y|
     x + y
   end
@@ -68,6 +70,15 @@ end
 
 After a call to `:UpdateRemotePlugins`, plugins will be auto-loaded from the `$VIMRUNTIME/rplugin/ruby` directory.
 
+## Links
+
+* Source: <http://github.com/alexgenco/neovim-ruby>
+* Bugs:   <http://github.com/alexgenco/neovim-ruby/issues>
+* CI: <http://travis-ci.org/alexgenco/neovim-ruby>
+* Documentation:
+    * Latest Gem: <http://rubydoc.info/gems/neovim>
+    * Master: <http://rubydoc.info/github/alexgenco/neovim-ruby/master/frames>
+
 ## Contributing
 
 1. Fork it (http://github.com/alexgenco/neovim-ruby/fork)

data/Rakefile

@@ -2,20 +2,24 @@ require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
-task :default => :spec
+
+namespace :spec do
+  desc "Build Neovim and run specs on CI"
+  task :ci => ["neovim:build", :spec]
+end
 
 namespace :neovim do
   vendor = File.expand_path("../vendor/neovim", __FILE__)
 
-  desc "Install Neovim"
-  task :install do
+  desc "Build Neovim"
+  task :build do
     sh "git submodule update --init && " +
        "cd #{vendor} && " +
        "make distclean && " +
        "make"
   end
 
-  desc "Update Neovim installation"
+  desc "Update vendored Neovim revision"
   task :update do
     sh "git submodule update --init && " +
        "cd #{vendor} && " +
@@ -23,4 +27,60 @@ namespace :neovim do
        "git pull origin master && " +
        "make"
   end
+
+  desc "Generate Neovim remote API docs"
+  task :generate_docs do
+    require "neovim"
+    require "pathname"
+
+    vim_docs = []
+    buffer_docs = []
+    window_docs = []
+    tabpage_docs = []
+    session = Neovim::Session.child(%w(-u NONE -n -N))
+
+    session.request(:vim_get_api_info)[1]["functions"].each do |func|
+      prefix, method_name = func["name"].split("_", 2)
+      return_type = func["return_type"]
+      params = func["parameters"]
+      params.shift unless prefix == "vim"
+      param_names = params.map(&:last)
+      param_str = params.empty? ? "" : "(#{param_names.join(", ")})"
+      method_decl = "@method #{method_name}#{param_str}"
+      param_docs = params.map do |type, name|
+        "  @param [#{type}] #{name}"
+      end
+      return_doc = "  @return [#{return_type}]\n"
+      method_doc = [method_decl, *param_docs, return_doc].join("\n")
+      method_doc.gsub!(/ArrayOf\((\w+)[^)]*\)/, 'Array<\1>')
+      method_doc.gsub!(/Integer/, "Fixnum")
+
+      case prefix
+      when "vim"
+        vim_docs << method_doc
+      when "buffer"
+        buffer_docs << method_doc
+      when "tabpage"
+        tabpage_docs << method_doc
+      when "window"
+        window_docs << method_doc
+      end
+    end
+
+    lib_dir = Pathname.new(File.expand_path("../lib/neovim", __FILE__))
+    {
+      "client.rb" => vim_docs,
+      "buffer.rb" => buffer_docs,
+      "tabpage.rb" => tabpage_docs,
+      "window.rb" => window_docs,
+    }.each do |filename, docs|
+      path = lib_dir.join(filename)
+      contents = File.read(path)
+      doc_str = ["=begin", *docs, "=end"].join("\n")
+
+      File.write(path, contents.sub(/=begin.+=end/m, doc_str))
+    end
+  end
 end
+
+task :default => :spec

data/bin/j2mp

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+#
+# Convert STDIN from JSON to MessagePack.
+require "json"
+require "msgpack"
+
+ARGF.binmode
+puts MessagePack.pack(JSON.parse(ARGF.read.strip))

data/bin/mp2j

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+#
+# Convert STDIN from MessagePack to JSON
+require "json"
+require "msgpack"
+
+ARGF.binmode
+puts JSON.dump(MessagePack.unpack(ARGF.read.strip))

data/lib/neovim.rb

@@ -6,27 +6,99 @@ require "neovim/msgpack_stream"
 require "neovim/session"
 require "neovim/plugin"
 
+# The main entrypoint to the +Neovim+ gem. It allows you to connect to a
+# running +nvim+ instance programmatically or define a remote plugin to be
+# autoloaded by +nvim+.
+#
+# You can connect to a running +nvim+ instance by setting or inspecting the
+# +NVIM_LISTEN_ADDRESS+ environment variable and connecting via the appropriate
+# +attach_+ method. This is currently supported for both UNIX domain sockets
+# and TCP. You can also spawn and connect to an +nvim+ subprocess via
+# +Neovim.attach_child(argv)+.
+#
+# You can define a remote plugin using the +Neovim.plugin+ DSL, which allows
+# you to register commands, functions, and autocmds. Plugins are autoloaded by
+# +nvim+ from the +rplugin/ruby+ directory in your +nvim+ runtime path.
+#
+# @example Connect over a TCP socket
+#   Neovim.attach_tcp("0.0.0.0", 3333) # => Neovim::Client
+#
+# @example Connect over a UNIX domain socket
+#   Neovim.attach_unix("/tmp/nvim.sock") # => Neovim::Client
+#
+# @example Spawn and connect to a child +nvim+ process
+#   Neovim.attach_child(["-u", "NONE"]) # => Neovim::Client
+#
+# @example Define a Ruby plugin
+#   # ~/.config/nvim/rplugin/ruby/plugin.rb
+#
+#   Neovim.plugin do |plug|
+#     # Define a command called "SetLine" which sets the contents of the
+#     # current line. This command is executed asynchronously, so the return
+#     # value is ignored.
+#     plug.command(:SetLine, :nargs => 1) do |nvim, str|
+#       nvim.current.line = str
+#     end
+#
+#     # Define a function called "Sum" which adds two numbers. This function is
+#     # executed synchronously, so the result of the block will be returned to
+#     # nvim.
+#     plug.function(:Sum, :nargs => 2, :sync => true) do |nvim, x, y|
+#       x + y
+#     end
+#
+#     # Define an autocmd for the BufEnter event on Ruby files.
+#     plug.autocmd(:BufEnter, :pattern => "*.rb") do |nvim|
+#       nvim.command("echom 'Ruby file, eh?'")
+#     end
+#   end
+#
+# @see Client
+# @see Plugin::DSL
 module Neovim
   class << self
-    attr_accessor :__configured_plugin_manifest, :__configured_plugin_path
+    # @api private
+    # @return [Manifest, nil]
+    attr_accessor :__configured_plugin_manifest
+
+    # @api private
+    # @return [String, nil]
+    attr_accessor :__configured_plugin_path
   end
 
+  # Connect to a running +nvim+ instance over TCP.
+  #
+  # @param host [String] The hostname or IP address
+  # @param port [Fixnum] The port
+  # @return [Client]
+  # @see Session.tcp
   def self.attach_tcp(host, port)
-    attach_event_loop(EventLoop.tcp(host, port))
+    Client.new(Session.tcp(host, port).discover_api)
   end
 
+  # Connect to a running +nvim+ instance over a UNIX domain socket.
+  #
+  # @param socket_path [String] The socket path
+  # @return [Client]
+  # @see Session.unix
   def self.attach_unix(socket_path)
-    attach_event_loop(EventLoop.unix(socket_path))
+    Client.new(Session.unix(socket_path).discover_api)
   end
 
+  # Spawn and connect to a child +nvim+ process.
+  #
+  # @param argv [Array] The arguments to pass to the spawned process
+  # @return [Client]
+  # @see Session.child
   def self.attach_child(argv=[])
-    attach_event_loop(EventLoop.child(argv))
-  end
-
-  def self.start_host(rplugin_paths)
-    Host.load_from_files(rplugin_paths).run
+    Client.new(Session.child(argv).discover_api)
   end
 
+  # Define an +nvim+ remote plugin using the plugin DSL.
+  #
+  # @yield [Plugin::DSL]
+  # @return [Plugin]
+  # @see Plugin::DSL
   def self.plugin(&block)
     Plugin.from_config_block(__configured_plugin_path, &block).tap do |plugin|
       if __configured_plugin_manifest.respond_to?(:register)
@@ -35,20 +107,31 @@ module Neovim
     end
   end
 
+  # Start a plugin host. This is called by the +nvim-ruby-host+ executable,
+  # which is spawned by +nvim+ to discover and run Ruby plugins, and acts as
+  # the bridge between +nvim+ and the plugin.
+  #
+  # @param rplugin_paths [Array<String>] The paths to remote plugin files
+  # @return [void]
+  # @see Host
+  def self.start_host(rplugin_paths)
+    Host.load_from_files(rplugin_paths).run
+  end
+
+  # Set the Neovim global logger.
+  #
+  # @param logger [Logger] The target logger
+  # @return [Logger]
+  # @see Logging
   def self.logger=(logger)
     Logging.logger = logger
   end
 
+  # The Neovim global logger.
+  #
+  # @return [Logger]
+  # @see Logging
   def self.logger
     Logging.logger
   end
-
-  def self.attach_event_loop(event_loop)
-    msgpack_stream = MsgpackStream.new(event_loop)
-    async_session = AsyncSession.new(msgpack_stream)
-    session = Session.new(async_session)
-
-    Client.new(session)
-  end
-  private_class_method :attach_event_loop
 end

data/lib/neovim/api.rb

@@ -0,0 +1,84 @@
+module Neovim
+  class API
+    # Represents an unknown API. Used as a stand-in when the API hasn't been
+    # discovered yet via the +vim_get_api_info+ RPC call.
+    #
+    # @return [API]
+    def self.null
+      new([nil, {"functions" => [], "types" => []}])
+    end
+
+    def initialize(data)
+      @data = data
+    end
+
+    # Return all functions defined by the API, as +Function+ objects.
+    #
+    # @return [Array<Function>]
+    # @see Function
+    def functions
+      @functions ||= @data.fetch(1).fetch("functions").map do |func|
+        Function.new(func["name"], func["async"])
+      end
+    end
+
+    # Return information about +nvim+ types. Used for registering MessagePack
+    # +ext+ types.
+    #
+    # @return [Hash]
+    def types
+      @types ||= @data.fetch(1).fetch("types")
+    end
+
+    # Return the channel ID of the current RPC session.
+    #
+    # @return [Fixnum, nil]
+    def channel_id
+      @channel_id ||= @data.fetch(0)
+    end
+
+    # Return a list of functions with the given name prefix.
+    #
+    # @param prefix [String] The function prefix
+    # @return [Array<Function>]
+    def functions_with_prefix(prefix)
+      functions.select do |function|
+        function.name =~ /\A#{prefix}/
+      end
+    end
+
+    # Find a function with the given name.
+    #
+    # @param name [String] The name of the function
+    # @return [Function, nil]
+    def function(name)
+      functions.find do |func|
+        func.name == name.to_s
+      end
+    end
+
+    # Truncate the output of inspect so console sessions are more pleasant.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class}:0x%x @types={...} @functions={...}>" % (object_id << 1)
+    end
+
+    # Encapsulate an RPC function.
+    class Function < Struct.new(:name, :async)
+      # Apply this function to a running RPC session. Sends either a request if
+      # +async+ is +false+ or a notification if +async+ is +true+.
+      #
+      # @param session [Session] The session to apply the function to.
+      # @param *args [Array] Arguments to the function.
+      # @return [Object, nil]
+      def call(session, *args)
+        if async
+          session.notify(name, *args)
+        else
+          session.request(name, *args)
+        end
+      end
+    end
+  end
+end

data/lib/neovim/async_session.rb

@@ -3,6 +3,9 @@ require "neovim/request"
 require "neovim/notification"
 
 module Neovim
+  # Handles formatting RPC requests and writing them to the
+  # +MsgpackStream+. This exposes an asynchronous API, in which responses
+  # are handled in callbacks.
   class AsyncSession
     include Logging
 
@@ -12,49 +15,99 @@ module Neovim
       @pending_requests = {}
     end
 
-    def register_session(session)
-      @msgpack_stream.register_session(session)
-    end
-
+    # Send an RPC request and enqueue it's callback to be called when a
+    # response is received.
+    #
+    # @param method [Symbol, String] The RPC method name
+    # @param *args [Array] The arguments to the RPC method
+    # @return [self]
+    # @example
+    #   async_session.request(:vim_strwidth, "foobar") do |response|
+    #     $stderr.puts("Got a response #{response}")
+    #   end
     def request(method, *args, &response_cb)
       reqid = @request_id
       @request_id += 1
 
-      @msgpack_stream.send([0, reqid, method, args])
+      @msgpack_stream.write([0, reqid, method, args])
       @pending_requests[reqid] = response_cb || Proc.new {}
       self
     end
 
+    # Send an RPC notification. Notifications don't receive a response
+    # from +nvim+.
+    #
+    # @param method [Symbol, String] The RPC method name
+    # @param *args [Array] The arguments to the RPC method
+    # @return [self]
+    # @example
+    #   async_session.notify(:vim_input, "jk")
     def notify(method, *args)
-      @msgpack_stream.send([2, method, args])
+      @msgpack_stream.write([2, method, args])
       self
     end
 
-    def run(request_cb=nil, notification_cb=nil, setup_cb=nil)
-      request_cb ||= Proc.new {}
-      notification_cb ||= Proc.new {}
-      setup_cb ||= Proc.new {}
-
-      msg_cb = Proc.new do |msg|
-        kind, *rest = msg
+    # Run the event loop, yielding received RPC messages to the block. RPC
+    # requests and notifications from +nvim+ will be wrapped in +Request+
+    # and +Notification+ objects, respectively, and responses will be
+    # passed to their callbacks with optional errors.
+    #
+    # @param session [Session] The current session
+    # @yield [Object]
+    # @return [void]
+    # @see MsgpackStream#run
+    # @see EventLoop#run
+    def run(session=nil, &callback)
+      @msgpack_stream.run(session) do |msg|
+        kind, *payload = msg
 
         case kind
         when 0
-          reqid, method, args = rest
-          request_cb.call(Request.new(method, args, @msgpack_stream, reqid))
+          handle_request(payload, callback)
         when 1
-          reqid, (_, error), result = rest
-          @pending_requests.fetch(reqid).call(error, result)
+          handle_response(payload)
         when 2
-          method, args = rest
-          notification_cb.call(Notification.new(method, args))
+          handle_notification(payload, callback)
         end
       end
-
-      @msgpack_stream.run(msg_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
+      @msgpack_stream.stop
+    end
+
+    # Shut down the event loop.
+    #
+    # @return [void]
+    # @see EventLoop#shutdown
+    def shutdown
+      @msgpack_stream.shutdown
+    end
+
+    private
+
+    def handle_request(payload, callback)
+      callback ||= Proc.new {}
+      reqid, method, args = payload
+      callback.call(Request.new(method, args, @msgpack_stream, reqid))
+    end
+
+    def handle_response(payload)
+      reqid, (_, error), result = payload
+      @pending_requests.delete(reqid).call(error, result)
+    end
+
+    def handle_notification(payload, callback)
+      callback ||= Proc.new {}
+      method, args = payload
+      callback.call(Notification.new(method, args))
+    end
   end
 end