Suggestion: provide a stable callback-based lua API

[alfaix]

Hey, thank you for all the work on this plugin. It really makes interacting with CMake much easier and I use it a lot :)

That said, I think the plugin can be improved by providing a stable API.

Describe the problem or limitation you are having The plugin's API is difficult to use by another plugin.

Describe the solution you'd like

1. Declare which part of the lua API is considered stable
2. Follow the traditional fn(is_ok, result_or_error) callback signature in all lua API

Describe alternatives you've considered Working with the API as-is. It's quite difficult, and here's an example: I'm working on this plugin, and as part of it I need to list all executables in the CMake project. To do that, I need to generate the CMake files first. Thus, I would have to call cmake.generate(), and then cmake.get_targets. However, there are 2 problems:

1. cmake.generate only calls the callback if the call is successful. This means that I cannot schedule another operation after it: once I do cmake.generate(), I have no way of knowing when it is done. I can pass the callback, but if the call fails, I'll never know. One option is to do timeouts, but then if CMake fails quickly (say, due to invalid CMakeLists file), the user would have to wait until the timeout (which can be very long for complex CMakeLists) before the interface would react.
2. I can't know if the API will change in the future without notice, as the only documented API is vim commands.

Additional context If the proposed changes make sense to you (change callback signature, ensure callback is always called), I can take a crack at it in a PR.

[alfaix]

Hey @Civitasv I was wondering if you would accept a PR with such changes (make all callbacks adhere to the same format, make sure they are always called even in case of command failure)?

[Civitasv]

We actually have some getters in init.lua, which I think is stable, but I don't document them very well yet. See

https://github.com/Civitasv/cmake-tools.nvim/blob/5893fef535912baa4b3bae4dde550211a90e699d/lua/cmake-tools/init.lua#L1020-L1108

Hey @Civitasv I was wondering if you would accept a PR with such changes (make all callbacks adhere to the same format, make sure they are always called even in case of command failure)?

I think this indeed is helpful. And I'm happy to accept this.

Edit:

These are all getters: https://github.com/Civitasv/cmake-tools.nvim/blob/master/docs/howto.md#mimic-ui-of-cmake-tools-toolbar-in-visual-studio-code