mirror of
https://github.com/neovim/neovim.git
synced 2025-09-07 11:58:17 +00:00
automation: Generate API documentation (#5798)
runtime: Add underscore to {} helpSpecial syntax pattern
docs: Added generated api-funcs.txt
This commit is contained in:
Tommy Allen
committed by
Justin M. Keyes
Justin M. Keyes
parent
efe1476d42
commit
fd9cc8b0b2
716
runtime/doc/api-funcs.txt
Normal file
716
runtime/doc/api-funcs.txt
Normal file
@@ -0,0 +1,716 @@
|
||||
*api-funcs.txt* Neovim API Function Reference {Nvim}
|
||||
|
||||
Note: This documentation is generated from Neovim's API source code.
|
||||
|
||||
Contents:
|
||||
|
||||
1. Global Functions |api-global|
|
||||
2. Buffer Functions |api-buffer|
|
||||
3. Window Functions |api-window|
|
||||
4. Tabpage Functions |api-tabpage|
|
||||
5. UI Functions |api-ui|
|
||||
|
||||
==============================================================================
|
||||
1. Global Functions *api-global*
|
||||
|
||||
nvim_command({command}) *nvim_command()*
|
||||
Executes an ex-command. On VimL error: Returns the VimL error;
|
||||
v:errmsg is not updated.
|
||||
|
||||
Parameters:~
|
||||
{command} Ex-command string
|
||||
|
||||
nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()*
|
||||
Passes input keys to Nvim. On VimL error: Does not fail, but
|
||||
updates v:errmsg.
|
||||
|
||||
Parameters:~
|
||||
{keys} to be typed
|
||||
{mode} mapping options
|
||||
{escape_csi} If true, escape K_SPECIAL/CSI bytes in
|
||||
`keys`
|
||||
|
||||
nvim_input({keys}) *nvim_input()*
|
||||
Passes keys to Nvim as raw user-input. On VimL error: Does not
|
||||
fail, but updates v:errmsg.
|
||||
|
||||
Unlike `nvim_feedkeys`, this uses a lower-level input buffer
|
||||
and the call is not deferred. This is the most reliable way to
|
||||
emulate real user input.
|
||||
|
||||
Parameters:~
|
||||
{keys} to be typed
|
||||
|
||||
Return:~
|
||||
Number of bytes actually written (can be fewer than
|
||||
requested if the buffer becomes full).
|
||||
|
||||
*nvim_replace_termcodes()*
|
||||
nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
|
||||
Replaces any terminal codes with the internal representation
|
||||
|
||||
nvim_command_output({str}) *nvim_command_output()*
|
||||
TODO: Documentation
|
||||
|
||||
nvim_eval({expr}) *nvim_eval()*
|
||||
Evaluates a VimL expression (:help expression). Dictionaries
|
||||
and Lists are recursively expanded. On VimL error: Returns a
|
||||
generic error; v:errmsg is not updated.
|
||||
|
||||
Parameters:~
|
||||
{expr} VimL expression string
|
||||
|
||||
Return:~
|
||||
Evaluation result or expanded object
|
||||
|
||||
nvim_call_function({fname}, {args}) *nvim_call_function()*
|
||||
Calls a VimL function with the given arguments. On VimL error:
|
||||
Returns a generic error; v:errmsg is not updated.
|
||||
|
||||
Parameters:~
|
||||
{fname} Function to call
|
||||
{args} Function arguments packed in an Array
|
||||
|
||||
Return:~
|
||||
Result of the function call
|
||||
|
||||
nvim_strwidth({str}) *nvim_strwidth()*
|
||||
Calculates the number of display cells occupied by `text`.
|
||||
<Tab> counts as one cell.
|
||||
|
||||
Parameters:~
|
||||
{text} Some text
|
||||
|
||||
Return:~
|
||||
Number of cells
|
||||
|
||||
nvim_list_runtime_paths() *nvim_list_runtime_paths()*
|
||||
Gets the paths contained in 'runtimepath'.
|
||||
|
||||
Return:~
|
||||
List of paths
|
||||
|
||||
nvim_set_current_dir({dir}) *nvim_set_current_dir()*
|
||||
Changes the global working directory.
|
||||
|
||||
Parameters:~
|
||||
{dir} Directory path
|
||||
|
||||
nvim_get_current_line() *nvim_get_current_line()*
|
||||
Gets the current line
|
||||
|
||||
Parameters:~
|
||||
|
||||
Return:~
|
||||
Current line string
|
||||
|
||||
nvim_set_current_line({line}) *nvim_set_current_line()*
|
||||
Sets the current line
|
||||
|
||||
Parameters:~
|
||||
{line} Line contents
|
||||
|
||||
nvim_del_current_line() *nvim_del_current_line()*
|
||||
Deletes the current line
|
||||
|
||||
Parameters:~
|
||||
|
||||
nvim_get_var({name}) *nvim_get_var()*
|
||||
Gets a global (g:) variable
|
||||
|
||||
Parameters:~
|
||||
{name} Variable name
|
||||
|
||||
Return:~
|
||||
Variable value
|
||||
|
||||
nvim_set_var({name}, {value}) *nvim_set_var()*
|
||||
Sets a global (g:) variable
|
||||
|
||||
Parameters:~
|
||||
{name} Variable name
|
||||
{value} Variable value
|
||||
|
||||
nvim_del_var({name}) *nvim_del_var()*
|
||||
Removes a global (g:) variable
|
||||
|
||||
Parameters:~
|
||||
{name} Variable name
|
||||
|
||||
nvim_get_vvar({name}) *nvim_get_vvar()*
|
||||
Gets a v: variable
|
||||
|
||||
Parameters:~
|
||||
{name} Variable name
|
||||
|
||||
Return:~
|
||||
Variable value
|
||||
|
||||
nvim_get_option({name}) *nvim_get_option()*
|
||||
Gets an option value string
|
||||
|
||||
Parameters:~
|
||||
{name} Option name
|
||||
|
||||
Return:~
|
||||
Option value
|
||||
|
||||
nvim_set_option({name}, {value}) *nvim_set_option()*
|
||||
Sets an option value
|
||||
|
||||
Parameters:~
|
||||
{name} Option name
|
||||
{value} New option value
|
||||
|
||||
nvim_out_write({str}) *nvim_out_write()*
|
||||
Writes a message to vim output buffer
|
||||
|
||||
Parameters:~
|
||||
{str} Message
|
||||
|
||||
nvim_err_write({str}) *nvim_err_write()*
|
||||
Writes a message to vim error buffer
|
||||
|
||||
Parameters:~
|
||||
{str} Message
|
||||
|
||||
nvim_err_writeln({str}) *nvim_err_writeln()*
|
||||
Writes a message to vim error buffer. Appends a linefeed to
|
||||
ensure all contents are written.
|
||||
|
||||
Parameters:~
|
||||
{str} Message
|
||||
|
||||
nvim_list_bufs() *nvim_list_bufs()*
|
||||
Gets the current list of buffer handles
|
||||
|
||||
Return:~
|
||||
List of buffer handles
|
||||
|
||||
nvim_get_current_buf() *nvim_get_current_buf()*
|
||||
Gets the current buffer
|
||||
|
||||
Return:~
|
||||
Buffer handle
|
||||
|
||||
nvim_set_current_buf({buffer}) *nvim_set_current_buf()*
|
||||
Sets the current buffer
|
||||
|
||||
Parameters:~
|
||||
{id} Buffer handle
|
||||
|
||||
nvim_list_wins() *nvim_list_wins()*
|
||||
Gets the current list of window handles
|
||||
|
||||
Return:~
|
||||
List of window handles
|
||||
|
||||
nvim_get_current_win() *nvim_get_current_win()*
|
||||
Gets the current window
|
||||
|
||||
Return:~
|
||||
Window handle
|
||||
|
||||
nvim_set_current_win({window}) *nvim_set_current_win()*
|
||||
Sets the current window
|
||||
|
||||
Parameters:~
|
||||
{handle} Window handle
|
||||
|
||||
nvim_list_tabpages() *nvim_list_tabpages()*
|
||||
Gets the current list of tabpage handles
|
||||
|
||||
Return:~
|
||||
List of tabpage handles
|
||||
|
||||
nvim_get_current_tabpage() *nvim_get_current_tabpage()*
|
||||
Gets the current tabpage
|
||||
|
||||
Return:~
|
||||
Tabpage handle
|
||||
|
||||
nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
|
||||
Sets the current tabpage
|
||||
|
||||
Parameters:~
|
||||
{handle} Tabpage handle
|
||||
|
||||
nvim_subscribe({event}) *nvim_subscribe()*
|
||||
Subscribes to event broadcasts
|
||||
|
||||
Parameters:~
|
||||
{event} Event type string
|
||||
|
||||
nvim_unsubscribe({event}) *nvim_unsubscribe()*
|
||||
Unsubscribes to event broadcasts
|
||||
|
||||
Parameters:~
|
||||
{event} Event type string
|
||||
|
||||
nvim_get_color_by_name({name}) *nvim_get_color_by_name()*
|
||||
TODO: Documentation
|
||||
|
||||
nvim_get_color_map() *nvim_get_color_map()*
|
||||
TODO: Documentation
|
||||
|
||||
nvim_get_api_info() *nvim_get_api_info()*
|
||||
TODO: Documentation
|
||||
|
||||
nvim_call_atomic({calls}) *nvim_call_atomic()*
|
||||
Call many api methods atomically
|
||||
|
||||
This has two main usages: Firstly, to perform several requests
|
||||
from an async context atomically, i.e. without processing
|
||||
requests from other rpc clients or redrawing or allowing user
|
||||
interaction in between. Note that api methods that could fire
|
||||
autocommands or do event processing still might do so. For
|
||||
instance invoking the :sleep command might call timer
|
||||
callbacks. Secondly, it can be used to reduce rpc overhead
|
||||
(roundtrips) when doing many requests in sequence.
|
||||
|
||||
Parameters:~
|
||||
{calls} an array of calls, where each call is described
|
||||
by an array with two elements: the request name,
|
||||
and an array of arguments.
|
||||
|
||||
Return:~
|
||||
an array with two elements. The first is an array of
|
||||
return values. The second is NIL if all calls succeeded.
|
||||
If a call resulted in an error, it is a three-element
|
||||
array with the zero-based index of the call which resulted
|
||||
in an error, the error type and the error message. If an
|
||||
error ocurred, the values from all preceding calls will
|
||||
still be returned.
|
||||
|
||||
|
||||
==============================================================================
|
||||
2. Buffer Functions *api-buffer*
|
||||
|
||||
nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
|
||||
Gets the buffer line count
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
|
||||
Return:~
|
||||
Line count
|
||||
|
||||
*nvim_buf_get_lines()*
|
||||
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
|
||||
Retrieves a line range from the buffer
|
||||
|
||||
Indexing is zero-based, end-exclusive. Negative indices are
|
||||
interpreted as length+1+index, i e -1 refers to the index past
|
||||
the end. So to get the last element set start=-2 and end=-1.
|
||||
|
||||
Out-of-bounds indices are clamped to the nearest valid value,
|
||||
unless `strict_indexing` is set.
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{start} First line index
|
||||
{end} Last line index (exclusive)
|
||||
{strict_indexing} Whether out-of-bounds should be an
|
||||
error.
|
||||
|
||||
Return:~
|
||||
Array of lines
|
||||
|
||||
*nvim_buf_set_lines()*
|
||||
nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing},
|
||||
{replacement})
|
||||
Replaces line range on the buffer
|
||||
|
||||
Indexing is zero-based, end-exclusive. Negative indices are
|
||||
interpreted as length+1+index, i e -1 refers to the index past
|
||||
the end. So to change or delete the last element set start=-2
|
||||
and end=-1.
|
||||
|
||||
To insert lines at a given index, set both start and end to
|
||||
the same index. To delete a range of lines, set replacement to
|
||||
an empty array.
|
||||
|
||||
Out-of-bounds indices are clamped to the nearest valid value,
|
||||
unless `strict_indexing` is set.
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{start} First line index
|
||||
{end} Last line index (exclusive)
|
||||
{strict_indexing} Whether out-of-bounds should be an
|
||||
error.
|
||||
{replacement} Array of lines to use as replacement
|
||||
|
||||
nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()*
|
||||
Gets a buffer-scoped (b:) variable.
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{name} Variable name
|
||||
|
||||
Return:~
|
||||
Variable value
|
||||
|
||||
nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
|
||||
Sets a buffer-scoped (b:) variable
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{name} Variable name
|
||||
{value} Variable value
|
||||
|
||||
nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()*
|
||||
Removes a buffer-scoped (b:) variable
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{name} Variable name
|
||||
|
||||
nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()*
|
||||
Gets a buffer option value
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{name} Option name
|
||||
|
||||
Return:~
|
||||
Option value
|
||||
|
||||
nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()*
|
||||
Sets a buffer option value. Passing 'nil' as value deletes the
|
||||
option (only works if there's a global fallback)
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{name} Option name
|
||||
{value} Option value
|
||||
|
||||
nvim_buf_get_number({buffer}) *nvim_buf_get_number()*
|
||||
Gets the buffer number
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
|
||||
Return:~
|
||||
Buffer number
|
||||
|
||||
nvim_buf_get_name({buffer}) *nvim_buf_get_name()*
|
||||
Gets the full file name for the buffer
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
|
||||
Return:~
|
||||
Buffer name
|
||||
|
||||
nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()*
|
||||
Sets the full file name for a buffer
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{name} Buffer name
|
||||
|
||||
nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()*
|
||||
Checks if a buffer is valid
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
|
||||
Return:~
|
||||
true if the buffer is valid, false otherwise
|
||||
|
||||
nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
|
||||
Return a tuple (row,col) representing the position of the
|
||||
named mark
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{name} Mark name
|
||||
|
||||
Return:~
|
||||
(row, col) tuple
|
||||
|
||||
*nvim_buf_add_highlight()*
|
||||
nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
|
||||
{col_start}, {col_end})
|
||||
Adds a highlight to buffer.
|
||||
|
||||
This can be used for plugins which dynamically generate
|
||||
highlights to a buffer (like a semantic highlighter or
|
||||
linter). The function adds a single highlight to a buffer.
|
||||
Unlike matchaddpos() highlights follow changes to line
|
||||
numbering (as lines are inserted/removed above the highlighted
|
||||
line), like signs and marks do.
|
||||
|
||||
"src_id" is useful for batch deletion/updating of a set of
|
||||
highlights. When called with src_id = 0, an unique source id
|
||||
is generated and returned. Succesive calls can pass in it as
|
||||
"src_id" to add new highlights to the same source group. All
|
||||
highlights in the same group can then be cleared with
|
||||
nvim_buf_clear_highlight. If the highlight never will be
|
||||
manually deleted pass in -1 for "src_id".
|
||||
|
||||
If "hl_group" is the empty string no highlight is added, but a
|
||||
new src_id is still returned. This is useful for an external
|
||||
plugin to synchrounously request an unique src_id at
|
||||
initialization, and later asynchronously add and clear
|
||||
highlights in response to buffer changes.
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{src_id} Source group to use or 0 to use a new group,
|
||||
or -1 for ungrouped highlight
|
||||
{hl_group} Name of the highlight group to use
|
||||
{line} Line to highlight
|
||||
{col_start} Start of range of columns to highlight
|
||||
{col_end} End of range of columns to highlight, or -1
|
||||
to highlight to end of line
|
||||
|
||||
Return:~
|
||||
The src_id that was used
|
||||
|
||||
*nvim_buf_clear_highlight()*
|
||||
nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
|
||||
Clears highlights from a given source group and a range of
|
||||
lines
|
||||
|
||||
To clear a source group in the entire buffer, pass in 1 and -1
|
||||
to line_start and line_end respectively.
|
||||
|
||||
Parameters:~
|
||||
{buffer} Buffer handle
|
||||
{src_id} Highlight source group to clear, or -1 to
|
||||
clear all.
|
||||
{line_start} Start of range of lines to clear
|
||||
{line_end} End of range of lines to clear (exclusive)
|
||||
or -1 to clear to end of file.
|
||||
|
||||
|
||||
==============================================================================
|
||||
3. Window Functions *api-window*
|
||||
|
||||
nvim_win_get_buf({window}) *nvim_win_get_buf()*
|
||||
Gets the current buffer in a window
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
|
||||
Return:~
|
||||
Buffer handle
|
||||
|
||||
nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
|
||||
Gets the cursor position in the window
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
|
||||
Return:~
|
||||
(row, col) tuple
|
||||
|
||||
nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
|
||||
Sets the cursor position in the window
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
{pos} (row, col) tuple representing the new position
|
||||
|
||||
nvim_win_get_height({window}) *nvim_win_get_height()*
|
||||
Gets the window height
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
|
||||
Return:~
|
||||
Height as a count of rows
|
||||
|
||||
nvim_win_set_height({window}, {height}) *nvim_win_set_height()*
|
||||
Sets the window height. This will only succeed if the screen
|
||||
is split horizontally.
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
{height} Height as a count of rows
|
||||
|
||||
nvim_win_get_width({window}) *nvim_win_get_width()*
|
||||
Gets the window width
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
|
||||
Return:~
|
||||
Width as a count of columns
|
||||
|
||||
nvim_win_set_width({window}, {width}) *nvim_win_set_width()*
|
||||
Sets the window width. This will only succeed if the screen is
|
||||
split vertically.
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
{width} Width as a count of columns
|
||||
|
||||
nvim_win_get_var({window}, {name}) *nvim_win_get_var()*
|
||||
Gets a window-scoped (w:) variable
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
{name} Variable name
|
||||
|
||||
Return:~
|
||||
Variable value
|
||||
|
||||
nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()*
|
||||
Sets a window-scoped (w:) variable
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
{name} Variable name
|
||||
{value} Variable value
|
||||
|
||||
nvim_win_del_var({window}, {name}) *nvim_win_del_var()*
|
||||
Removes a window-scoped (w:) variable
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
{name} Variable name
|
||||
|
||||
nvim_win_get_option({window}, {name}) *nvim_win_get_option()*
|
||||
Gets a window option value
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
{name} Option name
|
||||
|
||||
Return:~
|
||||
Option value
|
||||
|
||||
nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()*
|
||||
Sets a window option value. Passing 'nil' as value deletes the
|
||||
option(only works if there's a global fallback)
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
{name} Option name
|
||||
{value} Option value
|
||||
|
||||
nvim_win_get_position({window}) *nvim_win_get_position()*
|
||||
Gets the window position in display cells. First position is
|
||||
zero.
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
|
||||
Return:~
|
||||
(row, col) tuple with the window position
|
||||
|
||||
nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()*
|
||||
Gets the window tabpage
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
|
||||
Return:~
|
||||
Tabpage that contains the window
|
||||
|
||||
nvim_win_get_number({window}) *nvim_win_get_number()*
|
||||
Gets the window number
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
|
||||
Return:~
|
||||
Window number
|
||||
|
||||
nvim_win_is_valid({window}) *nvim_win_is_valid()*
|
||||
Checks if a window is valid
|
||||
|
||||
Parameters:~
|
||||
{window} Window handle
|
||||
|
||||
Return:~
|
||||
true if the window is valid, false otherwise
|
||||
|
||||
|
||||
==============================================================================
|
||||
4. Tabpage Functions *api-tabpage*
|
||||
|
||||
nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()*
|
||||
Gets the windows in a tabpage
|
||||
|
||||
Parameters:~
|
||||
{tabpage} Tabpage
|
||||
|
||||
Return:~
|
||||
List of windows in tabpage
|
||||
|
||||
nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()*
|
||||
Gets a tab-scoped (t:) variable
|
||||
|
||||
Parameters:~
|
||||
{tabpage} Tabpage handle
|
||||
{name} Variable name
|
||||
|
||||
Return:~
|
||||
Variable value
|
||||
|
||||
nvim_tabpage_set_var({tabpage}, {name}, {value}) *nvim_tabpage_set_var()*
|
||||
Sets a tab-scoped (t:) variable
|
||||
|
||||
Parameters:~
|
||||
{tabpage} Tabpage handle
|
||||
{name} Variable name
|
||||
{value} Variable value
|
||||
|
||||
nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()*
|
||||
Removes a tab-scoped (t:) variable
|
||||
|
||||
Parameters:~
|
||||
{tabpage} Tabpage handle
|
||||
{name} Variable name
|
||||
|
||||
nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()*
|
||||
Gets the current window in a tabpage
|
||||
|
||||
Parameters:~
|
||||
{tabpage} Tabpage handle
|
||||
|
||||
Return:~
|
||||
Window handle
|
||||
|
||||
nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()*
|
||||
Gets the tabpage number
|
||||
|
||||
Parameters:~
|
||||
{tabpage} Tabpage handle
|
||||
|
||||
Return:~
|
||||
Tabpage number
|
||||
|
||||
nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()*
|
||||
Checks if a tabpage is valid
|
||||
|
||||
Parameters:~
|
||||
{tabpage} Tabpage handle
|
||||
|
||||
Return:~
|
||||
true if the tabpage is valid, false otherwise
|
||||
|
||||
|
||||
==============================================================================
|
||||
5. UI Functions *api-ui*
|
||||
|
||||
remote_ui_disconnect() *remote_ui_disconnect()*
|
||||
TODO: Documentation
|
||||
|
||||
nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()*
|
||||
TODO: Documentation
|
||||
|
||||
nvim_ui_detach() *nvim_ui_detach()*
|
||||
TODO: Documentation
|
||||
|
||||
nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
|
||||
TODO: Documentation
|
||||
|
||||
nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()*
|
||||
TODO: Documentation
|
||||
|
||||
vim:tw=78:ts=8:ft=help:norl:
|
||||
@@ -59,7 +59,7 @@ syn match helpSpecial "\[N]"
|
||||
syn match helpSpecial "N N"he=s+1
|
||||
syn match helpSpecial "Nth"me=e-2
|
||||
syn match helpSpecial "N-1"me=e-2
|
||||
syn match helpSpecial "{[-a-zA-Z0-9'"*+/:%#=[\]<>.,]\+}"
|
||||
syn match helpSpecial "{[-_a-zA-Z0-9'"*+/:%#=[\]<>.,]\+}"
|
||||
syn match helpSpecial "\s\[[-a-z^A-Z0-9_]\{2,}]"ms=s+1
|
||||
syn match helpSpecial "<[-a-zA-Z0-9_]\+>"
|
||||
syn match helpSpecial "<[SCM]-.>"
|
||||
|
||||
514
scripts/gen_api_vimdoc.py
Normal file
514
scripts/gen_api_vimdoc.py
Normal file
@@ -0,0 +1,514 @@
|
||||
#!/usr/bin/env python
|
||||
"""Parses Doxygen XML output to generate Neovim's API documentation.
|
||||
|
||||
This would be easier using lxml and XSLT, but:
|
||||
|
||||
1. This should avoid needing Python dependencies, especially ones that are
|
||||
C modules that have library dependencies (lxml requires libxml and
|
||||
libxslt).
|
||||
2. I wouldn't know how to deal with nested indentation in <para> tags using
|
||||
XSLT.
|
||||
|
||||
Each function documentation is formatted with the following rules:
|
||||
|
||||
- Maximum width of 78 characters (`text_width`).
|
||||
- Spaces for indentation.
|
||||
- Function signature and helptag are on the same line.
|
||||
- Helptag is right aligned.
|
||||
- Signature and helptag must have a minimum of 8 spaces between them.
|
||||
- If the signature is too long, it is placed on the line after the
|
||||
helptag. The signature wraps at `text_width - 8` characters with
|
||||
subsequent lines indented to the open parenthesis.
|
||||
- Documentation body will be indented by 16 spaces.
|
||||
- Subsection bodies are indented an additional 4 spaces.
|
||||
- Documentation body consists of the function description, parameter details,
|
||||
return description, and C declaration.
|
||||
- Parameters are omitted for the `void` and `Error *` types, or if the
|
||||
parameter is marked as [out].
|
||||
- Each function documentation is separated by a single line.
|
||||
|
||||
The C declaration is added to the end to show actual argument types.
|
||||
"""
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
import shutil
|
||||
import textwrap
|
||||
import subprocess
|
||||
|
||||
from xml.dom import minidom
|
||||
|
||||
# Text at the top of the doc file.
|
||||
preamble = '''
|
||||
Note: This documentation is generated from Neovim's API source code.
|
||||
'''
|
||||
|
||||
doc_filename = 'api-funcs.txt'
|
||||
|
||||
# Section name overrides.
|
||||
section_name = {
|
||||
'vim.c': 'Global',
|
||||
}
|
||||
|
||||
# Section ordering.
|
||||
section_order = (
|
||||
'vim.c',
|
||||
'buffer.c',
|
||||
'window.c',
|
||||
'tabpage.c',
|
||||
'ui.c',
|
||||
)
|
||||
|
||||
param_exclude = (
|
||||
'channel_id',
|
||||
)
|
||||
|
||||
text_width = 78
|
||||
script_path = os.path.abspath(__file__)
|
||||
base_dir = os.path.dirname(os.path.dirname(script_path))
|
||||
src_dir = os.path.join(base_dir, 'src/nvim/api')
|
||||
out_dir = os.path.join(base_dir, 'tmp/api_doc')
|
||||
filter_cmd = '%s %s' % (sys.executable, script_path)
|
||||
seen_funcs = set()
|
||||
|
||||
# Tracks `xrefsect` titles. As of this writing, used only for separating
|
||||
# deprecated functions.
|
||||
xrefs = set()
|
||||
|
||||
|
||||
# XML Parsing Utilities {{{
|
||||
def find_first(parent, name):
|
||||
"""Finds the first matching node within parent."""
|
||||
sub = parent.getElementsByTagName(name)
|
||||
if not sub:
|
||||
return None
|
||||
return sub[0]
|
||||
|
||||
|
||||
def get_children(parent, name):
|
||||
"""Yield matching child nodes within parent."""
|
||||
for child in parent.childNodes:
|
||||
if child.nodeType == child.ELEMENT_NODE and child.nodeName == name:
|
||||
yield child
|
||||
|
||||
|
||||
def get_child(parent, name):
|
||||
"""Get the first matching child node."""
|
||||
for child in get_children(parent, name):
|
||||
return child
|
||||
return None
|
||||
|
||||
|
||||
def clean_text(text):
|
||||
"""Cleans text.
|
||||
|
||||
Only cleans superfluous whitespace at the moment.
|
||||
"""
|
||||
return ' '.join(text.split()).strip()
|
||||
|
||||
|
||||
def clean_lines(text):
|
||||
"""Removes superfluous lines.
|
||||
|
||||
The beginning and end of the string is trimmed. Empty lines are collapsed.
|
||||
"""
|
||||
return re.sub(r'\A\n\s*\n*|\n\s*\n*\Z', '', re.sub(r'(\n\s*\n+)+', '\n\n', text))
|
||||
|
||||
|
||||
def get_text(parent):
|
||||
"""Combine all text in a node."""
|
||||
if parent.nodeType == parent.TEXT_NODE:
|
||||
return parent.data
|
||||
|
||||
out = ''
|
||||
for node in parent.childNodes:
|
||||
if node.nodeType == node.TEXT_NODE:
|
||||
out += clean_text(node.data)
|
||||
elif node.nodeType == node.ELEMENT_NODE:
|
||||
out += ' ' + get_text(node)
|
||||
return out
|
||||
|
||||
|
||||
def doc_wrap(text, prefix='', width=70, func=False):
|
||||
"""Wraps text to `width`.
|
||||
|
||||
The first line is prefixed with `prefix`, and subsequent lines are aligned.
|
||||
If `func` is True, only wrap at commas.
|
||||
"""
|
||||
if not width:
|
||||
return text
|
||||
|
||||
indent_space = ' ' * len(prefix)
|
||||
|
||||
if func:
|
||||
lines = [prefix]
|
||||
for part in text.split(', '):
|
||||
if part[-1] not in ');':
|
||||
part += ', '
|
||||
if len(lines[-1]) + len(part) > width:
|
||||
lines.append(indent_space)
|
||||
lines[-1] += part
|
||||
return '\n'.join(x.rstrip() for x in lines).rstrip()
|
||||
|
||||
return '\n'.join(textwrap.wrap(text.strip(), width=width,
|
||||
initial_indent=prefix,
|
||||
subsequent_indent=indent_space))
|
||||
|
||||
|
||||
def parse_params(parent, width=62):
|
||||
"""Parse Doxygen `parameterlist`."""
|
||||
name_length = 0
|
||||
items = []
|
||||
for child in parent.childNodes:
|
||||
if child.nodeType == child.TEXT_NODE:
|
||||
continue
|
||||
|
||||
name_node = find_first(child, 'parametername')
|
||||
if name_node.getAttribute('direction') == 'out':
|
||||
continue
|
||||
|
||||
name = get_text(name_node)
|
||||
if name in param_exclude:
|
||||
continue
|
||||
|
||||
name = '{%s}' % name
|
||||
name_length = max(name_length, len(name) + 2)
|
||||
|
||||
desc = ''
|
||||
desc_node = get_child(child, 'parameterdescription')
|
||||
if desc_node:
|
||||
desc = parse_parblock(desc_node, width=None)
|
||||
items.append((name.strip(), desc.strip()))
|
||||
|
||||
out = 'Parameters:~\n'
|
||||
for name, desc in items:
|
||||
name = ' %s' % name.ljust(name_length)
|
||||
out += doc_wrap(desc, prefix=name, width=width) + '\n'
|
||||
return out.strip()
|
||||
|
||||
|
||||
def parse_para(parent, width=62):
|
||||
"""Parse doxygen `para` tag.
|
||||
|
||||
I assume <para> is a paragraph block or "a block of text". It can contain
|
||||
text nodes, or other tags.
|
||||
"""
|
||||
line = ''
|
||||
lines = []
|
||||
for child in parent.childNodes:
|
||||
if child.nodeType == child.TEXT_NODE:
|
||||
line += child.data
|
||||
elif child.nodeName == 'computeroutput':
|
||||
line += '`%s`' % get_text(child)
|
||||
else:
|
||||
if line:
|
||||
lines.append(doc_wrap(line, width=width))
|
||||
line = ''
|
||||
|
||||
if child.nodeName == 'parameterlist':
|
||||
lines.append(parse_params(child, width=width))
|
||||
elif child.nodeName == 'xrefsect':
|
||||
title = get_text(get_child(child, 'xreftitle'))
|
||||
xrefs.add(title)
|
||||
xrefdesc = parse_para(get_child(child, 'xrefdescription'))
|
||||
lines.append(doc_wrap(xrefdesc, prefix='%s: ' % title,
|
||||
width=width) + '\n')
|
||||
elif child.nodeName == 'simplesect':
|
||||
kind = child.getAttribute('kind')
|
||||
if kind == 'return':
|
||||
lines.append('%s:~' % kind.title())
|
||||
lines.append(doc_wrap(parse_para(child),
|
||||
prefix=' ',
|
||||
width=width))
|
||||
else:
|
||||
lines.append(get_text(child))
|
||||
|
||||
if line:
|
||||
lines.append(doc_wrap(line, width=width))
|
||||
return clean_lines('\n'.join(lines).strip())
|
||||
|
||||
|
||||
def parse_parblock(parent, width=62):
|
||||
"""Parses a nested block of `para` tags.
|
||||
|
||||
Named after the \parblock command, but not directly related.
|
||||
"""
|
||||
paragraphs = []
|
||||
for child in parent.childNodes:
|
||||
if child.nodeType == child.TEXT_NODE:
|
||||
paragraphs.append(doc_wrap(child.data, width=width))
|
||||
elif child.nodeName == 'para':
|
||||
paragraphs.append(parse_para(child, width=width))
|
||||
else:
|
||||
paragraphs.append(doc_wrap(get_text(child), width=width))
|
||||
paragraphs.append('')
|
||||
return clean_lines('\n'.join(paragraphs).strip())
|
||||
# }}}
|
||||
|
||||
|
||||
def parse_source_xml(filename):
|
||||
"""Collects API functions.
|
||||
|
||||
This returns two strings:
|
||||
1. The API functions
|
||||
2. The deprecated API functions
|
||||
|
||||
The caller decides what to do with the deprecated documentation.
|
||||
"""
|
||||
global xrefs
|
||||
xrefs = set()
|
||||
functions = []
|
||||
deprecated_functions = []
|
||||
|
||||
dom = minidom.parse(filename)
|
||||
for member in dom.getElementsByTagName('memberdef'):
|
||||
if member.getAttribute('static') == 'yes' or \
|
||||
member.getAttribute('kind') != 'function':
|
||||
continue
|
||||
|
||||
loc = find_first(member, 'location')
|
||||
if 'private' in loc.getAttribute('file'):
|
||||
continue
|
||||
|
||||
return_type = get_text(get_child(member, 'type'))
|
||||
if return_type == '':
|
||||
continue
|
||||
|
||||
if return_type.startswith(('ArrayOf', 'DictionaryOf')):
|
||||
parts = return_type.strip('_').split('_')
|
||||
return_type = '%s(%s)' % (parts[0], ', '.join(parts[1:]))
|
||||
|
||||
name = get_text(get_child(member, 'name'))
|
||||
|
||||
vimtag = '*%s()*' % name
|
||||
args = []
|
||||
type_length = 0
|
||||
|
||||
for param in get_children(member, 'param'):
|
||||
arg_type = get_text(get_child(param, 'type')).strip()
|
||||
arg_name = ''
|
||||
declname = get_child(param, 'declname')
|
||||
if declname:
|
||||
arg_name = get_text(declname).strip()
|
||||
|
||||
if arg_name in param_exclude:
|
||||
continue
|
||||
|
||||
if arg_type.endswith('*'):
|
||||
arg_type = arg_type.strip('* ')
|
||||
arg_name = '*' + arg_name
|
||||
type_length = max(type_length, len(arg_type))
|
||||
args.append((arg_type, arg_name))
|
||||
|
||||
c_args = []
|
||||
for arg_type, arg_name in args:
|
||||
c_args.append(' ' + (
|
||||
'%s %s' % (arg_type.ljust(type_length), arg_name)).strip())
|
||||
|
||||
c_decl = textwrap.indent('%s %s(\n%s\n);' % (return_type, name,
|
||||
',\n'.join(c_args)),
|
||||
' ')
|
||||
|
||||
prefix = '%s(' % name
|
||||
suffix = '%s)' % ', '.join('{%s}' % a[1] for a in args
|
||||
if a[0] not in ('void', 'Error'))
|
||||
|
||||
# Minimum 8 chars between signature and vimtag
|
||||
lhs = (text_width - 8) - len(prefix)
|
||||
|
||||
if len(prefix) + len(suffix) > lhs:
|
||||
signature = vimtag.rjust(text_width) + '\n'
|
||||
signature += doc_wrap(suffix, width=text_width-8, prefix=prefix,
|
||||
func=True)
|
||||
else:
|
||||
signature = prefix + suffix
|
||||
signature += vimtag.rjust(text_width - len(signature))
|
||||
|
||||
doc = ''
|
||||
desc = find_first(member, 'detaileddescription')
|
||||
if desc:
|
||||
doc = parse_parblock(desc)
|
||||
if 'DEBUG' in os.environ:
|
||||
print(textwrap.indent(
|
||||
re.sub(r'\n\s*\n+', '\n',
|
||||
desc.toprettyxml(indent=' ', newl='\n')), ' ' * 16))
|
||||
|
||||
if not doc:
|
||||
doc = 'TODO: Documentation'
|
||||
|
||||
if 'INCLUDE_C_DECL' in os.environ:
|
||||
doc += '\n\nC Declaration:~\n>\n'
|
||||
doc += c_decl
|
||||
doc += '\n<'
|
||||
|
||||
func_doc = signature + '\n'
|
||||
func_doc += textwrap.indent(clean_lines(doc), ' ' * 16)
|
||||
func_doc = re.sub(r'^\s+([<>])$', r'\1', func_doc, flags=re.M)
|
||||
|
||||
if 'Deprecated' in xrefs:
|
||||
deprecated_functions.append(func_doc)
|
||||
else:
|
||||
functions.append(func_doc)
|
||||
|
||||
xrefs.clear()
|
||||
|
||||
return '\n\n'.join(functions), '\n\n'.join(deprecated_functions)
|
||||
|
||||
|
||||
def gen_docs(config):
|
||||
"""Generate documentation.
|
||||
|
||||
Doxygen is called and configured through stdin.
|
||||
"""
|
||||
p = subprocess.Popen(['doxygen', '-'], stdin=subprocess.PIPE)
|
||||
p.communicate(config.format(input=src_dir, output=out_dir,
|
||||
filter=filter_cmd).encode('utf8'))
|
||||
if p.returncode:
|
||||
sys.exit(p.returncode)
|
||||
|
||||
title_length = 0
|
||||
sections = {}
|
||||
sep = '=' * text_width
|
||||
|
||||
base = os.path.join(out_dir, 'xml')
|
||||
dom = minidom.parse(os.path.join(base, 'index.xml'))
|
||||
for compound in dom.getElementsByTagName('compound'):
|
||||
if compound.getAttribute('kind') != 'file':
|
||||
continue
|
||||
|
||||
filename = get_text(find_first(compound, 'name'))
|
||||
if filename.endswith('.c'):
|
||||
functions, deprecated = parse_source_xml(
|
||||
os.path.join(base, '%s.xml' % compound.getAttribute('refid')))
|
||||
|
||||
if not functions and not deprecated:
|
||||
continue
|
||||
|
||||
if functions or deprecated:
|
||||
name = os.path.splitext(os.path.basename(filename))[0]
|
||||
if name == 'ui':
|
||||
name = name.upper()
|
||||
else:
|
||||
name = name.title()
|
||||
|
||||
doc = ''
|
||||
if functions:
|
||||
doc += '\n\n' + functions
|
||||
|
||||
if 'INCLUDE_DEPRECATED' in os.environ and deprecated:
|
||||
doc += '\n\n\nDeprecated %s Functions:~\n\n' % name
|
||||
doc += deprecated
|
||||
|
||||
if doc:
|
||||
filename = os.path.basename(filename)
|
||||
name = section_name.get(filename, name)
|
||||
title = '%s Functions' % name
|
||||
helptag = '*api-%s*' % name.lower()
|
||||
title_length = max(title_length, len(title))
|
||||
sections[filename] = (title, helptag, doc)
|
||||
|
||||
if not sections:
|
||||
return
|
||||
|
||||
title_left = '*%s*' % doc_filename
|
||||
title_center = 'Neovim API Function Reference'
|
||||
title_right = '{Nvim}'
|
||||
margin = max(len(title_left), len(title_right))
|
||||
head = (title_left.ljust(margin) +
|
||||
title_center.center(text_width - margin * 2) +
|
||||
title_right.rjust(margin)) + '\n'
|
||||
|
||||
head += '\n%s\n\n' % doc_wrap(preamble, width=text_width)
|
||||
head += 'Contents:\n\n'
|
||||
|
||||
docs = ''
|
||||
|
||||
title_length += len(str(len(section_order))) + 2
|
||||
i = 0
|
||||
for filename in section_order:
|
||||
if filename not in sections:
|
||||
continue
|
||||
title, helptag, section_doc = sections.pop(filename)
|
||||
|
||||
i += 1
|
||||
docs += sep
|
||||
title = '%d. %s' % (i, title)
|
||||
head += (title.ljust(title_length) + ' ' +
|
||||
helptag.replace('*', '|') + '\n')
|
||||
docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
|
||||
docs += section_doc
|
||||
docs += '\n\n\n'
|
||||
|
||||
if sections:
|
||||
# In case new API sources are added without updating the order dict.
|
||||
for title, helptag, section_doc in sections.values():
|
||||
i += 1
|
||||
docs += sep
|
||||
title = '%d. %s' % (i, title)
|
||||
head += (title.ljust(title_length) + ' ' +
|
||||
helptag.replace('*', '|') + '\n')
|
||||
docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
|
||||
docs += section_doc
|
||||
docs += '\n\n\n'
|
||||
|
||||
docs = '%s\n%s' % (head, docs)
|
||||
docs = docs.rstrip() + '\n\n'
|
||||
docs += ' vim:tw=78:ts=8:ft=help:norl:'
|
||||
|
||||
doc_file = os.path.join(base_dir, 'runtime/doc', doc_filename)
|
||||
with open(doc_file, 'wb') as fp:
|
||||
fp.write(docs.encode('utf8'))
|
||||
|
||||
shutil.rmtree(out_dir)
|
||||
|
||||
|
||||
def filter_source(filename):
|
||||
"""Filters the source to fix macros that confuse Doxygen."""
|
||||
with open(filename, 'rt') as fp:
|
||||
print(re.sub(r'^(ArrayOf|DictionaryOf)(\(.*?\))',
|
||||
lambda m: m.group(1)+'_'.join(
|
||||
re.split(r'[^\w]+', m.group(2))),
|
||||
fp.read(), flags=re.M))
|
||||
|
||||
|
||||
# Doxygen Config {{{
|
||||
Doxyfile = '''
|
||||
OUTPUT_DIRECTORY = {output}
|
||||
INPUT = {input}
|
||||
INPUT_ENCODING = UTF-8
|
||||
FILE_PATTERNS = *.h *.c
|
||||
RECURSIVE = YES
|
||||
INPUT_FILTER = "{filter}"
|
||||
EXCLUDE =
|
||||
EXCLUDE_SYMLINKS = NO
|
||||
EXCLUDE_PATTERNS = */private/*
|
||||
EXCLUDE_SYMBOLS =
|
||||
|
||||
GENERATE_HTML = NO
|
||||
GENERATE_DOCSET = NO
|
||||
GENERATE_HTMLHELP = NO
|
||||
GENERATE_QHP = NO
|
||||
GENERATE_TREEVIEW = NO
|
||||
GENERATE_LATEX = NO
|
||||
GENERATE_RTF = NO
|
||||
GENERATE_MAN = NO
|
||||
GENERATE_DOCBOOK = NO
|
||||
GENERATE_AUTOGEN_DEF = NO
|
||||
|
||||
GENERATE_XML = YES
|
||||
XML_OUTPUT = xml
|
||||
XML_PROGRAMLISTING = NO
|
||||
|
||||
ENABLE_PREPROCESSING = YES
|
||||
MACRO_EXPANSION = YES
|
||||
EXPAND_ONLY_PREDEF = NO
|
||||
'''
|
||||
# }}}
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) > 1:
|
||||
filter_source(sys.argv[1])
|
||||
else:
|
||||
gen_docs(Doxyfile)
|
||||
|
||||
# vim: set ft=python ts=4 sw=4 tw=79 et fdm=marker :
|
||||
Reference in New Issue
Block a user