GitHub PullRequestReviewCommentEvent at 2014-09-14 09:31:07
Repository: neovim
Actor: oni-link
Payload: {"action":"created","comment":{"url":"https://api.github.com/repos/neovim/neovim/pulls/comments/17518294","id":17518294,"diff_hunk":"@@ -0,0 +1,245 @@\n+*msgpack_rpc.txt*    For Nvim.\t\t\t\t\t\t {Nvim}\n+\n+\n+\t\t NVIM REFERENCE MANUAL    by Thiago de Arruda\n+\n+\n+The Msgpack-RPC Interface to Nvim\t\t  *msgpack-rpc*\n+\n+1. Introduction\t\t\t|msgpack-rpc-intro|\n+2. API\t\t\t  \t|msgpack-rpc-api|\n+3. Connecting\t\t\t|msgpack-rpc-connecting|\n+4. Clients\t\t\t|msgpack-rpc-clients|\n+5. Types\t\t\t|msgpack-rpc-types|\n+6. Wrapping methods\t\t|msgpack-rpc-wrap-methods|\n+7. Vimscript functions\t\t|msgpack-rpc-vim-functions|\n+\n+==============================================================================\n+1. Introduction\t\t\t\t\t\t    *msgpack-rpc-intro*\n+\n+The primary means of controlling a running nvim instance is through\n+MessagePack-RPC, a messaging protocol that uses the MessagePack serialization\n+format: https://github.com/msgpack/msgpack/blob/7498cf3/spec.md.\n+From now on, we'll be referring to the protocol as msgpack-rpc.\n+\n+At this point, only plugins use msgpack-rpc, but eventually even user\n+interaction will be achieved through the protocol, since user interfaces will\n+be separate programs that control a headless nvim instance.\n+\n+This is what can be achieved by connecting to the msgpack-rpc interface:\n+\n+- Call any nvim API function\n+- Listen for nvim events\n+- Receive remote calls from nvim\n+\n+Nvim's msgpack-rpc interface can be seen as a more powerful version of Vim's\n+`clientserver` feature.\n+\n+==============================================================================\n+2. API\t\t\t\t\t\t\t      *msgpack-rpc-api*\n+\n+Nvim C API is automatically exposed to the msgpack-rpc interface by the\n+build system, which parses headers at src/nvim/api from the project root. A\n+dispatch function is generated, and it will match msgpack-rpc method names\n+with non-static API functions, converting/validating arguments and return\n+values back to msgpack.\n+\n+Client libraries will normally provide wrappers that hide msgpack-rpc details\n+from programmers, which can be automatically generated by reading bundled api\n+metadata from a compiled nvim instance.\n+\n+There are two ways to obtain API metadata:\n+\n+- By connecting to a running nvim instance and calling `vim_get_api_metadata`\n+  via msgpack-rpc. This is the preferred way for clients written in\n+  dynamically-typed languages, which can define functions at runtime.\n+- Through the `--api-info` command-line option, which makes nvim to dump a\n+  msgpack blob containing the metadata to stdout and exit. This is preferred\n+  when writing clients for statically-typed languages, which require a\n+  separate compilation step.\n+\n+Here's a simple way to get human-readable description of the API(requires\n+python and the pyyaml/msgpack-python pip packages):\n+>\n+    nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml\n+\n+==============================================================================\n+3. Connecting\t\t\t\t\t       *msgpack-rpc-connecting*\n+\n+\n+There are four ways to open msgpack-rpc streams to nvim:\n+\n+1. Through nvim's stdin/stdout when started with the `--embed` option. This\n+   how other programs can embed nvim.\n+\n+2. Through stdin/stdout of a program spawned by the |rpcstart()| function.\n+\n+3. Through the socket automatically created with every instance. To find out\n+   the socket location(which is random by default) from a running nvim\n+   instance, one can inspect the *$NVIM_LISTEN_ADDRESS* environment variable\n+   like this:\n+>\n+    :echo $NVIM_LISTEN_ADDRESS\n+<\n+4. Through a tcp/ip socket. To make nvim listen on a tcp/ip socket, you need\n+   to set the NVIM_LISTEN_ADDRESS environment variable before starting, like\n+   this:\n+>\n+    NVIM_LISTEN_ADDRESS=127.0.0.1:6666 nvim\n+<\n+Connecting to the socket is the easiest way a programmer can test the API,\n+which can be done through any msgpack-rpc client library or a fully-featured\n+Nvim client(which we'll see below). Here's a ruby script that will print the\n+string 'hello world!' on the current nvim instance:\n+>\n+    #!/usr/bin/env ruby\n+    # Requires msgpack-rpc: gem install msgpack-rpc\n+    # \n+    # To run this script, execute it from a running nvim instance(notice the\n+    # trailing '&' which is required since nvim won't process events while\n+    # running a blocking command):\n+    # \n+    #\t:!./hello.rb &\n+    #\n+    # Or from another shell by setting NVIM_LISTEN_ADDRESS:\n+    # $ NVIM_LISTEN_ADDRESS=[address] ./hello.rb\n+\n+    require 'msgpack/rpc'\n+    require 'msgpack/rpc/transport/unix'\n+\n+    vim = MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS'])\n+    result = vim.call(:vim_command, 'echo \"hello world!\"')\n+<\n+A better way is to use the python REPL with the `neovim` package, where API\n+functions can be called interactively:\n+>\n+    >>> import neovim; vim = neovim.connect('[address]')\n+    >>> vim.command('echo \"hello world!\"')\n+<\n+==============================================================================\n+4. Implementing new clients\t\t\t\t  *msgpack-rpc-clients*\n+\n+Nvim is still alpha and there's no in-depth documentation explaining how to\n+properly implement a client library. The python client(neovim pip package)\n+will be always up-to-date with the latest API changes, so it's source code is\n+best documentation currently available. There are some guidelines however:\n+\n+- Separate the transport layer from the rest of the library(See\n+  |msgpack-rpc-connecting| for details of how a client can connect to nvim).\n+- Use a msgpack library that implements the spec version 5, Nvim uses the\n+  BIN/EXT types.\n+- Read api metadata in order to create client-side wrappers for all\n+  msgpack-rpc methods.\n+- Use a single-threaded event loop library/pattern.\n+- Use a fiber/coroutine library for the language you are implementing a client\n+  for. These greatly simplify concurrency and allow the library to expose a\n+  blocking API on top of a non-blocking event loop without the complexity\n+  that comes with preemptive multi-tasking.","path":"runtime/doc/msgpack_rpc.txt","position":137,"original_position":137,"commit_id":"84aff1da6ad8607f67156a810028cdfb0ffedc9f","original_commit_id":"84aff1da6ad8607f67156a810028cdfb0ffedc9f","user":{"login":"oni-link","id":2077655,"avatar_url":"https://avatars.githubusercontent.com/u/2077655?v=2","gravatar_id":"6c9f17d5b731d510dcc360a91e2b9101","url":"https://api.github.com/users/oni-link","html_url":"https://github.com/oni-link","followers_url":"https://api.github.com/users/oni-link/followers","following_url":"https://api.github.com/users/oni-link/following{/other_user}","gists_url":"https://api.github.com/users/oni-link/gists{/gist_id}","starred_url":"https://api.github.com/users/oni-link/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/oni-link/subscriptions","organizations_url":"https://api.github.com/users/oni-link/orgs","repos_url":"https://api.github.com/users/oni-link/repos","events_url":"https://api.github.com/users/oni-link/events{/privacy}","received_events_url":"https://api.github.com/users/oni-link/received_events","type":"User","site_admin":false},"body":"No hypen in \"multi-tasking\"?","created_at":"2014-09-14T09:31:07Z","updated_at":"2014-09-14T09:31:07Z","html_url":"https://github.com/neovim/neovim/pull/1163#discussion_r17518294","pull_request_url":"https://api.github.com/repos/neovim/neovim/pulls/1163","_links":{"self":{"href":"https://api.github.com/repos/neovim/neovim/pulls/comments/17518294"},"html":{"href":"https://github.com/neovim/neovim/pull/1163#discussion_r17518294"},"pull_request":{"href":"https://api.github.com/repos/neovim/neovim/pulls/1163"}}},"pull_request":{"url":"https://api.github.com/repos/neovim/neovim/pulls/1163","id":21176802,"html_url":"https://github.com/neovim/neovim/pull/1163","diff_url":"https://github.com/neovim/neovim/pull/1163.diff","patch_url":"https://github.com/neovim/neovim/pull/1163.patch","issue_url":"https://api.github.com/repos/neovim/neovim/issues/1163","number":1163,"state":"closed","locked":false,"title":"[WIP] Initial documentation of nvim features","user":{"login":"tarruda","id":842846,"avatar_url":"https://avatars.githubusercontent.com/u/842846?v=2","gravatar_id":"164e7269035a0a06248ab8336fb82e9f","url":"https://api.github.com/users/tarruda","html_url":"https://github.com/tarruda","followers_url":"https://api.github.com/users/tarruda/followers","following_url":"https://api.github.com/users/tarruda/following{/other_user}","gists_url":"https://api.github.com/users/tarruda/gists{/gist_id}","starred_url":"https://api.github.com/users/tarruda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tarruda/subscriptions","organizations_url":"https://api.github.com/users/tarruda/orgs","repos_url":"https://api.github.com/users/tarruda/repos","events_url":"https://api.github.com/users/tarruda/events{/privacy}","received_events_url":"https://api.github.com/users/tarruda/received_events","type":"User","site_admin":false},"body":"Starting some documentation so users read about Neovim from within nvim!","created_at":"2014-09-12T20:23:26Z","updated_at":"2014-09-14T09:31:07Z","closed_at":"2014-09-14T01:08:12Z","merged_at":"2014-09-14T01:08:12Z","merge_commit_sha":"f67d51f965dafde15fd612fc19d28ab072b2065f","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/neovim/neovim/pulls/1163/commits","review_comments_url":"https://api.github.com/repos/neovim/neovim/pulls/1163/comments","review_comment_url":"https://api.github.com/repos/neovim/neovim/pulls/comments/{number}","comments_url":"https://api.github.com/repos/neovim/neovim/issues/1163/comments","statuses_url":"https://api.github.com/repos/neovim/neovim/statuses/84aff1da6ad8607f67156a810028cdfb0ffedc9f","head":{"label":"tarruda:document-nvim-features","ref":"document-nvim-features","sha":"84aff1da6ad8607f67156a810028cdfb0ffedc9f","user":{"login":"tarruda","id":842846,"avatar_url":"https://avatars.githubusercontent.com/u/842846?v=2","gravatar_id":"164e7269035a0a06248ab8336fb82e9f","url":"https://api.github.com/users/tarruda","html_url":"https://github.com/tarruda","followers_url":"https://api.github.com/users/tarruda/followers","following_url":"https://api.github.com/users/tarruda/following{/other_user}","gists_url":"https://api.github.com/users/tarruda/gists{/gist_id}","starred_url":"https://api.github.com/users/tarruda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tarruda/subscriptions","organizations_url":"https://api.github.com/users/tarruda/orgs","repos_url":"https://api.github.com/users/tarruda/repos","events_url":"https://api.github.com/users/tarruda/events{/privacy}","received_events_url":"https://api.github.com/users/tarruda/received_events","type":"User","site_admin":false},"repo":{"id":17170945,"name":"neovim","full_name":"tarruda/neovim","owner":{"login":"tarruda","id":842846,"avatar_url":"https://avatars.githubusercontent.com/u/842846?v=2","gravatar_id":"164e7269035a0a06248ab8336fb82e9f","url":"https://api.github.com/users/tarruda","html_url":"https://github.com/tarruda","followers_url":"https://api.github.com/users/tarruda/followers","following_url":"https://api.github.com/users/tarruda/following{/other_user}","gists_url":"https://api.github.com/users/tarruda/gists{/gist_id}","starred_url":"https://api.github.com/users/tarruda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tarruda/subscriptions","organizations_url":"https://api.github.com/users/tarruda/orgs","repos_url":"https://api.github.com/users/tarruda/repos","events_url":"https://api.github.com/users/tarruda/events{/privacy}","received_events_url":"https://api.github.com/users/tarruda/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/tarruda/neovim","description":"vim's rebirth for the 21st century","fork":true,"url":"https://api.github.com/repos/tarruda/neovim","forks_url":"https://api.github.com/repos/tarruda/neovim/forks","keys_url":"https://api.github.com/repos/tarruda/neovim/keys{/key_id}","collaborators_url":"https://api.github.com/repos/tarruda/neovim/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/tarruda/neovim/teams","hooks_url":"https://api.github.com/repos/tarruda/neovim/hooks","issue_events_url":"https://api.github.com/repos/tarruda/neovim/issues/events{/number}","events_url":"https://api.github.com/repos/tarruda/neovim/events","assignees_url":"https://api.github.com/repos/tarruda/neovim/assignees{/user}","branches_url":"https://api.github.com/repos/tarruda/neovim/branches{/branch}","tags_url":"https://api.github.com/repos/tarruda/neovim/tags","blobs_url":"https://api.github.com/repos/tarruda/neovim/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/tarruda/neovim/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/tarruda/neovim/git/refs{/sha}","trees_url":"https://api.github.com/repos/tarruda/neovim/git/trees{/sha}","statuses_url":"https://api.github.com/repos/tarruda/neovim/statuses/{sha}","languages_url":"https://api.github.com/repos/tarruda/neovim/languages","stargazers_url":"https://api.github.com/repos/tarruda/neovim/stargazers","contributors_url":"https://api.github.com/repos/tarruda/neovim/contributors","subscribers_url":"https://api.github.com/repos/tarruda/neovim/subscribers","subscription_url":"https://api.github.com/repos/tarruda/neovim/subscription","commits_url":"https://api.github.com/repos/tarruda/neovim/commits{/sha}","git_commits_url":"https://api.github.com/repos/tarruda/neovim/git/commits{/sha}","comments_url":"https://api.github.com/repos/tarruda/neovim/comments{/number}","issue_comment_url":"https://api.github.com/repos/tarruda/neovim/issues/comments/{number}","contents_url":"https://api.github.com/repos/tarruda/neovim/contents/{+path}","compare_url":"https://api.github.com/repos/tarruda/neovim/compare/{base}...{head}","merges_url":"https://api.github.com/repos/tarruda/neovim/merges","archive_url":"https://api.github.com/repos/tarruda/neovim/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/tarruda/neovim/downloads","issues_url":"https://api.github.com/repos/tarruda/neovim/issues{/number}","pulls_url":"https://api.github.com/repos/tarruda/neovim/pulls{/number}","milestones_url":"https://api.github.com/repos/tarruda/neovim/milestones{/number}","notifications_url":"https://api.github.com/repos/tarruda/neovim/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/tarruda/neovim/labels{/name}","releases_url":"https://api.github.com/repos/tarruda/neovim/releases{/id}","created_at":"2014-02-25T11:35:55Z","updated_at":"2014-09-10T02:11:33Z","pushed_at":"2014-09-14T00:54:02Z","git_url":"git://github.com/tarruda/neovim.git","ssh_url":"git@github.com:tarruda/neovim.git","clone_url":"https://github.com/tarruda/neovim.git","svn_url":"https://github.com/tarruda/neovim","homepage":"http://neovim.org/","size":32466,"stargazers_count":0,"watchers_count":0,"language":"C","has_issues":false,"has_downloads":true,"has_wiki":true,"forks_count":2,"mirror_url":null,"open_issues_count":0,"forks":2,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"neovim:master","ref":"master","sha":"5778c25c019f01c3e0249da18398abdca3f9b002","user":{"login":"neovim","id":6471485,"avatar_url":"https://avatars.githubusercontent.com/u/6471485?v=2","gravatar_id":"294926ca6818f582b716e868d6c6f985","url":"https://api.github.com/users/neovim","html_url":"https://github.com/neovim","followers_url":"https://api.github.com/users/neovim/followers","following_url":"https://api.github.com/users/neovim/following{/other_user}","gists_url":"https://api.github.com/users/neovim/gists{/gist_id}","starred_url":"https://api.github.com/users/neovim/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/neovim/subscriptions","organizations_url":"https://api.github.com/users/neovim/orgs","repos_url":"https://api.github.com/users/neovim/repos","events_url":"https://api.github.com/users/neovim/events{/privacy}","received_events_url":"https://api.github.com/users/neovim/received_events","type":"Organization","site_admin":false},"repo":{"id":16408992,"name":"neovim","full_name":"neovim/neovim","owner":{"login":"neovim","id":6471485,"avatar_url":"https://avatars.githubusercontent.com/u/6471485?v=2","gravatar_id":"294926ca6818f582b716e868d6c6f985","url":"https://api.github.com/users/neovim","html_url":"https://github.com/neovim","followers_url":"https://api.github.com/users/neovim/followers","following_url":"https://api.github.com/users/neovim/following{/other_user}","gists_url":"https://api.github.com/users/neovim/gists{/gist_id}","starred_url":"https://api.github.com/users/neovim/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/neovim/subscriptions","organizations_url":"https://api.github.com/users/neovim/orgs","repos_url":"https://api.github.com/users/neovim/repos","events_url":"https://api.github.com/users/neovim/events{/privacy}","received_events_url":"https://api.github.com/users/neovim/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/neovim/neovim","description":"vim for the 21st century","fork":false,"url":"https://api.github.com/repos/neovim/neovim","forks_url":"https://api.github.com/repos/neovim/neovim/forks","keys_url":"https://api.github.com/repos/neovim/neovim/keys{/key_id}","collaborators_url":"https://api.github.com/repos/neovim/neovim/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/neovim/neovim/teams","hooks_url":"https://api.github.com/repos/neovim/neovim/hooks","issue_events_url":"https://api.github.com/repos/neovim/neovim/issues/events{/number}","events_url":"https://api.github.com/repos/neovim/neovim/events","assignees_url":"https://api.github.com/repos/neovim/neovim/assignees{/user}","branches_url":"https://api.github.com/repos/neovim/neovim/branches{/branch}","tags_url":"https://api.github.com/repos/neovim/neovim/tags","blobs_url":"https://api.github.com/repos/neovim/neovim/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/neovim/neovim/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/neovim/neovim/git/refs{/sha}","trees_url":"https://api.github.com/repos/neovim/neovim/git/trees{/sha}","statuses_url":"https://api.github.com/repos/neovim/neovim/statuses/{sha}","languages_url":"https://api.github.com/repos/neovim/neovim/languages","stargazers_url":"https://api.github.com/repos/neovim/neovim/stargazers","contributors_url":"https://api.github.com/repos/neovim/neovim/contributors","subscribers_url":"https://api.github.com/repos/neovim/neovim/subscribers","subscription_url":"https://api.github.com/repos/neovim/neovim/subscription","commits_url":"https://api.github.com/repos/neovim/neovim/commits{/sha}","git_commits_url":"https://api.github.com/repos/neovim/neovim/git/commits{/sha}","comments_url":"https://api.github.com/repos/neovim/neovim/comments{/number}","issue_comment_url":"https://api.github.com/repos/neovim/neovim/issues/comments/{number}","contents_url":"https://api.github.com/repos/neovim/neovim/contents/{+path}","compare_url":"https://api.github.com/repos/neovim/neovim/compare/{base}...{head}","merges_url":"https://api.github.com/repos/neovim/neovim/merges","archive_url":"https://api.github.com/repos/neovim/neovim/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/neovim/neovim/downloads","issues_url":"https://api.github.com/repos/neovim/neovim/issues{/number}","pulls_url":"https://api.github.com/repos/neovim/neovim/pulls{/number}","milestones_url":"https://api.github.com/repos/neovim/neovim/milestones{/number}","notifications_url":"https://api.github.com/repos/neovim/neovim/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/neovim/neovim/labels{/name}","releases_url":"https://api.github.com/repos/neovim/neovim/releases{/id}","created_at":"2014-01-31T13:39:22Z","updated_at":"2014-09-14T08:22:57Z","pushed_at":"2014-09-14T05:01:47Z","git_url":"git://github.com/neovim/neovim.git","ssh_url":"git@github.com:neovim/neovim.git","clone_url":"https://github.com/neovim/neovim.git","svn_url":"https://github.com/neovim/neovim","homepage":"http://neovim.org/","size":56827,"stargazers_count":9768,"watchers_count":9768,"language":"VimL","has_issues":true,"has_downloads":true,"has_wiki":true,"forks_count":636,"mirror_url":null,"open_issues_count":194,"forks":636,"open_issues":194,"watchers":9768,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/neovim/neovim/pulls/1163"},"html":{"href":"https://github.com/neovim/neovim/pull/1163"},"issue":{"href":"https://api.github.com/repos/neovim/neovim/issues/1163"},"comments":{"href":"https://api.github.com/repos/neovim/neovim/issues/1163/comments"},"review_comments":{"href":"https://api.github.com/repos/neovim/neovim/pulls/1163/comments"},"review_comment":{"href":"https://api.github.com/repos/neovim/neovim/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/neovim/neovim/pulls/1163/commits"},"statuses":{"href":"https://api.github.com/repos/neovim/neovim/statuses/84aff1da6ad8607f67156a810028cdfb0ffedc9f"}}}}