aboutsummaryrefslogtreecommitdiff
path: root/src/nvim/api
diff options
context:
space:
mode:
Diffstat (limited to 'src/nvim/api')
-rw-r--r--src/nvim/api/buffer.c115
-rw-r--r--src/nvim/api/buffer.h99
-rw-r--r--src/nvim/api/private/helpers.c66
-rw-r--r--src/nvim/api/private/helpers.h54
-rw-r--r--src/nvim/api/tabpage.c27
-rw-r--r--src/nvim/api/tabpage.h29
-rw-r--r--src/nvim/api/vim.c121
-rw-r--r--src/nvim/api/vim.h107
-rw-r--r--src/nvim/api/window.c77
-rw-r--r--src/nvim/api/window.h77
10 files changed, 385 insertions, 387 deletions
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 1637374459..7c05ec7d44 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -20,10 +20,6 @@
#include "nvim/window.h"
#include "nvim/undo.h"
-// Find a window that contains "buf" and switch to it.
-// If there is no such window, use the current window and change "curbuf".
-// Caller must initialize save_curbuf to NULL.
-// restore_win_for_buf() MUST be called later!
static void switch_to_win_for_buf(buf_T *buf,
win_T **save_curwinp,
tabpage_T **save_curtabp,
@@ -33,14 +29,15 @@ static void restore_win_for_buf(win_T *save_curwin,
tabpage_T *save_curtab,
buf_T *save_curbuf);
-// Check if deleting lines made the cursor position invalid.
-// Changed the lines from "lo" to "hi" and added "extra" lines (negative if
-// deleted).
static void fix_cursor(linenr_T lo, linenr_T hi, linenr_T extra);
-// Normalizes 0-based indexes to buffer line numbers
static int64_t normalize_index(buf_T *buf, int64_t index);
+/// Gets the buffer line count
+///
+/// @param buffer The buffer handle
+/// @param[out] err Details of an error that may have occurred
+/// @return The line count
Integer buffer_get_length(Buffer buffer, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
@@ -52,6 +49,12 @@ Integer buffer_get_length(Buffer buffer, Error *err)
return buf->b_ml.ml_line_count;
}
+/// Gets a buffer line
+///
+/// @param buffer The buffer handle
+/// @param index The line index
+/// @param[out] err Details of an error that may have occurred
+/// @return The line string
String buffer_get_line(Buffer buffer, Integer index, Error *err)
{
String rv = {.size = 0};
@@ -66,18 +69,38 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
return rv;
}
+/// Sets a buffer line
+///
+/// @param buffer The buffer handle
+/// @param index The line index
+/// @param line The new line.
+/// @param[out] err Details of an error that may have occurred
void buffer_set_line(Buffer buffer, Integer index, String line, Error *err)
{
StringArray array = {.items = &line, .size = 1};
buffer_set_slice(buffer, index, index, true, true, array, err);
}
+/// Deletes a buffer line
+///
+/// @param buffer The buffer handle
+/// @param index The line index
+/// @param[out] err Details of an error that may have occurred
void buffer_del_line(Buffer buffer, Integer index, Error *err)
{
StringArray array = ARRAY_DICT_INIT;
buffer_set_slice(buffer, index, index, true, true, array, err);
}
+/// Retrieves a line range from the buffer
+///
+/// @param buffer The buffer handle
+/// @param start The first line index
+/// @param end The last line index
+/// @param include_start True if the slice includes the `start` parameter
+/// @param include_end True if the slice includes the `end` parameter
+/// @param[out] err Details of an error that may have occurred
+/// @return An array of lines
StringArray buffer_get_slice(Buffer buffer,
Integer start,
Integer end,
@@ -128,6 +151,16 @@ end:
return rv;
}
+/// Replaces a line range on the buffer
+///
+/// @param buffer The buffer handle
+/// @param start The first line index
+/// @param end The last line index
+/// @param include_start True if the slice includes the `start` parameter
+/// @param include_end True if the slice includes the `end` parameter
+/// @param lines An array of lines to use as replacement(A 0-length array
+/// will simply delete the line range)
+/// @param[out] err Details of an error that may have occurred
void buffer_set_slice(Buffer buffer,
Integer start,
Integer end,
@@ -251,6 +284,12 @@ end:
try_end(err);
}
+/// Gets a buffer variable
+///
+/// @param buffer The buffer handle
+/// @param name The variable name
+/// @param[out] err Details of an error that may have occurred
+/// @return The variable value
Object buffer_get_var(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
@@ -262,6 +301,13 @@ Object buffer_get_var(Buffer buffer, String name, Error *err)
return dict_get_value(buf->b_vars, name, err);
}
+/// Sets a buffer variable. Passing 'nil' as value deletes the variable.
+///
+/// @param buffer The buffer handle
+/// @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
Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
@@ -273,6 +319,12 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
return dict_set_value(buf->b_vars, name, value, err);
}
+/// Gets a buffer option value
+///
+/// @param buffer The buffer handle
+/// @param name The option name
+/// @param[out] err Details of an error that may have occurred
+/// @return The option value
Object buffer_get_option(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
@@ -284,6 +336,13 @@ Object buffer_get_option(Buffer buffer, String name, Error *err)
return get_option_from(buf, SREQ_BUF, name, err);
}
+/// Sets a buffer option value. Passing 'nil' as value deletes the option(only
+/// works if there's a global fallback)
+///
+/// @param buffer The buffer handle
+/// @param name The option name
+/// @param value The option value
+/// @param[out] err Details of an error that may have occurred
void buffer_set_option(Buffer buffer, String name, Object value, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
@@ -295,6 +354,11 @@ void buffer_set_option(Buffer buffer, String name, Object value, Error *err)
set_option_to(buf, SREQ_BUF, name, value, err);
}
+/// Gets the buffer number
+///
+/// @param buffer The buffer handle
+/// @param[out] err Details of an error that may have occurred
+/// @return The buffer number
Integer buffer_get_number(Buffer buffer, Error *err)
{
Integer rv = 0;
@@ -307,6 +371,11 @@ Integer buffer_get_number(Buffer buffer, Error *err)
return buf->b_fnum;
}
+/// Gets the full file name for the buffer
+///
+/// @param buffer The buffer handle
+/// @param[out] err Details of an error that may have occurred
+/// @return The buffer name
String buffer_get_name(Buffer buffer, Error *err)
{
String rv = STRING_INIT;
@@ -319,6 +388,11 @@ String buffer_get_name(Buffer buffer, Error *err)
return cstr_to_string((char *)buf->b_ffname);
}
+/// Sets the full file name for a buffer
+///
+/// @param buffer The buffer handle
+/// @param name The buffer name
+/// @param[out] err Details of an error that may have occurred
void buffer_set_name(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
@@ -347,17 +421,34 @@ void buffer_set_name(Buffer buffer, String name, Error *err)
}
}
+/// Checks if a buffer is valid
+///
+/// @param buffer The buffer handle
+/// @return true if the buffer is valid, false otherwise
Boolean buffer_is_valid(Buffer buffer)
{
Error stub = {.set = false};
return find_buffer(buffer, &stub) != NULL;
}
+/// Inserts a sequence of lines to a buffer at a certain index
+///
+/// @param buffer The buffer handle
+/// @param lnum Insert the lines after `lnum`. If negative, it will append
+/// to the end of the buffer.
+/// @param lines An array of lines
+/// @param[out] err Details of an error that may have occurred
void buffer_insert(Buffer buffer, Integer lnum, StringArray lines, Error *err)
{
buffer_set_slice(buffer, lnum, lnum, false, true, lines, err);
}
+/// Return a tuple (row,col) representing the position of the named mark
+///
+/// @param buffer The buffer handle
+/// @param name The mark's name
+/// @param[out] err Details of an error that may have occurred
+/// @return The (row, col) tuple
Position buffer_get_mark(Buffer buffer, String name, Error *err)
{
Position rv = POSITION_INIT;
@@ -395,6 +486,10 @@ Position buffer_get_mark(Buffer buffer, String name, Error *err)
return rv;
}
+// Find a window that contains "buf" and switch to it.
+// If there is no such window, use the current window and change "curbuf".
+// Caller must initialize save_curbuf to NULL.
+// restore_win_for_buf() MUST be called later!
static void switch_to_win_for_buf(buf_T *buf,
win_T **save_curwinp,
tabpage_T **save_curtabp,
@@ -419,6 +514,9 @@ static void restore_win_for_buf(win_T *save_curwin,
}
}
+// Check if deleting lines made the cursor position invalid.
+// Changed the lines from "lo" to "hi" and added "extra" lines (negative if
+// deleted).
static void fix_cursor(linenr_T lo, linenr_T hi, linenr_T extra)
{
if (curwin->w_cursor.lnum >= lo) {
@@ -438,6 +536,7 @@ static void fix_cursor(linenr_T lo, linenr_T hi, linenr_T extra)
invalidate_botline();
}
+// Normalizes 0-based indexes to buffer line numbers
static int64_t normalize_index(buf_T *buf, int64_t index)
{
// Fix if < 0
diff --git a/src/nvim/api/buffer.h b/src/nvim/api/buffer.h
index 52a3b7cdb3..c68ff5561e 100644
--- a/src/nvim/api/buffer.h
+++ b/src/nvim/api/buffer.h
@@ -6,45 +6,14 @@
#include "nvim/api/private/defs.h"
-/// Gets the buffer line count
-///
-/// @param buffer The buffer handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The line count
Integer buffer_get_length(Buffer buffer, Error *err);
-/// Gets a buffer line
-///
-/// @param buffer The buffer handle
-/// @param index The line index
-/// @param[out] err Details of an error that may have occurred
-/// @return The line string
String buffer_get_line(Buffer buffer, Integer index, Error *err);
-/// Sets a buffer line
-///
-/// @param buffer The buffer handle
-/// @param index The line index
-/// @param line The new line.
-/// @param[out] err Details of an error that may have occurred
void buffer_set_line(Buffer buffer, Integer index, String line, Error *err);
-/// Deletes a buffer line
-///
-/// @param buffer The buffer handle
-/// @param index The line index
-/// @param[out] err Details of an error that may have occurred
void buffer_del_line(Buffer buffer, Integer index, Error *err);
-/// Retrieves a line range from the buffer
-///
-/// @param buffer The buffer handle
-/// @param start The first line index
-/// @param end The last line index
-/// @param include_start True if the slice includes the `start` parameter
-/// @param include_end True if the slice includes the `end` parameter
-/// @param[out] err Details of an error that may have occurred
-/// @return An array of lines
StringArray buffer_get_slice(Buffer buffer,
Integer start,
Integer end,
@@ -52,16 +21,6 @@ StringArray buffer_get_slice(Buffer buffer,
Boolean include_end,
Error *err);
-/// Replaces a line range on the buffer
-///
-/// @param buffer The buffer handle
-/// @param start The first line index
-/// @param end The last line index
-/// @param include_start True if the slice includes the `start` parameter
-/// @param include_end True if the slice includes the `end` parameter
-/// @param lines An array of lines to use as replacement(A 0-length array
-/// will simply delete the line range)
-/// @param[out] err Details of an error that may have occurred
void buffer_set_slice(Buffer buffer,
Integer start,
Integer end,
@@ -70,82 +29,24 @@ void buffer_set_slice(Buffer buffer,
StringArray replacement,
Error *err);
-/// Gets a buffer variable
-///
-/// @param buffer The buffer handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
Object buffer_get_var(Buffer buffer, String name, Error *err);
-/// Sets a buffer variable. Passing 'nil' as value deletes the variable.
-///
-/// @param buffer The buffer handle
-/// @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
Object buffer_set_var(Buffer buffer, String name, Object value, Error *err);
-/// Gets a buffer option value
-///
-/// @param buffer The buffer handle
-/// @param name The option name
-/// @param[out] err Details of an error that may have occurred
-/// @return The option value
Object buffer_get_option(Buffer buffer, String name, Error *err);
-/// Sets a buffer option value. Passing 'nil' as value deletes the option(only
-/// works if there's a global fallback)
-///
-/// @param buffer The buffer handle
-/// @param name The option name
-/// @param value The option value
-/// @param[out] err Details of an error that may have occurred
void buffer_set_option(Buffer buffer, String name, Object value, Error *err);
-/// Gets the buffer number
-///
-/// @param buffer The buffer handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The buffer number
Integer buffer_get_number(Buffer buffer, Error *err);
-/// Gets the full file name for the buffer
-///
-/// @param buffer The buffer handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The buffer name
String buffer_get_name(Buffer buffer, Error *err);
-/// Sets the full file name for a buffer
-///
-/// @param buffer The buffer handle
-/// @param name The buffer name
-/// @param[out] err Details of an error that may have occurred
void buffer_set_name(Buffer buffer, String name, Error *err);
-/// Checks if a buffer is valid
-///
-/// @param buffer The buffer handle
-/// @return true if the buffer is valid, false otherwise
Boolean buffer_is_valid(Buffer buffer);
-/// Inserts a sequence of lines to a buffer at a certain index
-///
-/// @param buffer The buffer handle
-/// @param lnum Insert the lines after `lnum`. If negative, it will append
-/// to the end of the buffer.
-/// @param lines An array of lines
-/// @param[out] err Details of an error that may have occurred
void buffer_insert(Buffer buffer, Integer lnum, StringArray lines, Error *err);
-/// Return a tuple (row,col) representing the position of the named mark
-///
-/// @param buffer The buffer handle
-/// @param name The mark's name
-/// @param[out] err Details of an error that may have occurred
-/// @return The (row, col) tuple
Position buffer_get_mark(Buffer buffer, String name, Error *err);
#endif // NVIM_API_BUFFER_H
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index c9bc849af0..2183b77cfa 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -15,12 +15,6 @@
#include "nvim/option.h"
#include "nvim/option_defs.h"
-/// Recursion helper for the `vim_to_object`. This uses a pointer table
-/// to avoid infinite recursion due to cyclic references
-///
-/// @param obj The source object
-/// @param lookup Lookup table containing pointers to all processed objects
-/// @return The converted value
static Object vim_to_object_rec(typval_T *obj, PMap(ptr_t) *lookup);
static bool object_to_vim(Object obj, typval_T *tv, Error *err);
@@ -39,11 +33,17 @@ static void set_option_value_err(char *key,
int opt_flags,
Error *err);
+/// Start block that may cause vimscript exceptions
void try_start()
{
++trylevel;
}
+/// End try block, set the error message if any and return true if an error
+/// occurred.
+///
+/// @param err Pointer to the stack-allocated error object
+/// @return true if an error occurred
bool try_end(Error *err)
{
--trylevel;
@@ -81,6 +81,11 @@ bool try_end(Error *err)
return err->set;
}
+/// Recursively expands a vimscript value in a dict
+///
+/// @param dict The vimscript dict
+/// @param key The key
+/// @param[out] err Details of an error that may have occurred
Object dict_get_value(dict_T *dict, String key, Error *err)
{
Object rv = OBJECT_INIT;
@@ -101,6 +106,14 @@ Object dict_get_value(dict_T *dict, String key, Error *err)
return rv;
}
+/// Set a value in a dict. Objects are recursively expanded into their
+/// vimscript equivalents. Passing 'nil' as value deletes the key.
+///
+/// @param dict The vimscript dict
+/// @param key The key
+/// @param value The new value
+/// @param[out] err Details of an error that may have occurred
+/// @return the old value, if any
Object dict_set_value(dict_T *dict, String key, Object value, Error *err)
{
Object rv = OBJECT_INIT;
@@ -164,6 +177,14 @@ Object dict_set_value(dict_T *dict, String key, Object value, Error *err)
return rv;
}
+/// Gets the value of a global or local(buffer, window) option.
+///
+/// @param from If `type` is `SREQ_WIN` or `SREQ_BUF`, this must be a pointer
+/// to the window or buffer.
+/// @param type One of `SREQ_GLOBAL`, `SREQ_WIN` or `SREQ_BUF`
+/// @param name The option name
+/// @param[out] err Details of an error that may have occurred
+/// @return the option value
Object get_option_from(void *from, int type, String name, Error *err)
{
Object rv = OBJECT_INIT;
@@ -207,6 +228,13 @@ Object get_option_from(void *from, int type, String name, Error *err)
return rv;
}
+/// Sets the value of a global or local(buffer, window) option.
+///
+/// @param to If `type` is `SREQ_WIN` or `SREQ_BUF`, this must be a pointer
+/// to the window or buffer.
+/// @param type One of `SREQ_GLOBAL`, `SREQ_WIN` or `SREQ_BUF`
+/// @param name The option name
+/// @param[out] err Details of an error that may have occurred
void set_option_to(void *to, int type, String name, Object value, Error *err)
{
if (name.size == 0) {
@@ -274,6 +302,11 @@ cleanup:
free(key);
}
+/// Convert a vim object to an `Object` instance, recursively expanding
+/// Arrays/Dictionaries.
+///
+/// @param obj The source object
+/// @return The converted value
Object vim_to_object(typval_T *obj)
{
Object rv;
@@ -285,6 +318,11 @@ Object vim_to_object(typval_T *obj)
return rv;
}
+/// Finds the pointer for a window number
+///
+/// @param window the window number
+/// @param[out] err Details of an error that may have occurred
+/// @return the window pointer
buf_T *find_buffer(Buffer buffer, Error *err)
{
buf_T *rv = handle_get_buffer(buffer);
@@ -296,6 +334,11 @@ buf_T *find_buffer(Buffer buffer, Error *err)
return rv;
}
+/// Finds the pointer for a window number
+///
+/// @param window the window number
+/// @param[out] err Details of an error that may have occurred
+/// @return the window pointer
win_T * find_window(Window window, Error *err)
{
win_T *rv = handle_get_window(window);
@@ -307,6 +350,11 @@ win_T * find_window(Window window, Error *err)
return rv;
}
+/// Finds the pointer for a tabpage number
+///
+/// @param tabpage the tabpage number
+/// @param[out] err Details of an error that may have occurred
+/// @return the tabpage pointer
tabpage_T * find_tab(Tabpage tabpage, Error *err)
{
tabpage_T *rv = handle_get_tabpage(tabpage);
@@ -422,6 +470,12 @@ static bool object_to_vim(Object obj, typval_T *tv, Error *err)
return true;
}
+/// Recursion helper for the `vim_to_object`. This uses a pointer table
+/// to avoid infinite recursion due to cyclic references
+///
+/// @param obj The source object
+/// @param lookup Lookup table containing pointers to all processed objects
+/// @return The converted value
static Object vim_to_object_rec(typval_T *obj, PMap(ptr_t) *lookup)
{
Object rv = OBJECT_INIT;
diff --git a/src/nvim/api/private/helpers.h b/src/nvim/api/private/helpers.h
index 04b128d3f1..b70cc55d42 100644
--- a/src/nvim/api/private/helpers.h
+++ b/src/nvim/api/private/helpers.h
@@ -13,78 +13,24 @@
err->set = true; \
} while (0)
-/// Start block that may cause vimscript exceptions
void try_start(void);
-/// End try block, set the error message if any and return true if an error
-/// occurred.
-///
-/// @param err Pointer to the stack-allocated error object
-/// @return true if an error occurred
bool try_end(Error *err);
-/// Recursively expands a vimscript value in a dict
-///
-/// @param dict The vimscript dict
-/// @param key The key
-/// @param[out] err Details of an error that may have occurred
Object dict_get_value(dict_T *dict, String key, Error *err);
-/// Set a value in a dict. Objects are recursively expanded into their
-/// vimscript equivalents. Passing 'nil' as value deletes the key.
-///
-/// @param dict The vimscript dict
-/// @param key The key
-/// @param value The new value
-/// @param[out] err Details of an error that may have occurred
-/// @return the old value, if any
Object dict_set_value(dict_T *dict, String key, Object value, Error *err);
-/// Gets the value of a global or local(buffer, window) option.
-///
-/// @param from If `type` is `SREQ_WIN` or `SREQ_BUF`, this must be a pointer
-/// to the window or buffer.
-/// @param type One of `SREQ_GLOBAL`, `SREQ_WIN` or `SREQ_BUF`
-/// @param name The option name
-/// @param[out] err Details of an error that may have occurred
-/// @return the option value
Object get_option_from(void *from, int type, String name, Error *err);
-/// Sets the value of a global or local(buffer, window) option.
-///
-/// @param to If `type` is `SREQ_WIN` or `SREQ_BUF`, this must be a pointer
-/// to the window or buffer.
-/// @param type One of `SREQ_GLOBAL`, `SREQ_WIN` or `SREQ_BUF`
-/// @param name The option name
-/// @param[out] err Details of an error that may have occurred
void set_option_to(void *to, int type, String name, Object value, Error *err);
-/// Convert a vim object to an `Object` instance, recursively expanding
-/// Arrays/Dictionaries.
-///
-/// @param obj The source object
-/// @return The converted value
Object vim_to_object(typval_T *obj);
-/// Finds the pointer for a window number
-///
-/// @param window the window number
-/// @param[out] err Details of an error that may have occurred
-/// @return the window pointer
buf_T *find_buffer(Buffer buffer, Error *err);
-/// Finds the pointer for a window number
-///
-/// @param window the window number
-/// @param[out] err Details of an error that may have occurred
-/// @return the window pointer
win_T * find_window(Window window, Error *err);
-/// Finds the pointer for a tabpage number
-///
-/// @param tabpage the tabpage number
-/// @param[out] err Details of an error that may have occurred
-/// @return the tabpage pointer
tabpage_T * find_tab(Tabpage tabpage, Error *err);
/// Copies a C string into a String (binary safe string, characters + length)
diff --git a/src/nvim/api/tabpage.c b/src/nvim/api/tabpage.c
index ce52466d12..8d92b01cf9 100644
--- a/src/nvim/api/tabpage.c
+++ b/src/nvim/api/tabpage.c
@@ -8,6 +8,11 @@
#include "nvim/api/private/helpers.h"
#include "nvim/memory.h"
+/// Gets the number of windows in a tabpage
+///
+/// @param tabpage The tabpage
+/// @param[out] err Details of an error that may have occurred
+/// @return The number of windows in `tabpage`
WindowArray tabpage_get_windows(Tabpage tabpage, Error *err)
{
WindowArray rv = ARRAY_DICT_INIT;
@@ -40,6 +45,12 @@ WindowArray tabpage_get_windows(Tabpage tabpage, Error *err)
return rv;
}
+/// Gets a tabpage variable
+///
+/// @param tabpage The tab page handle
+/// @param name The variable name
+/// @param[out] err Details of an error that may have occurred
+/// @return The variable value
Object tabpage_get_var(Tabpage tabpage, String name, Error *err)
{
tabpage_T *tab = find_tab(tabpage, err);
@@ -51,6 +62,13 @@ Object tabpage_get_var(Tabpage tabpage, String name, Error *err)
return dict_get_value(tab->tp_vars, name, err);
}
+/// Sets a tabpage variable. Passing 'nil' as value deletes the variable.
+///
+/// @param tabpage handle
+/// @param name The variable name
+/// @param value The variable value
+/// @param[out] err Details of an error that may have occurred
+/// @return The tab page handle
Object tabpage_set_var(Tabpage tabpage, String name, Object value, Error *err)
{
tabpage_T *tab = find_tab(tabpage, err);
@@ -62,6 +80,11 @@ Object tabpage_set_var(Tabpage tabpage, String name, Object value, Error *err)
return dict_set_value(tab->tp_vars, name, value, err);
}
+/// Gets the current window in a tab page
+///
+/// @param tabpage The tab page handle
+/// @param[out] err Details of an error that may have occurred
+/// @return The Window handle
Window tabpage_get_window(Tabpage tabpage, Error *err)
{
Window rv = 0;
@@ -87,6 +110,10 @@ Window tabpage_get_window(Tabpage tabpage, Error *err)
}
}
+/// Checks if a tab page is valid
+///
+/// @param tabpage The tab page handle
+/// @return true if the tab page is valid, false otherwise
Boolean tabpage_is_valid(Tabpage tabpage)
{
Error stub = {.set = false};
diff --git a/src/nvim/api/tabpage.h b/src/nvim/api/tabpage.h
index dddcecbdbd..a7c1eac19d 100644
--- a/src/nvim/api/tabpage.h
+++ b/src/nvim/api/tabpage.h
@@ -6,41 +6,12 @@
#include "nvim/api/private/defs.h"
-/// Gets the number of windows in a tabpage
-///
-/// @param tabpage The tabpage
-/// @param[out] err Details of an error that may have occurred
-/// @return The number of windows in `tabpage`
-WindowArray tabpage_get_windows(Tabpage tabpage, Error *err);
-
-/// Gets a tabpage variable
-///
-/// @param tabpage The tab page handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
Object tabpage_get_var(Tabpage tabpage, String name, Error *err);
-/// Sets a tabpage variable. Passing 'nil' as value deletes the variable.
-///
-/// @param tabpage handle
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
-/// @return The tab page handle
Object tabpage_set_var(Tabpage tabpage, String name, Object value, Error *err);
-/// Gets the current window in a tab page
-///
-/// @param tabpage The tab page handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The Window handle
Window tabpage_get_window(Tabpage tabpage, Error *err);
-/// Checks if a tab page is valid
-///
-/// @param tabpage The tab page handle
-/// @return true if the tab page is valid, false otherwise
Boolean tabpage_is_valid(Tabpage tabpage);
#endif // NVIM_API_TABPAGE_H
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 39e2c32d6d..a1aa6b2d79 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -22,20 +22,20 @@
#define LINE_BUFFER_SIZE 4096
-/// Writes a message to vim output or error buffer. The string is split
-/// 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)
static void write_msg(String message, bool to_err);
+/// Send keys to vim input buffer, simulating user input.
+///
+/// @param str The keys to send
void vim_push_keys(String str)
{
abort();
}
+/// Executes an ex-mode command str
+///
+/// @param str The command str
+/// @param[out] err Details of an error that may have occurred
void vim_command(String str, Error *err)
{
// We still use 0-terminated strings, so we must convert.
@@ -48,6 +48,13 @@ void vim_command(String str, Error *err)
try_end(err);
}
+/// Evaluates the expression str using the vim internal expression
+/// evaluator (see |expression|).
+/// Dictionaries and lists are recursively expanded.
+///
+/// @param str The expression str
+/// @param[out] err Details of an error that may have occurred
+/// @return The expanded object
Object vim_eval(String str, Error *err)
{
Object rv;
@@ -67,6 +74,12 @@ Object vim_eval(String str, Error *err)
return rv;
}
+/// Calculates the number of display cells `str` occupies, 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
Integer vim_strwidth(String str, Error *err)
{
if (str.size > INT_MAX) {
@@ -80,6 +93,9 @@ Integer vim_strwidth(String str, Error *err)
return rv;
}
+/// Returns a list of paths contained in 'runtimepath'
+///
+/// @return The list of paths
StringArray vim_list_runtime_paths(void)
{
StringArray rv = ARRAY_DICT_INIT;
@@ -117,6 +133,10 @@ StringArray vim_list_runtime_paths(void)
return rv;
}
+/// Changes vim working directory
+///
+/// @param dir The new working directory
+/// @param[out] err Details of an error that may have occurred
void vim_change_directory(String dir, Error *err)
{
if (dir.size >= MAXPATHL) {
@@ -141,56 +161,102 @@ void vim_change_directory(String dir, Error *err)
try_end(err);
}
+/// Return the current line
+///
+/// @param[out] err Details of an error that may have occurred
+/// @return The current line string
String vim_get_current_line(Error *err)
{
return buffer_get_line(curbuf->handle, curwin->w_cursor.lnum - 1, err);
}
+/// Sets the current line
+///
+/// @param line The line contents
+/// @param[out] err Details of an error that may have occurred
void vim_set_current_line(String line, Error *err)
{
buffer_set_line(curbuf->handle, curwin->w_cursor.lnum - 1, line, err);
}
+/// Delete the current line
+///
+/// @param[out] err Details of an error that may have occurred
void vim_del_current_line(Error *err)
{
buffer_del_line(curbuf->handle, curwin->w_cursor.lnum - 1, 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
Object vim_get_var(String name, Error *err)
{
return dict_get_value(&globvardict, name, err);
}
+/// Sets a global variable. Passing 'nil' as value deletes the variable.
+///
+/// @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 if any
Object vim_set_var(String name, Object value, Error *err)
{
return dict_set_value(&globvardict, name, value, err);
}
+/// Gets a vim variable
+///
+/// @param name The variable name
+/// @param[out] err Details of an error that may have occurred
+/// @return The variable value
Object vim_get_vvar(String name, Error *err)
{
return dict_get_value(&vimvardict, name, err);
}
+/// Get an option value string
+///
+/// @param name The option name
+/// @param[out] err Details of an error that may have occurred
+/// @return The option value
Object vim_get_option(String name, Error *err)
{
return get_option_from(NULL, SREQ_GLOBAL, name, 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
void vim_set_option(String name, Object value, Error *err)
{
set_option_to(NULL, SREQ_GLOBAL, name, value, err);
}
+/// Write a message to vim output buffer
+///
+/// @param str The message
void vim_out_write(String str)
{
write_msg(str, false);
}
+/// Write a message to vim error buffer
+///
+/// @param str The message
void vim_err_write(String str)
{
write_msg(str, true);
}
+/// Gets the current list of buffer handles
+///
+/// @return The number of buffers
BufferArray vim_get_buffers(void)
{
BufferArray rv = ARRAY_DICT_INIT;
@@ -213,11 +279,18 @@ BufferArray vim_get_buffers(void)
return rv;
}
+/// Return the current buffer
+///
+/// @reqturn The buffer handle
Buffer vim_get_current_buffer(void)
{
return curbuf->handle;
}
+/// Sets the current buffer
+///
+/// @param id The buffer handle
+/// @param[out] err Details of an error that may have occurred
void vim_set_current_buffer(Buffer buffer, Error *err)
{
buf_T *buf = find_buffer(buffer, err);
@@ -241,6 +314,9 @@ void vim_set_current_buffer(Buffer buffer, Error *err)
try_end(err);
}
+/// Gets the current list of window handles
+///
+/// @return The number of windows
WindowArray vim_get_windows(void)
{
WindowArray rv = ARRAY_DICT_INIT;
@@ -261,11 +337,17 @@ WindowArray vim_get_windows(void)
return rv;
}
+/// Return the current window
+///
+/// @return The window handle
Window vim_get_current_window(void)
{
return curwin->handle;
}
+/// Sets the current window
+///
+/// @param handle The window handle
void vim_set_current_window(Window window, Error *err)
{
win_T *win = find_window(window, err);
@@ -288,6 +370,9 @@ void vim_set_current_window(Window window, Error *err)
try_end(err);
}
+/// Gets the current list of tabpage handles
+///
+/// @return The number of tab pages
TabpageArray vim_get_tabpages(void)
{
TabpageArray rv = ARRAY_DICT_INIT;
@@ -310,11 +395,18 @@ TabpageArray vim_get_tabpages(void)
return rv;
}
+/// Return the current tab page
+///
+/// @return The tab page handle
Tabpage vim_get_current_tabpage(void)
{
return curtab->handle;
}
+/// Sets the current tab page
+///
+/// @param handle The tab page handle
+/// @param[out] err Details of an error that may have occurred
void vim_set_current_tabpage(Tabpage tabpage, Error *err)
{
tabpage_T *tp = find_tab(tabpage, err);
@@ -328,6 +420,10 @@ void vim_set_current_tabpage(Tabpage tabpage, Error *err)
try_end(err);
}
+/// Subscribes to event broadcasts
+///
+/// @param channel_id The channel id(passed automatically by the dispatcher)
+/// @param event The event type string
void vim_subscribe(uint64_t channel_id, String event)
{
size_t length = (event.size < EVENT_MAXLEN ? event.size : EVENT_MAXLEN);
@@ -337,6 +433,10 @@ void vim_subscribe(uint64_t channel_id, String event)
channel_subscribe(channel_id, e);
}
+/// Unsubscribes to event broadcasts
+///
+/// @param channel_id The channel id(passed automatically by the dispatcher)
+/// @param event The event type string
void vim_unsubscribe(uint64_t channel_id, String event)
{
size_t length = (event.size < EVENT_MAXLEN ? event.size : EVENT_MAXLEN);
@@ -346,6 +446,13 @@ void vim_unsubscribe(uint64_t channel_id, String event)
channel_unsubscribe(channel_id, e);
}
+/// Writes a message to vim output or error buffer. The string is split
+/// 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)
static void write_msg(String message, bool to_err)
{
static int pos = 0;
diff --git a/src/nvim/api/vim.h b/src/nvim/api/vim.h
index 4d1ac9023e..426acf7f50 100644
--- a/src/nvim/api/vim.h
+++ b/src/nvim/api/vim.h
@@ -6,165 +6,58 @@
#include "nvim/api/private/defs.h"
-/// Send keys to vim input buffer, simulating user input.
-///
-/// @param str The keys to send
void vim_push_keys(String str);
-/// Executes an ex-mode command str
-///
-/// @param str The command str
-/// @param[out] err Details of an error that may have occurred
void vim_command(String str, Error *err);
-/// Evaluates the expression str using the vim internal expression
-/// evaluator (see |expression|).
-/// Dictionaries and lists are recursively expanded.
-///
-/// @param str The expression str
-/// @param[out] err Details of an error that may have occurred
-/// @return The expanded object
Object vim_eval(String str, Error *err);
-/// Calculates the number of display cells `str` occupies, 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
Integer vim_strwidth(String str, Error *err);
-/// Returns a list of paths contained in 'runtimepath'
-///
-/// @return The list of paths
StringArray vim_list_runtime_paths(void);
-/// Changes vim working directory
-///
-/// @param dir The new working directory
-/// @param[out] err Details of an error that may have occurred
void vim_change_directory(String dir, Error *err);
-/// Return the current line
-///
-/// @param[out] err Details of an error that may have occurred
-/// @return The current line string
String vim_get_current_line(Error *err);
-/// Delete the current line
-///
-/// @param[out] err Details of an error that may have occurred
void vim_del_current_line(Error *err);
-/// Sets the current line
-///
-/// @param line The line contents
-/// @param[out] err Details of an error that may have occurred
void vim_set_current_line(String 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
Object vim_get_var(String name, Error *err);
-/// Sets a global variable. Passing 'nil' as value deletes the variable.
-///
-/// @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 if any
Object vim_set_var(String name, Object value, Error *err);
-/// Gets a vim variable
-///
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
Object vim_get_vvar(String name, Error *err);
-/// Get an option value string
-///
-/// @param name The option name
-/// @param[out] err Details of an error that may have occurred
-/// @return The option value
Object vim_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
void vim_set_option(String name, Object value, Error *err);
-/// Write a message to vim output buffer
-///
-/// @param str The message
void vim_out_write(String str);
-/// Write a message to vim error buffer
-///
-/// @param str The message
void vim_err_write(String str);
-/// Gets the current list of buffer handles
-///
-/// @return The number of buffers
BufferArray vim_get_buffers(void);
-/// Return the current buffer
-///
-/// @reqturn The buffer handle
Buffer vim_get_current_buffer(void);
-/// Sets the current buffer
-///
-/// @param id The buffer handle
-/// @param[out] err Details of an error that may have occurred
void vim_set_current_buffer(Buffer buffer, Error *err);
-/// Gets the current list of window handles
-///
-/// @return The number of windows
WindowArray vim_get_windows(void);
-/// Return the current window
-///
-/// @return The window handle
Window vim_get_current_window(void);
-/// Sets the current window
-///
-/// @param handle The window handle
void vim_set_current_window(Window window, Error *err);
-/// Gets the current list of tabpage handles
-///
-/// @return The number of tab pages
TabpageArray vim_get_tabpages(void);
-/// Return the current tab page
-///
-/// @return The tab page handle
Tabpage vim_get_current_tabpage(void);
-/// Sets the current tab page
-///
-/// @param handle The tab page handle
-/// @param[out] err Details of an error that may have occurred
void vim_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
void vim_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
void vim_unsubscribe(uint64_t channel_id, String event);
#endif // NVIM_API_VIM_H
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index fd13557e3b..2b81afdb0c 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -12,6 +12,11 @@
#include "nvim/misc2.h"
+/// Gets the current buffer in a window
+///
+/// @param window The window handle
+/// @param[out] err Details of an error that may have occurred
+/// @return The buffer handle
Buffer window_get_buffer(Window window, Error *err)
{
win_T *win = find_window(window, err);
@@ -23,6 +28,11 @@ Buffer window_get_buffer(Window window, Error *err)
return win->w_buffer->handle;
}
+/// Gets the cursor position in the window
+///
+/// @param window The window handle
+/// @param[out] err Details of an error that may have occurred
+/// @return the (row, col) tuple
Position window_get_cursor(Window window, Error *err)
{
Position rv = {.row = 0, .col = 0};
@@ -36,6 +46,11 @@ Position window_get_cursor(Window window, Error *err)
return rv;
}
+/// Sets the cursor position in the window
+///
+/// @param window The window handle
+/// @param pos the (row, col) tuple representing the new position
+/// @param[out] err Details of an error that may have occurred
void window_set_cursor(Window window, Position pos, Error *err)
{
win_T *win = find_window(window, err);
@@ -67,6 +82,11 @@ void window_set_cursor(Window window, Position pos, Error *err)
update_screen(VALID);
}
+/// Gets the window height
+///
+/// @param window The window handle
+/// @param[out] err Details of an error that may have occurred
+/// @return the height in rows
Integer window_get_height(Window window, Error *err)
{
win_T *win = find_window(window, err);
@@ -78,6 +98,12 @@ Integer window_get_height(Window window, Error *err)
return win->w_height;
}
+/// Sets the window height. This will only succeed if the screen is split
+/// horizontally.
+///
+/// @param window The window handle
+/// @param height the new height in rows
+/// @param[out] err Details of an error that may have occurred
void window_set_height(Window window, Integer height, Error *err)
{
win_T *win = find_window(window, err);
@@ -99,6 +125,11 @@ void window_set_height(Window window, Integer height, Error *err)
try_end(err);
}
+/// Gets the window width
+///
+/// @param window The window handle
+/// @param[out] err Details of an error that may have occurred
+/// @return the width in columns
Integer window_get_width(Window window, Error *err)
{
win_T *win = find_window(window, err);
@@ -110,6 +141,12 @@ Integer window_get_width(Window window, Error *err)
return win->w_width;
}
+/// Sets the window width. This will only succeed if the screen is split
+/// vertically.
+///
+/// @param window The window handle
+/// @param width the new width in columns
+/// @param[out] err Details of an error that may have occurred
void window_set_width(Window window, Integer width, Error *err)
{
win_T *win = find_window(window, err);
@@ -131,6 +168,12 @@ void window_set_width(Window window, Integer width, Error *err)
try_end(err);
}
+/// Gets a window variable
+///
+/// @param window The window handle
+/// @param name The variable name
+/// @param[out] err Details of an error that may have occurred
+/// @return The variable value
Object window_get_var(Window window, String name, Error *err)
{
win_T *win = find_window(window, err);
@@ -142,6 +185,13 @@ Object window_get_var(Window window, String name, Error *err)
return dict_get_value(win->w_vars, name, err);
}
+/// Sets a window variable. Passing 'nil' as value deletes the variable.
+///
+/// @param window The window handle
+/// @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
Object window_set_var(Window window, String name, Object value, Error *err)
{
win_T *win = find_window(window, err);
@@ -153,6 +203,12 @@ Object window_set_var(Window window, String name, Object value, Error *err)
return dict_set_value(win->w_vars, name, value, err);
}
+/// Gets a window option value
+///
+/// @param window The window handle
+/// @param name The option name
+/// @param[out] err Details of an error that may have occurred
+/// @return The option value
Object window_get_option(Window window, String name, Error *err)
{
win_T *win = find_window(window, err);
@@ -164,6 +220,13 @@ Object window_get_option(Window window, String name, Error *err)
return get_option_from(win, SREQ_WIN, name, err);
}
+/// Sets a window option value. Passing 'nil' as value deletes the option(only
+/// works if there's a global fallback)
+///
+/// @param window The window handle
+/// @param name The option name
+/// @param value The option value
+/// @param[out] err Details of an error that may have occurred
void window_set_option(Window window, String name, Object value, Error *err)
{
win_T *win = find_window(window, err);
@@ -175,6 +238,11 @@ void window_set_option(Window window, String name, Object value, Error *err)
set_option_to(win, SREQ_WIN, name, value, err);
}
+/// Gets the window position in display cells. First position is zero.
+///
+/// @param window The window handle
+/// @param[out] err Details of an error that may have occurred
+/// @return The (row, col) tuple with the window position
Position window_get_position(Window window, Error *err)
{
Position rv;
@@ -188,6 +256,11 @@ Position window_get_position(Window window, Error *err)
return rv;
}
+/// Gets the window tab page
+///
+/// @param window The window handle
+/// @param[out] err Details of an error that may have occurred
+/// @return The tab page that contains the window
Tabpage window_get_tabpage(Window window, Error *err)
{
Tabpage rv = 0;
@@ -200,6 +273,10 @@ Tabpage window_get_tabpage(Window window, Error *err)
return rv;
}
+/// Checks if a window is valid
+///
+/// @param window The window handle
+/// @return true if the window is valid, false otherwise
Boolean window_is_valid(Window window)
{
Error stub = {.set = false};
diff --git a/src/nvim/api/window.h b/src/nvim/api/window.h
index 4c036ff5d7..694558fca8 100644
--- a/src/nvim/api/window.h
+++ b/src/nvim/api/window.h
@@ -6,109 +6,32 @@
#include "nvim/api/private/defs.h"
-/// Gets the current buffer in a window
-///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The buffer handle
Buffer window_get_buffer(Window window, Error *err);
-/// Gets the cursor position in the window
-///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return the (row, col) tuple
Position window_get_cursor(Window window, Error *err);
-/// Sets the cursor position in the window
-///
-/// @param window The window handle
-/// @param pos the (row, col) tuple representing the new position
-/// @param[out] err Details of an error that may have occurred
void window_set_cursor(Window window, Position pos, Error *err);
-/// Gets the window height
-///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return the height in rows
Integer window_get_height(Window window, Error *err);
-/// Sets the window height. This will only succeed if the screen is split
-/// horizontally.
-///
-/// @param window The window handle
-/// @param height the new height in rows
-/// @param[out] err Details of an error that may have occurred
void window_set_height(Window window, Integer height, Error *err);
-/// Gets the window width
-///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return the width in columns
Integer window_get_width(Window window, Error *err);
-/// Sets the window width. This will only succeed if the screen is split
-/// vertically.
-///
-/// @param window The window handle
-/// @param width the new width in columns
-/// @param[out] err Details of an error that may have occurred
void window_set_width(Window window, Integer width, Error *err);
-/// Gets a window variable
-///
-/// @param window The window handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
Object window_get_var(Window window, String name, Error *err);
-/// Sets a window variable. Passing 'nil' as value deletes the variable.
-///
-/// @param window The window handle
-/// @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
Object window_set_var(Window window, String name, Object value, Error *err);
-/// Gets a window option value
-///
-/// @param window The window handle
-/// @param name The option name
-/// @param[out] err Details of an error that may have occurred
-/// @return The option value
Object window_get_option(Window window, String name, Error *err);
-/// Sets a window option value. Passing 'nil' as value deletes the option(only
-/// works if there's a global fallback)
-///
-/// @param window The window handle
-/// @param name The option name
-/// @param value The option value
-/// @param[out] err Details of an error that may have occurred
void window_set_option(Window window, String name, Object value, Error *err);
-/// Gets the window position in display cells. First position is zero.
-///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The (row, col) tuple with the window position
Position window_get_position(Window window, Error *err);
-/// Gets the window tab page
-///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The tab page that contains the window
Tabpage window_get_tabpage(Window window, Error *err);
-/// Checks if a window is valid
-///
-/// @param window The window handle
-/// @return true if the window is valid, false otherwise
Boolean window_is_valid(Window window);
#endif // NVIM_API_WINDOW_H