feat!: Lua API

[xiyaowong]

VimScript functions

No changes.

Lua

API

• Resolve: feature: simplify lua api #1421

The original APIs have all been removed or modified. The new APIs are as follows:

Load module: local vscode = require("vscode-neovim")

1. vscode.action for asynchronous execution of actions.
2. vscode.call for synchronous execution of actions.
3. vscode.on for adding hook functions.
4. vscode.has_config check if a configuration exists
5. vscode.get_config get a configuration value
6. vscode.update_config update a configuration
7. vscode.notify like vim.notify

Usage

Actions

Now, two built-in actions are provided for testing purposes:

1. _ping returns "pong"
2. _wait waits for the specified milliseconds and then returns "ok"

do -- Execute _ping asynchronously and print the result
  vscode.action("_ping", {
    callback = function(err, res)
      if err == nil then
        print(res) -- outputs: pong
      end
    end,
  })
end

-- Execute _ping synchronously and print the result
print(vscode.call("_ping")) -- outputs: pong

-- Wait for 1 second and print the return value 'ok'
print(vscode.call("_wait", { args = { 1000 } })) -- outputs: ok

-- Wait for 2 seconds with a timeout of 1 second
print(vscode.call("_wait", { args = { 2000 } }), 1000)
-- error: Call '_wait' timed out

do -- Comment the three lines below the cursor
  local lnum = vim.fn.line(".")
  vscode.action("editor.action.commentLine", {
    range = { lnum, lnum + 2 },
  })
end

Hooks

• FocusGained/FocusLost works now
  • Resolve: Hook vscode FocusLost/Gained #370
  • Resolve: [feature request] leave insert mode onFocusChange event #434

Currently no available events for user use.

Integration of VSCode Settings

• Resolve: Update user's settings.json from vim #796

--- has_config ---

-- Check if the configuration "hello.world" exists
print(vscode.has_config("hello.world")) -- should output false

-- Check multiple configurations
vim.print(vscode.has_config({ "hello.world", "editor.tabSize" }))

--- get_config ---

-- Get the value of "editor.tabSize"
print(vscode.get_config("editor.tabSize")) -- a number

-- Get multiple configurations
vim.print(vscode.get_config({ "editor.fontFamily", "editor.tabSize" }))

--- update_config ---

-- Update the value of "editor.tabSize"
vscode.update_config("editor.tabSize", 16, "global")

-- Update multiple configurations
vscode.update_config({ "editor.fontFamily", "editor.tabSize" }, { "Fira Code", 14 })

Notifications

You set these as your default notify functions.

vim.notify = vscode.notify

Others

1. Reorganizing Lua functional modules (The idea is to treat each functional module as a mini-plugin)

[theol0403]

Looks great!

[theol0403]

I'm not sure about the hooks functionality. I think it is code we don't need. I had thought the vscode.on() was for subscribing to eventBus, which also is probably not useful.

init can be observed by VimEnter or something similar.

For #434, we should add specific code that calls doau FocusGained etc, and let users use autocommands. We should not reinvent any mechanisms we don't need to.

[xiyaowong]

I'm not sure about the hooks functionality. I think it is code we don't need. I had thought the vscode.on() was for subscribing to eventBus, which also is probably not useful.

init can be observed by VimEnter or something similar.

For #434, we should add specific code that calls doau FocusGained etc, and let users use autocommands. We should not reinvent any mechanisms we don't need to.

I don't think implicit doautocmd is better. Users can do it themselves.

Using on can handle bidirectional synchronization more conveniently, such as editor.options(&ts, &sw)).

This PR is feat, not fix. Not only solve the linked issues.

This mechanism is useful and common. Many nvim plug-ins have some hooks

[theol0403]

I don't think implicit doautocmd is better. Users can do it themselves.

I'm not sure what you mean, currently FocusLost is never triggered. I think the correct solution to #434 is not to provide a custom hook that users can use, but to make FocusLost function as expected so existing nvim code works automatically.

Using on can handle bidirectional synchronization more conveniently, such as editor.options(&ts, &sw)).

Can you explain further? Sure, I agree that hooks are useful, but I think all the hooks implemented so far can be better done using built-in neovim mechanisms that work out of the box with other nvim code.

[xiyaowong]

I don't think implicit doautocmd is better. Users can do it themselves.

I'm not sure what you mean, currently FocusLost is never triggered. I think the correct solution to #434 is not to provide a custom hook that users can use, but to make FocusLost function as expected so existing nvim code works automatically.

May not work as expected. When the window state changes, the internal state of vscode may also change. But I'm not sure, but I think there will be a lot of edge cases.

We can add this to docs:

You can trigger FocusGained/FocusLost on "window_state_changed"

vscode.on("window_state_changed", function(focused)
  vim.cmd.doautocmd(focused and "FocusGained" or "FocusLost")
end)

Using on can handle bidirectional synchronization more conveniently, such as editor.options(&ts, &sw)).

Can you explain further? Sure, I agree that hooks are useful, but I think all the hooks implemented so far can be better done using built-in neovim mechanisms that work out of the box with other nvim code.

For example:

For internal use

• editor_options_changed (bufnr, options: {tabSize, insertSpaces, cursorStyle, lineNumbers}

As a demonstration, I will use it to support #1530.

We can hook more useful vscode events so that users can write plugins for vscode-neovim.

[xiyaowong]

Example that supports modeline, and synchronize all editor options(tab options and number style) xiyaowong/vscode-neovim@feat/vscode-action...xiyaowong:vscode-neovim:tmp/support-modeline

[xiyaowong]

vim.notify = vscode.notify
vim.notify_once = vscode.notify_once

Consider making this the default.

It should be decided by the users themselves.Or provide a configuration item, which is obviously unnecessary.
https://github.com/rcarriga/nvim-notify
https://github.com/folke/noice.nvim

[xiyaowong]

• We should look into triggering FocusGained/Lost by default

Sure

[theol0403]

I am happy with this PR, pending readme documentation and ideally examples.

[xiyaowong]

Ready to merge⚡️

[theol0403]

Thank you for your hard work!

[theol0403]

@xiyaowong looking forward to seeing the settings sync PR