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

cmake-tools.nvim/lua/cmake-tools/init.lua

Lines 1020 to 1108 in 5893fef

	--[[ Getters ]]
	function cmake.get_config()
	return config
	end
	function cmake.get_build_target()
	return config.build_target
	end
	function cmake.get_launch_target()
	return config.launch_target
	end
	function cmake.get_model_info()
	return config:get_code_model_info()
	end
	function cmake.get_launch_args()
	if cmake.get_launch_target() == nil then
	return {}
	end
	if
	config.target_settings[cmake.get_launch_target()]
	and config.target_settings[cmake.get_launch_target()].args
	then
	return config.target_settings[cmake.get_launch_target()].args
	end
	return {}
	end
	function cmake.get_build_environment()
	return environment.get_build_environment_table(config)
	end
	function cmake.get_run_environment(target)
	return environment.get_run_environment_table(
	config,
	target and target or cmake.get_launch_target()
	)
	end
	function cmake.get_build_type()
	return config.build_type
	end
	function cmake.get_kit()
	return config.kit
	end
	function cmake.get_configure_preset()
	return config.configure_preset
	end
	function cmake.get_build_preset()
	return config.build_preset
	end
	function cmake.get_build_directory()
	return config.build_directory
	end
	function cmake.is_cmake_project()
	local result = utils.get_cmake_configuration(config.cwd)
	return result.code == Types.SUCCESS
	end
	function cmake.has_cmake_preset()
	local presets_file = presets.check(config.cwd)
	return presets_file ~= nil
	end
	function cmake.get_build_targets()
	return config:build_targets()
	end
	function cmake.get_launch_targets()
	return config:launch_targets()
	end
	function cmake.get_generate_options()
	return config:generate_options()
	end
	function cmake.get_build_options()
	return config:build_options()
	end
	--[[ end ]]

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