Mercurial > vim

comparison runtime/doc/channel.txt @ 28473:1c112473a54f v8.2.4761

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.2.4761: documentation for using LSP messages is incomplete Commit: https://github.com/vim/vim/commit/e0805b849ce60f65149903b63584d49bf81f975e Author: Yegappan Lakshmanan <yegappan@yahoo.com> Date: Sat Apr 16 15:18:23 2022 +0100 patch 8.2.4761: documentation for using LSP messages is incomplete Problem: Documentation for using LSP messages is incomplete. Solution: Update the documentation. (Yegappan Lakshmanan, closes https://github.com/vim/vim/issues/10206)
author Bram Moolenaar <Bram@vim.org>
date Sat, 16 Apr 2022 16:30:03 +0200
parents 3beb14b12bbd
children d7ca583e5772
comparison
equal deleted inserted replaced
28472:953925226605 28473:1c112473a54f
528 entry. It can have a "timeout" entry to specify the timeout 528 entry. It can have a "timeout" entry to specify the timeout
529 for this specific request. 529 for this specific request.
530 530
531 ch_evalexpr() waits for a response and returns the decoded 531 ch_evalexpr() waits for a response and returns the decoded
532 expression. When there is an error or timeout it returns an 532 expression. When there is an error or timeout it returns an
533 empty string. 533 empty |String| or, when using the "lsp" channel mode, returns an
534 empty |Dict|.
534 535
535 Note that while waiting for the response, Vim handles other 536 Note that while waiting for the response, Vim handles other
536 messages. You need to make sure this doesn't cause trouble. 537 messages. You need to make sure this doesn't cause trouble.
537 538
538 Can also be used as a |method|: > 539 Can also be used as a |method|: >
700 701
701 If the channel mode is "lsp", then returns a Dict. Otherwise 702 If the channel mode is "lsp", then returns a Dict. Otherwise
702 returns an empty String. If the "callback" item is present in 703 returns an empty String. If the "callback" item is present in
703 {options}, then the returned Dict contains the ID of the 704 {options}, then the returned Dict contains the ID of the
704 request message. The ID can be used to send a cancellation 705 request message. The ID can be used to send a cancellation
705 request to the LSP server (if needed). 706 request to the LSP server (if needed). Returns an empty Dict
707 on error.
706 708
707 If a response message is not expected for {expr}, then don't 709 If a response message is not expected for {expr}, then don't
708 specify the "callback" item in {options}. 710 specify the "callback" item in {options}.
709 711
710 Can also be used as a |method|: > 712 Can also be used as a |method|: >
1403 Each LSP protocol message starts with a simple HTTP header followed by the 1405 Each LSP protocol message starts with a simple HTTP header followed by the
1404 payload encoded in JSON-RPC format. This is described in: 1406 payload encoded in JSON-RPC format. This is described in:
1405 1407
1406 https://www.jsonrpc.org/specification 1408 https://www.jsonrpc.org/specification
1407 1409
1408 For messages received on a channel with mode set to "lsp", Vim will process 1410 To encode and send a LSP request/notification message in a Vim |Dict| into a
1409 the HTTP header and decode the payload into a Vim |Dict| type and call the 1411 LSP JSON-RPC message and to receive and decode a LSP JSON-RPC
1410 channel callback or the specified callback function. When sending messages on 1412 response/notification message into a Vim |Dict|, connect to the LSP server
1411 a channel using |ch_evalexpr()| or |ch_sendexpr()|, Vim will add the HTTP 1413 with the |channel-mode| set to "lsp".
1412 header and encode the Vim expression into JSON-RPC. 1414
1415 For messages received on a channel with |channel-mode| set to "lsp", Vim will
1416 process the HTTP header and decode the JSON-RPC payload into a Vim |Dict| type
1417 and call the |channel-callback| function or the specified
1418 |channel-onetime-callback| function. When sending messages on a channel using
1419 the |ch_evalexpr()| or |ch_sendexpr()| functions, Vim will add the HTTP header
1420 and encode the Vim expression into JSON. Refer to |json_encode()| and
1421 |json_decode()| for more information about how Vim encodes and decodes the
1422 builtin types into JSON.
1413 1423
1414 To open a channel using the 'lsp' mode, set the 'mode' item in the |ch_open()| 1424 To open a channel using the 'lsp' mode, set the 'mode' item in the |ch_open()|
1415 {options} argument to 'lsp'. Example: > 1425 {options} argument to 'lsp'. Example: >
1416 1426
1417 let ch = ch_open(..., #{mode: 'lsp'}) 1427 let ch = ch_open(..., #{mode: 'lsp'})
1418 1428
1419 To open a channel using the 'lsp' mode with a job, set the 'in_mode' and 1429 To open a channel using the 'lsp' mode with a job, set the 'in_mode' and
1420 'out_mode' items in the |job_start()| {options} argument to 'lsp'. Example: > 1430 'out_mode' items in the |job_start()| {options} argument to 'lsp'. Example: >
1421 1431
1422 let job = job_start(...., #{in_mode: 'lsp', out_mode: 'lsp'}) 1432 let cmd = ['clangd', '--background-index', '--clang-tidy']
1433 let opts = {}
1434 let opts.in_mode = 'lsp'
1435 let opts.out_mode = 'lsp'
1436 let opts.out_cb = function('LspOutCallback')
1437 let opts.err_cb = function('LspErrCallback')
1438 let opts.exit_cb = function('LspExitCallback')
1439 let job = job_start(cmd, opts)
1423 1440
1424 To synchronously send a JSON-RPC request to the server, use the 1441 To synchronously send a JSON-RPC request to the server, use the
1425 |ch_evalexpr()| function. This function will wait and return the decoded 1442 |ch_evalexpr()| function. This function will wait and return the decoded
1426 response message from the server. You can use either the |channel-timeout| or 1443 response message from the server. You can use either the |channel-timeout| or
1427 the 'timeout' field in the {options} argument to control the response wait 1444 the 'timeout' field in the {options} argument to control the response wait
1428 time. If the request times out, then an empty string is returned. Example: > 1445 time. If the request times out, then an empty |Dict| is returned. Example: >
1429 1446
1430 let req = {} 1447 let req = {}
1431 let req.method = 'textDocument/definition' 1448 let req.method = 'textDocument/definition'
1432 let req.params = {} 1449 let req.params = {}
1433 let req.params.textDocument = #{uri: 'a.c'} 1450 let req.params.textDocument = #{uri: 'a.c'}
1434 let req.params.position = #{line: 10, character: 3} 1451 let req.params.position = #{line: 10, character: 3}
1435 let resp = ch_evalexpr(ch, req, #{timeout: 100}) 1452 let defs = ch_evalexpr(ch, req, #{timeout: 100})
1453 if defs->empty()
1454 ... <handle failure>
1455 endif
1436 1456
1437 Note that in the request message the 'id' field should not be specified. If it 1457 Note that in the request message the 'id' field should not be specified. If it
1438 is specified, then Vim will overwrite the value with an internally generated 1458 is specified, then Vim will overwrite the value with an internally generated
1439 identifier. Vim currently supports only a number type for the 'id' field. 1459 identifier. Vim currently supports only a number type for the 'id' field.
1440 The callback function will be invoked for both a successful and a failed RPC 1460 The callback function will be invoked for both a successful and a failed RPC
1441 request. If the "id" field is present in the request message, then Vim will 1461 request.
1442 overwrite it with an internally generated number. This function returns a
1443 Dict with the identifier used for the message. This can be used to send
1444 cancellation request to the LSP server (if needed).
1445 1462
1446 To send a JSON-RPC request to the server and asynchronously process the 1463 To send a JSON-RPC request to the server and asynchronously process the
1447 response, use the |ch_sendexpr()| function and supply a callback function. 1464 response, use the |ch_sendexpr()| function and supply a callback function. If
1448 1465 the "id" field is present in the request message, then Vim will overwrite it
1449 Example: > 1466 with an internally generated number. This function returns a Dict with the
1467 identifier used for the message. This can be used to send cancellation
1468 request to the LSP server (if needed). Example: >
1450 1469
1451 let req = {} 1470 let req = {}
1452 let req.method = 'textDocument/hover' 1471 let req.method = 'textDocument/hover'
1453 let req.id = 200 1472 let req.id = 200
1454 let req.params = {} 1473 let req.params = {}
1455 let req.params.textDocument = #{uri: 'a.c'} 1474 let req.params.textDocument = #{uri: 'a.c'}
1456 let req.params.position = #{line: 10, character: 3} 1475 let req.params.position = #{line: 10, character: 3}
1457 let resp = ch_sendexpr(ch, req, #{callback: 'MyFn'}) 1476 let resp = ch_sendexpr(ch, req, #{callback: 'HoverFunc'})
1458 1477
1459 To cancel an outstanding LSP request sent to the server using the 1478 To cancel an outstanding asynchronous LSP request sent to the server using the
1460 |ch_sendexpr()| function, send a cancelation message to the server using the 1479 |ch_sendexpr()| function, send a cancelation message to the server using the
1461 |ch_sendexpr()| function with the ID returned by |ch_sendexpr()|. Example: > 1480 |ch_sendexpr()| function with the ID returned by the |ch_sendexpr()| function
1481 for the request. Example: >
1462 1482
1463 " send a completion request 1483 " send a completion request
1464 let req = {} 1484 let req = {}
1465 let req.method = 'textDocument/completion' 1485 let req.method = 'textDocument/completion'
1466 let req.params = {} 1486 let req.params = {}
1467 let req.params.textDocument = #{uri: 'a.c'} 1487 let req.params.textDocument = #{uri: 'a.c'}
1468 let req.params.position = #{line: 10, character: 3} 1488 let req.params.position = #{line: 10, character: 3}
1469 let reqstatus = ch_sendexpr(ch, req, #{callback: 'MyComplete'}) 1489 let reqstatus = ch_sendexpr(ch, req, #{callback: 'LspComplete'})
1470 " send a cancellation notification 1490 " send a cancellation notification
1471 let notif = {} 1491 let notif = {}
1472 let notif.method = '$/cancelRequest' 1492 let notif.method = '$/cancelRequest'
1473 let notif.id = reqstatus.id 1493 let notif.id = reqstatus.id
1474 call ch_sendexpr(ch, notif) 1494 call ch_sendexpr(ch, notif)