From 880957ad4e3fc0ff681025f5e29c5eccf797c564 Mon Sep 17 00:00:00 2001 From: ZyX Date: Sat, 10 May 2014 00:53:36 +0400 Subject: Move documentation from function declarations to definitions Uses a perl script to move it (scripts/movedocs.pl) --- src/nvim/api/buffer.c | 115 ++++++++++++++++++++++++++++++++++++--- src/nvim/api/buffer.h | 99 --------------------------------- src/nvim/api/private/helpers.c | 66 ++++++++++++++++++++-- src/nvim/api/private/helpers.h | 54 ------------------ src/nvim/api/tabpage.c | 27 +++++++++ src/nvim/api/tabpage.h | 29 ---------- src/nvim/api/vim.c | 121 ++++++++++++++++++++++++++++++++++++++--- src/nvim/api/vim.h | 107 ------------------------------------ src/nvim/api/window.c | 77 ++++++++++++++++++++++++++ src/nvim/api/window.h | 77 -------------------------- src/nvim/memory.c | 110 +++++++++++++++++++++++++++++++++++++ src/nvim/memory.h | 110 ------------------------------------- src/nvim/os/channel.c | 25 +++++++++ src/nvim/os/channel.h | 27 +-------- src/nvim/os/env.c | 7 +++ src/nvim/os/fs.c | 76 +++++++++++++++++++++++++- src/nvim/os/input.c | 4 ++ src/nvim/os/input.h | 4 -- src/nvim/os/job.c | 40 ++++++++++++++ src/nvim/os/job.h | 41 -------------- src/nvim/os/mem.c | 4 +- src/nvim/os/os.h | 81 --------------------------- src/nvim/os/rstream.c | 47 ++++++++++++++++ src/nvim/os/rstream.h | 47 ---------------- src/nvim/os/server.c | 14 +++++ src/nvim/os/server.h | 14 ----- src/nvim/os/shell.c | 60 +++++++++++++------- src/nvim/os/shell.h | 18 ------ src/nvim/os/time.c | 17 ++++++ src/nvim/os/time.h | 17 ------ src/nvim/os/uv_helpers.c | 24 ++++++++ src/nvim/os/uv_helpers.h | 24 -------- src/nvim/os/wstream.c | 28 ++++++++++ src/nvim/os/wstream.h | 28 ---------- src/nvim/path.c | 77 ++++++++++++++++++++++---- src/nvim/path.h | 53 ------------------ 36 files changed, 884 insertions(+), 885 deletions(-) (limited to 'src/nvim') 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 diff --git a/src/nvim/memory.c b/src/nvim/memory.c index 238a6791c0..17d4a1ba8c 100644 --- a/src/nvim/memory.c +++ b/src/nvim/memory.c @@ -63,6 +63,14 @@ static void try_to_free_memory() trying_to_free = false; } +/// malloc() wrapper +/// +/// try_malloc() is a malloc() wrapper that tries to free some memory before +/// trying again. +/// +/// @see {try_to_free_memory} +/// @param size +/// @return pointer to allocated space. NULL if out of memory void *try_malloc(size_t size) { void *ret = malloc(size); @@ -80,6 +88,12 @@ void *try_malloc(size_t size) return ret; } +/// try_malloc() wrapper that shows an out-of-memory error message to the user +/// before returning NULL +/// +/// @see {try_malloc} +/// @param size +/// @return pointer to allocated space. NULL if out of memory void *verbose_try_malloc(size_t size) { void *ret = try_malloc(size); @@ -89,6 +103,14 @@ void *verbose_try_malloc(size_t size) return ret; } +/// malloc() wrapper that never returns NULL +/// +/// xmalloc() succeeds or gracefully aborts when out of memory. +/// Before aborting try to free some memory and call malloc again. +/// +/// @see {try_to_free_memory} +/// @param size +/// @return pointer to allocated space. Never NULL void *xmalloc(size_t size) { void *ret = try_malloc(size); @@ -100,6 +122,12 @@ void *xmalloc(size_t size) return ret; } +/// calloc() wrapper +/// +/// @see {xmalloc} +/// @param count +/// @param size +/// @return pointer to allocated space. Never NULL void *xcalloc(size_t count, size_t size) { void *ret = calloc(count, size); @@ -121,6 +149,11 @@ void *xcalloc(size_t count, size_t size) return ret; } +/// realloc() wrapper +/// +/// @see {xmalloc} +/// @param size +/// @return pointer to reallocated space. Never NULL void *xrealloc(void *ptr, size_t size) { void *ret = realloc(ptr, size); @@ -142,6 +175,11 @@ void *xrealloc(void *ptr, size_t size) return ret; } +/// xmalloc() wrapper that allocates size + 1 bytes and zeroes the last byte +/// +/// @see {xmalloc} +/// @param size +/// @return pointer to allocated space. Never NULL void *xmallocz(size_t size) { size_t total_size = size + 1; @@ -158,17 +196,62 @@ void *xmallocz(size_t size) return ret; } +/// Allocates (len + 1) bytes of memory, duplicates `len` bytes of +/// `data` to the allocated memory, zero terminates the allocated memory, +/// and returns a pointer to the allocated memory. If the allocation fails, +/// the program dies. +/// +/// @see {xmalloc} +/// @param data Pointer to the data that will be copied +/// @param len number of bytes that will be copied void *xmemdupz(const void *data, size_t len) { return memcpy(xmallocz(len), data, len); } +/// The xstpcpy() function shall copy the string pointed to by src (including +/// the terminating NUL character) into the array pointed to by dst. +/// +/// The xstpcpy() function shall return a pointer to the terminating NUL +/// character copied into the dst buffer. This is the only difference with +/// strcpy(), which returns dst. +/// +/// WARNING: If copying takes place between objects that overlap, the behavior is +/// undefined. +/// +/// This is the Neovim version of stpcpy(3) as defined in POSIX 2008. We +/// don't require that supported platforms implement POSIX 2008, so we +/// implement our own version. +/// +/// @param dst +/// @param src char *xstpcpy(char *restrict dst, const char *restrict src) { const size_t len = strlen(src); return (char *)memcpy(dst, src, len + 1) + len; } +/// The xstpncpy() function shall copy not more than n bytes (bytes that follow +/// a NUL character are not copied) from the array pointed to by src to the +/// array pointed to by dst. +/// +/// If a NUL character is written to the destination, the xstpncpy() function +/// shall return the address of the first such NUL character. Otherwise, it +/// shall return &dst[maxlen]. +/// +/// WARNING: If copying takes place between objects that overlap, the behavior is +/// undefined. +/// +/// WARNING: xstpncpy will ALWAYS write maxlen bytes. If src is shorter than +/// maxlen, zeroes will be written to the remaining bytes. +/// +/// TODO(aktau): I don't see a good reason to have this last behaviour, and +/// it is potentially wasteful. Could we perhaps deviate from the standard +/// and not zero the rest of the buffer? +/// +/// @param dst +/// @param src +/// @param maxlen char *xstpncpy(char *restrict dst, const char *restrict src, size_t maxlen) { const char *p = memchr(src, '\0', maxlen); @@ -183,6 +266,17 @@ char *xstpncpy(char *restrict dst, const char *restrict src, size_t maxlen) } } +/// xstrlcpy - Copy a %NUL terminated string into a sized buffer +/// +/// Compatible with *BSD strlcpy: the result is always a valid +/// NUL-terminated string that fits in the buffer (unless, +/// of course, the buffer size is zero). It does not pad +/// out the result like strncpy() does. +/// +/// @param dst Where to copy the string to +/// @param src Where to copy the string from +/// @param size Size of destination buffer +/// @return Length of the source string (i.e.: strlen(src)) size_t xstrlcpy(char *restrict dst, const char *restrict src, size_t size) { size_t ret = strlen(src); @@ -196,6 +290,11 @@ size_t xstrlcpy(char *restrict dst, const char *restrict src, size_t size) return ret; } +/// strdup() wrapper +/// +/// @see {xmalloc} +/// @param str 0-terminated string that will be copied +/// @return pointer to a copy of the string char *xstrdup(const char *str) { char *ret = strdup(str); @@ -212,12 +311,23 @@ char *xstrdup(const char *str) return ret; } +/// strndup() wrapper +/// +/// @see {xmalloc} +/// @param str 0-terminated string that will be copied +/// @return pointer to a copy of the string char *xstrndup(const char *str, size_t len) { char *p = memchr(str, '\0', len); return xmemdupz(str, p ? (size_t)(p - str) : len); } +/// Duplicates a chunk of memory using xmalloc +/// +/// @see {xmalloc} +/// @param data pointer to the chunk +/// @param len size of the chunk +/// @return a pointer void *xmemdup(const void *data, size_t len) { return memcpy(xmalloc(len), data, len); diff --git a/src/nvim/memory.h b/src/nvim/memory.h index accf293176..fc3b4ac52b 100644 --- a/src/nvim/memory.h +++ b/src/nvim/memory.h @@ -5,145 +5,35 @@ #include "nvim/types.h" #include "nvim/vim.h" -/// malloc() wrapper -/// -/// try_malloc() is a malloc() wrapper that tries to free some memory before -/// trying again. -/// -/// @see {try_to_free_memory} -/// @param size -/// @return pointer to allocated space. NULL if out of memory void *try_malloc(size_t size) FUNC_ATTR_MALLOC FUNC_ATTR_ALLOC_SIZE(1); -/// try_malloc() wrapper that shows an out-of-memory error message to the user -/// before returning NULL -/// -/// @see {try_malloc} -/// @param size -/// @return pointer to allocated space. NULL if out of memory void *verbose_try_malloc(size_t size) FUNC_ATTR_MALLOC FUNC_ATTR_ALLOC_SIZE(1); -/// malloc() wrapper that never returns NULL -/// -/// xmalloc() succeeds or gracefully aborts when out of memory. -/// Before aborting try to free some memory and call malloc again. -/// -/// @see {try_to_free_memory} -/// @param size -/// @return pointer to allocated space. Never NULL void *xmalloc(size_t size) FUNC_ATTR_MALLOC FUNC_ATTR_ALLOC_SIZE(1) FUNC_ATTR_NONNULL_RET; -/// calloc() wrapper -/// -/// @see {xmalloc} -/// @param count -/// @param size -/// @return pointer to allocated space. Never NULL void *xcalloc(size_t count, size_t size) FUNC_ATTR_MALLOC FUNC_ATTR_ALLOC_SIZE_PROD(1, 2) FUNC_ATTR_NONNULL_RET; -/// realloc() wrapper -/// -/// @see {xmalloc} -/// @param size -/// @return pointer to reallocated space. Never NULL void *xrealloc(void *ptr, size_t size) FUNC_ATTR_WARN_UNUSED_RESULT FUNC_ATTR_ALLOC_SIZE(2) FUNC_ATTR_NONNULL_RET; -/// xmalloc() wrapper that allocates size + 1 bytes and zeroes the last byte -/// -/// @see {xmalloc} -/// @param size -/// @return pointer to allocated space. Never NULL void *xmallocz(size_t size) FUNC_ATTR_MALLOC FUNC_ATTR_NONNULL_RET; -/// Allocates (len + 1) bytes of memory, duplicates `len` bytes of -/// `data` to the allocated memory, zero terminates the allocated memory, -/// and returns a pointer to the allocated memory. If the allocation fails, -/// the program dies. -/// -/// @see {xmalloc} -/// @param data Pointer to the data that will be copied -/// @param len number of bytes that will be copied void *xmemdupz(const void *data, size_t len) FUNC_ATTR_NONNULL_RET; -/// strdup() wrapper -/// -/// @see {xmalloc} -/// @param str 0-terminated string that will be copied -/// @return pointer to a copy of the string char * xstrdup(const char *str) FUNC_ATTR_MALLOC FUNC_ATTR_WARN_UNUSED_RESULT FUNC_ATTR_NONNULL_RET; -/// strndup() wrapper -/// -/// @see {xmalloc} -/// @param str 0-terminated string that will be copied -/// @return pointer to a copy of the string char * xstrndup(const char *str, size_t len) FUNC_ATTR_MALLOC FUNC_ATTR_WARN_UNUSED_RESULT FUNC_ATTR_NONNULL_RET; -/// The xstpcpy() function shall copy the string pointed to by src (including -/// the terminating NUL character) into the array pointed to by dst. -/// -/// The xstpcpy() function shall return a pointer to the terminating NUL -/// character copied into the dst buffer. This is the only difference with -/// strcpy(), which returns dst. -/// -/// WARNING: If copying takes place between objects that overlap, the behavior is -/// undefined. -/// -/// This is the Neovim version of stpcpy(3) as defined in POSIX 2008. We -/// don't require that supported platforms implement POSIX 2008, so we -/// implement our own version. -/// -/// @param dst -/// @param src char *xstpcpy(char *restrict dst, const char *restrict src); -/// The xstpncpy() function shall copy not more than n bytes (bytes that follow -/// a NUL character are not copied) from the array pointed to by src to the -/// array pointed to by dst. -/// -/// If a NUL character is written to the destination, the xstpncpy() function -/// shall return the address of the first such NUL character. Otherwise, it -/// shall return &dst[maxlen]. -/// -/// WARNING: If copying takes place between objects that overlap, the behavior is -/// undefined. -/// -/// WARNING: xstpncpy will ALWAYS write maxlen bytes. If src is shorter than -/// maxlen, zeroes will be written to the remaining bytes. -/// -/// TODO(aktau): I don't see a good reason to have this last behaviour, and -/// it is potentially wasteful. Could we perhaps deviate from the standard -/// and not zero the rest of the buffer? -/// -/// @param dst -/// @param src -/// @param maxlen char *xstpncpy(char *restrict dst, const char *restrict src, size_t maxlen); -/// xstrlcpy - Copy a %NUL terminated string into a sized buffer -/// -/// Compatible with *BSD strlcpy: the result is always a valid -/// NUL-terminated string that fits in the buffer (unless, -/// of course, the buffer size is zero). It does not pad -/// out the result like strncpy() does. -/// -/// @param dst Where to copy the string to -/// @param src Where to copy the string from -/// @param size Size of destination buffer -/// @return Length of the source string (i.e.: strlen(src)) size_t xstrlcpy(char *restrict dst, const char *restrict src, size_t size); -/// Duplicates a chunk of memory using xmalloc -/// -/// @see {xmalloc} -/// @param data pointer to the chunk -/// @param len size of the chunk -/// @return a pointer void *xmemdup(const void *data, size_t len) FUNC_ATTR_MALLOC FUNC_ATTR_WARN_UNUSED_RESULT FUNC_ATTR_NONNULL_RET; diff --git a/src/nvim/os/channel.c b/src/nvim/os/channel.c index 6fd7cdbb7e..5886620990 100644 --- a/src/nvim/os/channel.c +++ b/src/nvim/os/channel.c @@ -49,6 +49,7 @@ static void close_cb(uv_handle_t *handle); static WBuffer *serialize_event(char *type, typval_T *data); static Channel *register_channel(void); +/// Initializes the module void channel_init() { channels = pmap_new(uint64_t)(); @@ -56,6 +57,7 @@ void channel_init() msgpack_sbuffer_init(&msgpack_event_buffer); } +/// Teardown the module void channel_teardown() { if (!channels) { @@ -69,6 +71,10 @@ void channel_teardown() }); } +/// Creates an API channel by starting a job and connecting to its +/// stdin/stdout. stderr is forwarded to the editor error stream. +/// +/// @param argv The argument vector for the process void channel_from_job(char **argv) { Channel *channel = register_channel(); @@ -76,6 +82,10 @@ void channel_from_job(char **argv) channel->data.job_id = job_start(argv, channel, job_out, job_err, NULL); } +/// Creates an API channel f