diff options
Diffstat (limited to 'src/nvim/api/vim.c')
| -rw-r--r-- | src/nvim/api/vim.c | 187 |
1 files changed, 96 insertions, 91 deletions
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 9f3a84c88b..afe10ca4b7 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -33,24 +33,26 @@ # include "api/vim.c.generated.h" #endif -/// Executes an ex-mode command str +/// Executes an ex-command. +/// VimL error will be returned and v:errmsg updated. /// -/// @param str The command str -/// @param[out] err Details of an error that may have occurred -void nvim_command(String str, Error *err) +/// @param command Ex-command string +/// @param[out] err Error details (including actual VimL error), if any +void nvim_command(String command, Error *err) { // Run the command try_start(); - do_cmdline_cmd(str.data); + do_cmdline_cmd(command.data); update_screen(VALID); try_end(err); } -/// Passes input keys to Neovim +/// Passes input keys to Nvim. +/// Does not fail on VimL error, but v:errmsg will be updated. /// -/// @param keys to be typed -/// @param mode specifies the mapping options -/// @param escape_csi the string needs escaping for K_SPECIAL/CSI bytes +/// @param keys to be typed +/// @param mode mapping options +/// @param escape_csi If true, escape K_SPECIAL/CSI bytes in `keys` /// @see feedkeys() /// @see vim_strsave_escape_csi void nvim_feedkeys(String keys, String mode, Boolean escape_csi) @@ -102,13 +104,15 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_csi) } } -/// Passes input keys to Neovim. Unlike `nvim_feedkeys`, this will use a -/// lower-level input buffer and the call is not deferred. -/// This is the most reliable way to emulate real user input. +/// Passes keys to Nvim as raw user-input. +/// Does not fail on VimL error, but v:errmsg will be updated. +/// +/// Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call +/// is not deferred. This is the most reliable way to emulate real user input. /// /// @param keys to be typed -/// @return The number of bytes actually written, which can be lower than -/// requested if the buffer becomes full. +/// @return Number of bytes actually written (can be fewer than +/// requested if the buffer becomes full). Integer nvim_input(String keys) FUNC_API_ASYNC { @@ -152,19 +156,19 @@ String nvim_command_output(String str, Error *err) return cstr_to_string((char *)get_vim_var_str(VV_COMMAND_OUTPUT)); } -/// Evaluates the expression str using the Vim internal expression -/// evaluator (see |expression|). -/// Dictionaries and lists are recursively expanded. +/// Evaluates a VimL expression (:help expression). +/// Dictionaries and Lists are recursively expanded. +/// VimL error returns a generic error. v:errmsg is not updated. /// -/// @param str The expression str -/// @param[out] err Details of an error that may have occurred -/// @return The expanded object -Object nvim_eval(String str, Error *err) +/// @param expr VimL expression string +/// @param[out] err Error details, if any +/// @return Evaluation result or expanded object +Object nvim_eval(String expr, Error *err) { Object rv = OBJECT_INIT; // Evaluate the expression try_start(); - typval_T *expr_result = eval_expr((char_u *) str.data, NULL); + typval_T *expr_result = eval_expr((char_u *) expr.data, NULL); if (!expr_result) { api_set_error(err, Exception, _("Failed to evaluate expression")); @@ -180,11 +184,12 @@ Object nvim_eval(String str, Error *err) return rv; } -/// Call the given function with the given arguments stored in an array. +/// Calls a VimL function with the given arguments. +/// VimL error returns a generic error. v:errmsg is not updated. /// -/// @param fname Function to call -/// @param args Functions arguments packed in an Array -/// @param[out] err Details of an error that may have occurred +/// @param fname Function to call +/// @param args Function arguments packed in an Array +/// @param[out] err Error details, if any /// @return Result of the function call Object nvim_call_function(String fname, Array args, Error *err) { @@ -229,12 +234,12 @@ free_vim_args: return rv; } -/// Calculates the number of display cells `str` occupies, tab is counted as -/// one cell. +/// Calculates the number of display cells occupied by `text`. +/// Tab is counted as one cell. /// -/// @param str Some text -/// @param[out] err Details of an error that may have occurred -/// @return The number of cells +/// @param text Some text +/// @param[out] err Error details, if any +/// @return Number of cells Integer nvim_strwidth(String str, Error *err) { if (str.size > INT_MAX) { @@ -245,9 +250,9 @@ Integer nvim_strwidth(String str, Error *err) return (Integer) mb_string2cells((char_u *) str.data); } -/// Gets a list of paths contained in 'runtimepath' +/// Gets the paths contained in 'runtimepath'. /// -/// @return The list of paths +/// @return List of paths ArrayOf(String) nvim_list_runtime_paths(void) { Array rv = ARRAY_DICT_INIT; @@ -285,10 +290,10 @@ ArrayOf(String) nvim_list_runtime_paths(void) return rv; } -/// Changes Vim working directory +/// Changes the global working directory. /// -/// @param dir The new working directory -/// @param[out] err Details of an error that may have occurred +/// @param dir Directory path +/// @param[out] err Error details, if any void nvim_set_current_dir(String dir, Error *err) { if (dir.size >= MAXPATHL) { @@ -315,8 +320,8 @@ void nvim_set_current_dir(String dir, Error *err) /// Gets the current line /// -/// @param[out] err Details of an error that may have occurred -/// @return The current line string +/// @param[out] err Error details, if any +/// @return Current line string String nvim_get_current_line(Error *err) { return buffer_get_line(curbuf->handle, curwin->w_cursor.lnum - 1, err); @@ -324,8 +329,8 @@ String nvim_get_current_line(Error *err) /// Sets the current line /// -/// @param line The line contents -/// @param[out] err Details of an error that may have occurred +/// @param line Line contents +/// @param[out] err Error details, if any void nvim_set_current_line(String line, Error *err) { buffer_set_line(curbuf->handle, curwin->w_cursor.lnum - 1, line, err); @@ -333,7 +338,7 @@ void nvim_set_current_line(String line, Error *err) /// Deletes the current line /// -/// @param[out] err Details of an error that may have occurred +/// @param[out] err Error details, if any void nvim_del_current_line(Error *err) { buffer_del_line(curbuf->handle, curwin->w_cursor.lnum - 1, err); @@ -341,9 +346,9 @@ void nvim_del_current_line(Error *err) /// Gets a global variable /// -/// @param name The variable name -/// @param[out] err Details of an error that may have occurred -/// @return The variable value +/// @param name Variable name +/// @param[out] err Error details, if any +/// @return Variable value Object nvim_get_var(String name, Error *err) { return dict_get_value(&globvardict, name, err); @@ -351,9 +356,9 @@ Object nvim_get_var(String name, Error *err) /// Sets a global variable /// -/// @param name The variable name -/// @param value The variable value -/// @param[out] err Details of an error that may have occurred +/// @param name Variable name +/// @param value Variable value +/// @param[out] err Error details, if any void nvim_set_var(String name, Object value, Error *err) { dict_set_value(&globvardict, name, value, false, false, err); @@ -361,8 +366,8 @@ void nvim_set_var(String name, Object value, Error *err) /// Removes a global variable /// -/// @param name The variable name -/// @param[out] err Details of an error that may have occurred +/// @param name Variable name +/// @param[out] err Error details, if any void nvim_del_var(String name, Error *err) { dict_set_value(&globvardict, name, NIL, true, false, err); @@ -372,10 +377,10 @@ void nvim_del_var(String name, Error *err) /// /// @deprecated /// -/// @param name The variable name -/// @param value The variable value -/// @param[out] err Details of an error that may have occurred -/// @return The old value or nil if there was no previous value. +/// @param name Variable name +/// @param value Variable value +/// @param[out] err Error details, if any +/// @return Old value or nil if there was no previous value. /// /// @warning It may return nil if there was no previous value /// or if previous value was `v:null`. @@ -388,19 +393,19 @@ Object vim_set_var(String name, Object value, Error *err) /// /// @deprecated /// -/// @param name The variable name -/// @param[out] err Details of an error that may have occurred -/// @return The old value +/// @param name Variable name +/// @param[out] err Error details, if any +/// @return Old value Object vim_del_var(String name, Error *err) { return dict_set_value(&globvardict, name, NIL, true, true, err); } -/// Gets a vim variable +/// Gets a v: variable /// -/// @param name The variable name -/// @param[out] err Details of an error that may have occurred -/// @return The variable value +/// @param name Variable name +/// @param[out] err Error details, if any +/// @return Variable value Object nvim_get_vvar(String name, Error *err) { return dict_get_value(&vimvardict, name, err); @@ -408,9 +413,9 @@ Object nvim_get_vvar(String name, Error *err) /// Gets an option value string /// -/// @param name The option name -/// @param[out] err Details of an error that may have occurred -/// @return The option value +/// @param name Option name +/// @param[out] err Error details, if any +/// @return Option value Object nvim_get_option(String name, Error *err) { return get_option_from(NULL, SREQ_GLOBAL, name, err); @@ -418,9 +423,9 @@ Object nvim_get_option(String name, Error *err) /// Sets an option value /// -/// @param name The option name -/// @param value The new option value -/// @param[out] err Details of an error that may have occurred +/// @param name Option name +/// @param value New option value +/// @param[out] err Error details, if any void nvim_set_option(String name, Object value, Error *err) { set_option_to(NULL, SREQ_GLOBAL, name, value, err); @@ -428,7 +433,7 @@ void nvim_set_option(String name, Object value, Error *err) /// Writes a message to vim output buffer /// -/// @param str The message +/// @param str Message void nvim_out_write(String str) { write_msg(str, false); @@ -436,16 +441,17 @@ void nvim_out_write(String str) /// Writes a message to vim error buffer /// -/// @param str The message +/// @param str Message void nvim_err_write(String str) { write_msg(str, true); } -/// Higher level error reporting function that ensures all str contents -/// are written by sending a trailing linefeed to `nvim_err_write` +/// Writes a message to vim error buffer. To ensure all contents are written, +/// a trailing linefeed is appended. /// -/// @param str The message +/// @param str Message +/// @see nvim_err_write() void nvim_err_writeln(String str) { nvim_err_write(str); @@ -454,7 +460,7 @@ void nvim_err_writeln(String str) /// Gets the current list of buffer handles /// -/// @return The number of buffers +/// @return List of buffer handles ArrayOf(Buffer) nvim_list_bufs(void) { Array rv = ARRAY_DICT_INIT; @@ -475,7 +481,7 @@ ArrayOf(Buffer) nvim_list_bufs(void) /// Gets the current buffer /// -/// @reqturn The buffer handle +/// @return Buffer handle Buffer nvim_get_current_buf(void) { return curbuf->handle; @@ -483,8 +489,8 @@ Buffer nvim_get_current_buf(void) /// Sets the current buffer /// -/// @param id The buffer handle -/// @param[out] err Details of an error that may have occurred +/// @param id Buffer handle +/// @param[out] err Error details, if any void nvim_set_current_buf(Buffer buffer, Error *err) { buf_T *buf = find_buffer_by_handle(buffer, err); @@ -505,7 +511,7 @@ void nvim_set_current_buf(Buffer buffer, Error *err) /// Gets the current list of window handles /// -/// @return The number of windows +/// @return List of window handles ArrayOf(Window) nvim_list_wins(void) { Array rv = ARRAY_DICT_INIT; @@ -526,7 +532,7 @@ ArrayOf(Window) nvim_list_wins(void) /// Gets the current window /// -/// @return The window handle +/// @return Window handle Window nvim_get_current_win(void) { return curwin->handle; @@ -534,7 +540,7 @@ Window nvim_get_current_win(void) /// Sets the current window /// -/// @param handle The window handle +/// @param handle Window handle void nvim_set_current_win(Window window, Error *err) { win_T *win = find_window_by_handle(window, err); @@ -555,7 +561,7 @@ void nvim_set_current_win(Window window, Error *err) /// Gets the current list of tabpage handles /// -/// @return The number of tab pages +/// @return List of tabpage handles ArrayOf(Tabpage) nvim_list_tabpages(void) { Array rv = ARRAY_DICT_INIT; @@ -574,18 +580,18 @@ ArrayOf(Tabpage) nvim_list_tabpages(void) return rv; } -/// Gets the current tab page +/// Gets the current tabpage /// -/// @return The tab page handle +/// @return Tabpage handle Tabpage nvim_get_current_tabpage(void) { return curtab->handle; } -/// Sets the current tab page +/// Sets the current tabpage /// -/// @param handle The tab page handle -/// @param[out] err Details of an error that may have occurred +/// @param handle Tabpage handle +/// @param[out] err Error details, if any void nvim_set_current_tabpage(Tabpage tabpage, Error *err) { tabpage_T *tp = find_tab_by_handle(tabpage, err); @@ -606,8 +612,8 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err) /// Subscribes to event broadcasts /// -/// @param channel_id The channel id (passed automatically by the dispatcher) -/// @param event The event type string +/// @param channel_id Channel id (passed automatically by the dispatcher) +/// @param event Event type string void nvim_subscribe(uint64_t channel_id, String event) FUNC_API_NOEVAL { @@ -620,8 +626,8 @@ void nvim_subscribe(uint64_t channel_id, String event) /// Unsubscribes to event broadcasts /// -/// @param channel_id The channel id (passed automatically by the dispatcher) -/// @param event The event type string +/// @param channel_id Channel id (passed automatically by the dispatcher) +/// @param event Event type string void nvim_unsubscribe(uint64_t channel_id, String event) FUNC_API_NOEVAL { @@ -756,9 +762,8 @@ validation_error: /// and flushed after each newline. Incomplete lines are kept for writing /// later. /// -/// @param message The message to write -/// @param to_err true if it should be treated as an error message (use -/// `emsg` instead of `msg` to print each line) +/// @param message Message to write +/// @param to_err true: message is an error (uses `emsg` instead of `msg`) static void write_msg(String message, bool to_err) { static size_t out_pos = 0, err_pos = 0; |