#include <lauxlib.h>
#include <limits.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include "nvim/api/buffer.h"
#include "nvim/api/private/defs.h"
#include "nvim/api/private/helpers.h"
#include "nvim/autocmd.h"
#include "nvim/buffer.h"
#include "nvim/buffer_updates.h"
#include "nvim/change.h"
#include "nvim/cursor.h"
#include "nvim/decoration.h"
#include "nvim/ex_cmds.h"
#include "nvim/ex_docmd.h"
#include "nvim/extmark.h"
#include "nvim/lua/executor.h"
#include "nvim/mark.h"
#include "nvim/memline.h"
#include "nvim/memory.h"
#include "nvim/move.h"
#include "nvim/ops.h"
#include "nvim/undo.h"
#include "nvim/vim.h"
#include "nvim/window.h"

Functions
Integer	nvim_buf_line_count (Buffer buffer, Error *err) FUNC_API_SINCE(1)

Boolean	nvim_buf_attach (uint64_t channel_id, Buffer buffer, Boolean send_buffer, DictionaryOf(LuaRef) opts, Error *err) FUNC_API_SINCE(4)

Boolean	nvim_buf_detach (uint64_t channel_id, Buffer buffer, Error *err) FUNC_API_SINCE(4) FUNC_API_REMOTE_ONLY

void	nvim__buf_redraw_range (Buffer buffer, Integer first, Integer last, Error *err)

	ArrayOf (String)

void	nvim_buf_set_lines (uint64_t channel_id, Buffer buffer, Integer start, Integer end, Boolean strict_indexing, ArrayOf(String) replacement, Error *err) FUNC_API_CHECK_TEXTLOCK

void	nvim_buf_set_text (uint64_t channel_id, Buffer buffer, Integer start_row, Integer start_col, Integer end_row, Integer end_col, ArrayOf(String) replacement, Error *err) FUNC_API_SINCE(7)

Integer	nvim_buf_get_offset (Buffer buffer, Integer index, Error *err) FUNC_API_SINCE(5)

Object	nvim_buf_get_var (Buffer buffer, String name, Error *err) FUNC_API_SINCE(1)

Integer	nvim_buf_get_changedtick (Buffer buffer, Error *err) FUNC_API_SINCE(2)

	ArrayOf (Dictionary)

void	nvim_buf_set_keymap (uint64_t channel_id, Buffer buffer, String mode, String lhs, String rhs, Dict(keymap) opts, Error err) FUNC_API_SINCE(6)

void	nvim_buf_del_keymap (uint64_t channel_id, Buffer buffer, String mode, String lhs, Error *err) FUNC_API_SINCE(6)

Dictionary	nvim_buf_get_commands (Buffer buffer, Dict(get_commands) opts, Error err) FUNC_API_SINCE(4)

void	nvim_buf_set_var (Buffer buffer, String name, Object value, Error *err) FUNC_API_SINCE(1)

void	nvim_buf_del_var (Buffer buffer, String name, Error *err) FUNC_API_SINCE(1)

Object	nvim_buf_get_option (Buffer buffer, String name, Error *err) FUNC_API_SINCE(1)

void	nvim_buf_set_option (uint64_t channel_id, Buffer buffer, String name, Object value, Error *err) FUNC_API_SINCE(1)

String	nvim_buf_get_name (Buffer buffer, Error *err) FUNC_API_SINCE(1)

void	nvim_buf_set_name (Buffer buffer, String name, Error *err) FUNC_API_SINCE(1)

Boolean	nvim_buf_is_loaded (Buffer buffer) FUNC_API_SINCE(5)

void	nvim_buf_delete (Buffer buffer, Dictionary opts, Error *err) FUNC_API_CHECK_TEXTLOCK

Boolean	nvim_buf_is_valid (Buffer buffer) FUNC_API_SINCE(1)

Boolean	nvim_buf_del_mark (Buffer buffer, String name, Error *err) FUNC_API_SINCE(8)

Boolean	nvim_buf_set_mark (Buffer buffer, String name, Integer line, Integer col, Dictionary opts, Error *err) FUNC_API_SINCE(8)

	ArrayOf (Integer, 2)

Object	nvim_buf_call (Buffer buffer, LuaRef fun, Error *err) FUNC_API_LUA_ONLY

void	nvim_buf_create_user_command (Buffer buffer, String name, Object command, Dict(user_command) opts, Error err) FUNC_API_SINCE(9)

void	nvim_buf_del_user_command (Buffer buffer, String name, Error *err) FUNC_API_SINCE(9)

Dictionary	nvim__buf_stats (Buffer buffer, Error *err)

Function Documentation

◆ ArrayOf() [1/3]

ArrayOf ( Dictionary )

Gets a list of buffer-local |mapping| definitions.

Parameters

	mode	Mode short-name ("n", "i", "v", ...)
	buffer	Buffer handle, or 0 for current buffer
[out]	err	Error details, if any

Returns: Array of maparg()-like dictionaries describing mappings. The "buffer" key holds the associated buffer handle.

◆ ArrayOf() [2/3]

ArrayOf	(	Integer	,
		2
	)

Returns a tuple (row,col) representing the position of the named mark. See |mark-motions|.

Marks are (1,0)-indexed. |api-indexing|

Parameters

	buffer	Buffer handle, or 0 for current buffer
	name	Mark name
[out]	err	Error details, if any

Returns: (row, col) tuple, (0, 0) if the mark is not set, or is an uppercase/file mark set in another buffer.

See also: |nvim_buf_set_mark()|; |nvim_buf_del_mark()|

Gets the window position in display cells. First position is zero.

Parameters

	window	Window handle, or 0 for current window
[out]	err	Error details, if any

Returns: (row, col) tuple with the window position

◆ ArrayOf() [3/3]

ArrayOf ( String )

Gets a line-range from the buffer.

Indexing is zero-based, end-exclusive. Negative indices are interpreted as length+1+index: -1 refers to the index past the end. So to get the last element use start=-2 and end=-1.

Out-of-bounds indices are clamped to the nearest valid value, unless strict_indexing is set.

Parameters

	channel_id
	buffer	Buffer handle, or 0 for current buffer
	start	First line index
	end	Last line index, exclusive
	strict_indexing	Whether out-of-bounds should be an error.
[out]	err	Error details, if any

Returns: Array of lines, or empty array for unloaded buffer.

Gets a range from the buffer.

This differs from |nvim_buf_get_lines()| in that it allows retrieving only portions of a line.

Indexing is zero-based. Row indices are end-inclusive, and column indices are end-exclusive.

Prefer |nvim_buf_get_lines()| when retrieving entire lines.

Parameters

	channel_id
	buffer	Buffer handle, or 0 for current buffer
	start_row	First line index
	start_col	Starting column (byte offset) on first line
	end_row	Last line index, inclusive
	end_col	Ending column (byte offset) on last line, exclusive
	opts	Optional parameters. Currently unused.
[out]	err	Error details, if any

Returns: Array of lines, or empty array for unloaded buffer.

Find files in runtime directories

'name' can contain wildcards. For example nvim_get_runtime_file("colors/*.vim", true) will return all color scheme files. Always use forward slashes (/) in the search pattern for subdirectories regardless of platform.

It is not an error to not find any files. An empty array is returned then.

Parameters

name	pattern of files to search for
all	whether to return all matches or only the first

Returns: list of absolute paths to the found files

Find files in runtime directories

Parameters

pat	pattern of files to search for
all	whether to return all matches or only the first
opts	is_lua: only search lua subdirs

Returns: list of absolute paths to the found files

◆ nvim__buf_redraw_range()

void nvim__buf_redraw_range	(	Buffer	buffer,
		Integer	first,
		Integer	last,
		Error *	err
	)

◆ nvim__buf_stats()

Dictionary nvim__buf_stats	(	Buffer	buffer,
		Error *	err
	)

◆ nvim_buf_attach()

Boolean nvim_buf_attach	(	uint64_t	channel_id,
		Buffer	buffer,
		Boolean	send_buffer,
		DictionaryOf(LuaRef)	opts,
		Error *	err
	)

Activates buffer-update events on a channel, or as Lua callbacks.

Example (Lua): capture buffer updates in a global events variable (use "print(vim.inspect(events))" to see its contents):

  events = {}
  vim.api.nvim_buf_attach(0, false, {
    on_lines=function(...) table.insert(events, {...}) end})

See also: |nvim_buf_detach()|; |api-buffer-updates-lua|

Parameters

	channel_id
	buffer	Buffer handle, or 0 for current buffer
	send_buffer	True if the initial notification should contain the whole buffer: first notification will be `nvim_buf_lines_event`. Else the first notification will be `nvim_buf_changedtick_event`. Not for Lua callbacks.
	opts	Optional parameters. on_lines: Lua callback invoked on change. Return `true` to detach. Args: the string "lines" buffer handle b:changedtick first line that changed (zero-indexed) last line that was changed last line in the updated range byte count of previous contents deleted_codepoints (if `utf_sizes` is true) deleted_codeunits (if `utf_sizes` is true) on_bytes: lua callback invoked on change. This callback receives more granular information about the change compared to on_lines. Return `true` to detach. Args: the string "bytes" buffer handle b:changedtick start row of the changed text (zero-indexed) start column of the changed text byte offset of the changed text (from the start of the buffer) old end row of the changed text old end column of the changed text old end byte length of the changed text new end row of the changed text new end column of the changed text new end byte length of the changed text on_changedtick: Lua callback invoked on changedtick increment without text change. Args: the string "changedtick" buffer handle b:changedtick on_detach: Lua callback invoked on detach. Args: the string "detach" buffer handle on_reload: Lua callback invoked on reload. The entire buffer content should be considered changed. Args: the string "reload" buffer handle utf_sizes: include UTF-32 and UTF-16 size of the replaced region, as args to `on_lines`. preview: also attach to command preview (i.e. 'inccommand') events.
[out]	err	Error details, if any

Returns: False if attach failed (invalid parameter, or buffer isn't loaded); otherwise True. TODO: LUA_API_NO_EVAL

◆ nvim_buf_call()

Object nvim_buf_call	(	Buffer	buffer,
		LuaRef	fun,
		Error *	err
	)

call a function with buffer as temporary current buffer

This temporarily switches current buffer to "buffer". If the current window already shows "buffer", the window is not switched If a window inside the current tabpage (including a float) already shows the buffer One of these windows will be set as current window temporarily. Otherwise a temporary scratch window (called the "autocmd window" for historical reasons) will be used.

This is useful e.g. to call vimL functions that only work with the current buffer/window currently, like |termopen()|.

Parameters

	buffer	Buffer handle, or 0 for current buffer
	fun	Function to call inside the buffer (currently lua callable only)
[out]	err	Error details, if any

Returns: Return value of function. NB: will deepcopy lua values currently, use upvalues to send lua references in and out.

◆ nvim_buf_create_user_command()

void nvim_buf_create_user_command	(	Buffer	buffer,
		String	name,
		Object	command,
		Dict(user_command) *	opts,
		Error *	err
	)

Create a new user command |user-commands| in the given buffer.

Parameters

	buffer	Buffer handle, or 0 for current buffer.
[out]	err	Error details, if any.

See also: nvim_create_user_command

◆ nvim_buf_del_keymap()

void nvim_buf_del_keymap	(	uint64_t	channel_id,
		Buffer	buffer,
		String	mode,
		String	lhs,
		Error *	err
	)

Unmaps a buffer-local |mapping| for the given mode.

See also: |nvim_del_keymap()|

Parameters

buffer Buffer handle, or 0 for current buffer

◆ nvim_buf_del_mark()

Boolean nvim_buf_del_mark	(	Buffer	buffer,
		String	name,
		Error *	err
	)

Deletes a named mark in the buffer. See |mark-motions|.

Note: only deletes marks set in the buffer, if the mark is not set in the buffer it will return false.

Parameters

buffer	Buffer to set the mark on
name	Mark name

Returns: true if the mark was deleted, else false.

See also: |nvim_buf_set_mark()|; |nvim_del_mark()|

◆ nvim_buf_del_user_command()

void nvim_buf_del_user_command	(	Buffer	buffer,
		String	name,
		Error *	err
	)

Delete a buffer-local user-defined command.

Only commands created with |:command-buffer| or |nvim_buf_create_user_command()| can be deleted with this function.

Parameters

	buffer	Buffer handle, or 0 for current buffer.
	name	Name of the command to delete.
[out]	err	Error details, if any.

◆ nvim_buf_del_var()

void nvim_buf_del_var	(	Buffer	buffer,
		String	name,
		Error *	err
	)

Removes a buffer-scoped (b:) variable

Parameters

	buffer	Buffer handle, or 0 for current buffer
	name	Variable name
[out]	err	Error details, if any

◆ nvim_buf_delete()

void nvim_buf_delete	(	Buffer	buffer,
		Dictionary	opts,
		Error *	err
	)

Deletes the buffer. See |:bwipeout|

Parameters

buffer	Buffer handle, or 0 for current buffer
opts	Optional parameters. Keys: force: Force deletion and ignore unsaved changes. unload: Unloaded only, do not delete. See \|:bunload\|

◆ nvim_buf_detach()

Boolean nvim_buf_detach	(	uint64_t	channel_id,
		Buffer	buffer,
		Error *	err
	)

Deactivates buffer-update events on the channel.

See also: |nvim_buf_attach()|; |api-lua-detach| for detaching Lua callbacks

Parameters

	channel_id
	buffer	Buffer handle, or 0 for current buffer
[out]	err	Error details, if any

Returns: False if detach failed (because the buffer isn't loaded); otherwise True.

◆ nvim_buf_get_changedtick()

Integer nvim_buf_get_changedtick	(	Buffer	buffer,
		Error *	err
	)

Gets a changed tick of a buffer

Parameters

[in]	buffer	Buffer handle, or 0 for current buffer
[out]	err	Error details, if any

Returns: b:changedtick value.

◆ nvim_buf_get_commands()

Dictionary nvim_buf_get_commands	(	Buffer	buffer,
		Dict(get_commands) *	opts,
		Error *	err
	)

Gets a map of buffer-local |user-commands|.

Parameters

	buffer	Buffer handle, or 0 for current buffer
	opts	Optional parameters. Currently not used.
[out]	err	Error details, if any.

Returns: Map of maps describing commands.

◆ nvim_buf_get_name()

String nvim_buf_get_name	(	Buffer	buffer,
		Error *	err
	)

Gets the full file name for the buffer

Parameters

	buffer	Buffer handle, or 0 for current buffer
[out]	err	Error details, if any

Returns: Buffer name

◆ nvim_buf_get_offset()

Integer nvim_buf_get_offset	(	Buffer	buffer,
		Integer	index,
		Error *	err
	)

Returns the byte offset of a line (0-indexed). |api-indexing|

Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte. 'fileformat' and 'fileencoding' are ignored. The line index just after the last line gives the total byte-count of the buffer. A final EOL byte is counted if it would be written, see 'eol'.

Unlike |line2byte()|, throws error for out-of-bounds indexing. Returns -1 for unloaded buffer.

Parameters

	buffer	Buffer handle, or 0 for current buffer
	index	Line index
[out]	err	Error details, if any

Returns: Integer byte offset, or -1 for unloaded buffer.

◆ nvim_buf_get_option()

Object nvim_buf_get_option	(	Buffer	buffer,
		String	name,
		Error *	err
	)

Gets a buffer option value

Parameters

	buffer	Buffer handle, or 0 for current buffer
	name	Option name
[out]	err	Error details, if any

Returns: Option value

◆ nvim_buf_get_var()

Object nvim_buf_get_var	(	Buffer	buffer,
		String	name,
		Error *	err
	)

Gets a buffer-scoped (b:) variable.

Parameters

	buffer	Buffer handle, or 0 for current buffer
	name	Variable name
[out]	err	Error details, if any

Returns: Variable value

◆ nvim_buf_is_loaded()

Boolean nvim_buf_is_loaded ( Buffer buffer )

Checks if a buffer is valid and loaded. See |api-buffer| for more info about unloaded buffers.

Parameters

buffer Buffer handle, or 0 for current buffer

Returns: true if the buffer is valid and loaded, false otherwise.

◆ nvim_buf_is_valid()

Boolean nvim_buf_is_valid ( Buffer buffer )

Checks if a buffer is valid.

Note: Even if a buffer is valid it may have been unloaded. See |api-buffer| for more info about unloaded buffers.

Parameters

buffer Buffer handle, or 0 for current buffer

Returns: true if the buffer is valid, false otherwise.

◆ nvim_buf_line_count()

Integer nvim_buf_line_count	(	Buffer	buffer,
		Error *	err
	)

Returns the number of lines in the given buffer.

Parameters

	buffer	Buffer handle, or 0 for current buffer
[out]	err	Error details, if any

Returns: Line count, or 0 for unloaded buffer. |api-buffer|

◆ nvim_buf_set_keymap()

void nvim_buf_set_keymap	(	uint64_t	channel_id,
		Buffer	buffer,
		String	mode,
		String	lhs,
		String	rhs,
		Dict(keymap) *	opts,
		Error *	err
	)

Sets a buffer-local |mapping| for the given mode.

See also: |nvim_set_keymap()|

Parameters

buffer Buffer handle, or 0 for current buffer

◆ nvim_buf_set_lines()

void nvim_buf_set_lines	(	uint64_t	channel_id,
		Buffer	buffer,
		Integer	start,
		Integer	end,
		Boolean	strict_indexing,
		ArrayOf(String)	replacement,
		Error *	err
	)

Sets (replaces) a line-range in the buffer.

Indexing is zero-based, end-exclusive. Negative indices are interpreted as length+1+index: -1 refers to the index past the end. So to change or delete the last element use start=-2 and end=-1.

To insert lines at a given index, set 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

	channel_id
	buffer	Buffer handle, or 0 for current buffer
	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
[out]	err	Error details, if any

◆ nvim_buf_set_mark()

Boolean nvim_buf_set_mark	(	Buffer	buffer,
		String	name,
		Integer	line,
		Integer	col,
		Dictionary	opts,
		Error *	err
	)

Sets a named mark in the given buffer, all marks are allowed file/uppercase, visual, last change, etc. See |mark-motions|.

Marks are (1,0)-indexed. |api-indexing|

Note: Passing 0 as line deletes the mark

Parameters

buffer	Buffer to set the mark on
name	Mark name
line	Line number
col	Column/row number
opts	Optional parameters. Reserved for future use.

Returns: true if the mark was set, else false.

See also: |nvim_buf_del_mark()|; |nvim_buf_get_mark()|

◆ nvim_buf_set_name()

void nvim_buf_set_name	(	Buffer	buffer,
		String	name,
		Error *	err
	)

Sets the full file name for a buffer

Parameters

	buffer	Buffer handle, or 0 for current buffer
	name	Buffer name
[out]	err	Error details, if any

◆ nvim_buf_set_option()

void nvim_buf_set_option	(	uint64_t	channel_id,
		Buffer	buffer,
		String	name,
		Object	value,
		Error *	err
	)

Sets a buffer option value. Passing 'nil' as value deletes the option (only works if there's a global fallback)

Parameters

	channel_id
	buffer	Buffer handle, or 0 for current buffer
	name	Option name
	value	Option value
[out]	err	Error details, if any

◆ nvim_buf_set_text()

void nvim_buf_set_text	(	uint64_t	channel_id,
		Buffer	buffer,
		Integer	start_row,
		Integer	start_col,
		Integer	end_row,
		Integer	end_col,
		ArrayOf(String)	replacement,
		Error *	err
	)

Sets (replaces) a range in the buffer

This is recommended over |nvim_buf_set_lines()| when only modifying parts of a line, as extmarks will be preserved on non-modified parts of the touched lines.

Indexing is zero-based. Row indices are end-inclusive, and column indices are end-exclusive.

To insert text at a given (row, column) location, use start_row = end_row = row and start_col = end_col = col. To delete the text in a range, use replacement = {}.

Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire lines.

Parameters

	channel_id
	buffer	Buffer handle, or 0 for current buffer
	start_row	First line index
	start_col	Starting column (byte offset) on first line
	end_row	Last line index, inclusive
	end_col	Ending column (byte offset) on last line, exclusive
	replacement	Array of lines to use as replacement
[out]	err	Error details, if any

◆ nvim_buf_set_var()

void nvim_buf_set_var	(	Buffer	buffer,
		String	name,
		Object	value,
		Error *	err
	)

Sets a buffer-scoped (b:) variable

Parameters

	buffer	Buffer handle, or 0 for current buffer
	name	Variable name
	value	Variable value
[out]	err	Error details, if any

Functions

Function Documentation

◆ ArrayOf() [1/3]

◆ ArrayOf() [2/3]

◆ ArrayOf() [3/3]

◆ nvim__buf_redraw_range()

◆ nvim__buf_stats()

◆ nvim_buf_attach()

◆ nvim_buf_call()

◆ nvim_buf_create_user_command()

◆ nvim_buf_del_keymap()

◆ nvim_buf_del_mark()

◆ nvim_buf_del_user_command()

◆ nvim_buf_del_var()

◆ nvim_buf_delete()

◆ nvim_buf_detach()

◆ nvim_buf_get_changedtick()

◆ nvim_buf_get_commands()

◆ nvim_buf_get_name()

◆ nvim_buf_get_offset()

◆ nvim_buf_get_option()

◆ nvim_buf_get_var()

◆ nvim_buf_is_loaded()

◆ nvim_buf_is_valid()

◆ nvim_buf_line_count()

◆ nvim_buf_set_keymap()

◆ nvim_buf_set_lines()

◆ nvim_buf_set_mark()

◆ nvim_buf_set_name()

◆ nvim_buf_set_option()

◆ nvim_buf_set_text()

◆ nvim_buf_set_var()