To: vim_dev@googlegroups.com Subject: Patch 8.2.4761 Fcc: outbox From: Bram Moolenaar Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ------------ Patch 8.2.4761 Problem: Documentation for using LSP messages is incomplete. Solution: Update the documentation. (Yegappan Lakshmanan, closes #10206) Files: runtime/doc/channel.txt *** ../vim-8.2.4760/runtime/doc/channel.txt 2022-04-16 10:40:59.081370588 +0100 --- runtime/doc/channel.txt 2022-04-16 15:17:22.640641013 +0100 *************** *** 530,536 **** ch_evalexpr() waits for a response and returns the decoded expression. When there is an error or timeout it returns an ! empty string. Note that while waiting for the response, Vim handles other messages. You need to make sure this doesn't cause trouble. --- 530,537 ---- ch_evalexpr() waits for a response and returns the decoded expression. When there is an error or timeout it returns an ! empty |String| or, when using the "lsp" channel mode, returns an ! empty |Dict|. Note that while waiting for the response, Vim handles other messages. You need to make sure this doesn't cause trouble. *************** *** 702,708 **** returns an empty String. If the "callback" item is present in {options}, then the returned Dict contains the ID of the request message. The ID can be used to send a cancellation ! request to the LSP server (if needed). If a response message is not expected for {expr}, then don't specify the "callback" item in {options}. --- 703,710 ---- returns an empty String. If the "callback" item is present in {options}, then the returned Dict contains the ID of the request message. The ID can be used to send a cancellation ! request to the LSP server (if needed). Returns an empty Dict ! on error. If a response message is not expected for {expr}, then don't specify the "callback" item in {options}. *************** *** 1405,1415 **** https://www.jsonrpc.org/specification ! For messages received on a channel with mode set to "lsp", Vim will process ! the HTTP header and decode the payload into a Vim |Dict| type and call the ! channel callback or the specified callback function. When sending messages on ! a channel using |ch_evalexpr()| or |ch_sendexpr()|, Vim will add the HTTP ! header and encode the Vim expression into JSON-RPC. To open a channel using the 'lsp' mode, set the 'mode' item in the |ch_open()| {options} argument to 'lsp'. Example: > --- 1407,1425 ---- https://www.jsonrpc.org/specification ! To encode and send a LSP request/notification message in a Vim |Dict| into a ! LSP JSON-RPC message and to receive and decode a LSP JSON-RPC ! response/notification message into a Vim |Dict|, connect to the LSP server ! with the |channel-mode| set to "lsp". ! ! For messages received on a channel with |channel-mode| set to "lsp", Vim will ! process the HTTP header and decode the JSON-RPC payload into a Vim |Dict| type ! and call the |channel-callback| function or the specified ! |channel-onetime-callback| function. When sending messages on a channel using ! the |ch_evalexpr()| or |ch_sendexpr()| functions, Vim will add the HTTP header ! and encode the Vim expression into JSON. Refer to |json_encode()| and ! |json_decode()| for more information about how Vim encodes and decodes the ! builtin types into JSON. To open a channel using the 'lsp' mode, set the 'mode' item in the |ch_open()| {options} argument to 'lsp'. Example: > *************** *** 1419,1452 **** To open a channel using the 'lsp' mode with a job, set the 'in_mode' and 'out_mode' items in the |job_start()| {options} argument to 'lsp'. Example: > ! let job = job_start(...., #{in_mode: 'lsp', out_mode: 'lsp'}) To synchronously send a JSON-RPC request to the server, use the |ch_evalexpr()| function. This function will wait and return the decoded response message from the server. You can use either the |channel-timeout| or the 'timeout' field in the {options} argument to control the response wait ! time. If the request times out, then an empty string is returned. Example: > let req = {} let req.method = 'textDocument/definition' let req.params = {} let req.params.textDocument = #{uri: 'a.c'} let req.params.position = #{line: 10, character: 3} ! let resp = ch_evalexpr(ch, req, #{timeout: 100}) Note that in the request message the 'id' field should not be specified. If it is specified, then Vim will overwrite the value with an internally generated identifier. Vim currently supports only a number type for the 'id' field. The callback function will be invoked for both a successful and a failed RPC ! request. If the "id" field is present in the request message, then Vim will ! overwrite it with an internally generated number. This function returns a ! Dict with the identifier used for the message. This can be used to send ! cancellation request to the LSP server (if needed). To send a JSON-RPC request to the server and asynchronously process the ! response, use the |ch_sendexpr()| function and supply a callback function. ! ! Example: > let req = {} let req.method = 'textDocument/hover' --- 1429,1471 ---- To open a channel using the 'lsp' mode with a job, set the 'in_mode' and 'out_mode' items in the |job_start()| {options} argument to 'lsp'. Example: > ! let cmd = ['clangd', '--background-index', '--clang-tidy'] ! let opts = {} ! let opts.in_mode = 'lsp' ! let opts.out_mode = 'lsp' ! let opts.out_cb = function('LspOutCallback') ! let opts.err_cb = function('LspErrCallback') ! let opts.exit_cb = function('LspExitCallback') ! let job = job_start(cmd, opts) To synchronously send a JSON-RPC request to the server, use the |ch_evalexpr()| function. This function will wait and return the decoded response message from the server. You can use either the |channel-timeout| or the 'timeout' field in the {options} argument to control the response wait ! time. If the request times out, then an empty |Dict| is returned. Example: > let req = {} let req.method = 'textDocument/definition' let req.params = {} let req.params.textDocument = #{uri: 'a.c'} let req.params.position = #{line: 10, character: 3} ! let defs = ch_evalexpr(ch, req, #{timeout: 100}) ! if defs->empty() ! ... ! endif Note that in the request message the 'id' field should not be specified. If it is specified, then Vim will overwrite the value with an internally generated identifier. Vim currently supports only a number type for the 'id' field. The callback function will be invoked for both a successful and a failed RPC ! request. To send a JSON-RPC request to the server and asynchronously process the ! response, use the |ch_sendexpr()| function and supply a callback function. If ! the "id" field is present in the request message, then Vim will overwrite it ! with an internally generated number. This function returns a Dict with the ! identifier used for the message. This can be used to send cancellation ! request to the LSP server (if needed). Example: > let req = {} let req.method = 'textDocument/hover' *************** *** 1454,1464 **** let req.params = {} let req.params.textDocument = #{uri: 'a.c'} let req.params.position = #{line: 10, character: 3} ! let resp = ch_sendexpr(ch, req, #{callback: 'MyFn'}) ! To cancel an outstanding LSP request sent to the server using the |ch_sendexpr()| function, send a cancelation message to the server using the ! |ch_sendexpr()| function with the ID returned by |ch_sendexpr()|. Example: > " send a completion request let req = {} --- 1473,1484 ---- let req.params = {} let req.params.textDocument = #{uri: 'a.c'} let req.params.position = #{line: 10, character: 3} ! let resp = ch_sendexpr(ch, req, #{callback: 'HoverFunc'}) ! To cancel an outstanding asynchronous LSP request sent to the server using the |ch_sendexpr()| function, send a cancelation message to the server using the ! |ch_sendexpr()| function with the ID returned by the |ch_sendexpr()| function ! for the request. Example: > " send a completion request let req = {} *************** *** 1466,1472 **** let req.params = {} let req.params.textDocument = #{uri: 'a.c'} let req.params.position = #{line: 10, character: 3} ! let reqstatus = ch_sendexpr(ch, req, #{callback: 'MyComplete'}) " send a cancellation notification let notif = {} let notif.method = '$/cancelRequest' --- 1486,1492 ---- let req.params = {} let req.params.textDocument = #{uri: 'a.c'} let req.params.position = #{line: 10, character: 3} ! let reqstatus = ch_sendexpr(ch, req, #{callback: 'LspComplete'}) " send a cancellation notification let notif = {} let notif.method = '$/cancelRequest' *** ../vim-8.2.4760/src/version.c 2022-04-16 12:34:45.485217720 +0100 --- src/version.c 2022-04-16 15:14:28.771884020 +0100 *************** *** 748,749 **** --- 748,751 ---- { /* Add new patch number below this line */ + /**/ + 4761, /**/ -- Contrary to popular belief, it's often your clothing that gets promoted, not you. (Scott Adams - The Dilbert principle) /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// \\\ \\\ sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ /// \\\ help me help AIDS victims -- http://ICCF-Holland.org ///