#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <limits.h>
#include <lauxlib.h>
#include "nvim/api/buffer.h"
#include "nvim/api/private/helpers.h"
#include "nvim/api/private/defs.h"
#include "nvim/lua/executor.h"
#include "nvim/vim.h"
#include "nvim/buffer.h"
#include "nvim/charset.h"
#include "nvim/cursor.h"
#include "nvim/getchar.h"
#include "nvim/memline.h"
#include "nvim/memory.h"
#include "nvim/misc1.h"
#include "nvim/ex_cmds.h"
#include "nvim/mark.h"
#include "nvim/fileio.h"
#include "nvim/move.h"
#include "nvim/syntax.h"
#include "nvim/window.h"
#include "nvim/undo.h"
#include "nvim/ex_docmd.h"
#include "nvim/buffer_updates.h"

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

String	buffer_get_line (Buffer buffer, Integer index, Error *err)

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	buffer_set_line (Buffer buffer, Integer index, String line, Error *err)

void	buffer_del_line (Buffer buffer, Integer index, Error *err)

	ArrayOf (String)

void	buffer_set_line_slice (Buffer buffer, Integer start, Integer end, Boolean include_start, Boolean include_end, ArrayOf(String) replacement, Error *err)

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_SINCE(1)

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 (Buffer buffer, String mode, String lhs, String rhs, Dictionary opts, Error *err) FUNC_API_SINCE(6)

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

Dictionary	nvim_buf_get_commands (Buffer buffer, Dictionary 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	buffer_set_var (Buffer buffer, String name, Object value, Error *err)

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

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)

Integer	nvim_buf_get_number (Buffer buffer, Error *err) FUNC_API_DEPRECATED_SINCE(2)

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)

Boolean	nvim_buf_is_valid (Buffer buffer) FUNC_API_SINCE(1)

void	buffer_insert (Buffer buffer, Integer lnum, ArrayOf(String) lines, Error *err)

	ArrayOf (Integer, 2)

Integer	nvim_buf_add_highlight (Buffer buffer, Integer ns_id, String hl_group, Integer line, Integer col_start, Integer col_end, Error *err) FUNC_API_SINCE(1)

void	nvim_buf_clear_namespace (Buffer buffer, Integer ns_id, Integer line_start, Integer line_end, Error *err) FUNC_API_SINCE(5)

void	nvim_buf_clear_highlight (Buffer buffer, Integer ns_id, Integer line_start, Integer line_end, Error *err) FUNC_API_SINCE(1)

Integer	nvim_buf_set_virtual_text (Buffer buffer, Integer ns_id, Integer line, Array chunks, Dictionary opts, Error *err) FUNC_API_SINCE(5)

Function Documentation

ArrayOf ( String )

Retrieves a line range from the buffer

Deprecated:: use nvim_buf_get_lines(buffer, newstart, newend, false) where newstart = start + int(not include_start) - int(start < 0) newend = end + int(include_end) - int(end < 0) int(bool) = 1 if bool is true else 0

Parameters

	buffer	Buffer handle
	start	First line index
	end	Last line index
	include_start	True if the slice includes the `start` parameter
	include_end	True if the slice includes the `end` parameter
[out]	err	Error details, if any

Returns: Array of lines

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.

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	(	Integer	,
		2
	)

Return a tuple (row,col) representing the position of the named mark.

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

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

Parameters

	window	Window handle
[out]	err	Error details, if any

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

void buffer_del_line	(	Buffer	buffer,
		Integer	index,
		Error *	err
	)

Deletes a buffer line

Deprecated:: use nvim_buf_set_lines instead. for positive indices use "nvim_buf_set_lines(buffer, index, index+1, true, [])" for negative indices use "nvim_buf_set_lines(buffer, index-1, index, true, [])"

Parameters

	buffer	buffer handle
	index	line index
[out]	err	Error details, if any

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

Removes a buffer-scoped (b:) variable

Deprecated:

Parameters

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

Returns: Old value

String buffer_get_line	(	Buffer	buffer,
		Integer	index,
		Error *	err
	)

Gets a buffer line

Deprecated:: use nvim_buf_get_lines instead. for positive indices (including 0) use "nvim_buf_get_lines(buffer, index, index+1, true)" for negative indices use "nvim_buf_get_lines(buffer, index-1, index, true)"

Parameters

	buffer	Buffer handle
	index	Line index
[out]	err	Error details, if any

Returns: Line string

void buffer_insert	(	Buffer	buffer,
		Integer	lnum,
		ArrayOf(String)	lines,
		Error *	err
	)

Inserts a sequence of lines to a buffer at a certain index

Deprecated:: use nvim_buf_set_lines(buffer, lnum, lnum, true, lines)

Parameters

	buffer	Buffer handle
	lnum	Insert the lines after `lnum`. If negative, appends to the end of the buffer.
	lines	Array of lines
[out]	err	Error details, if any

void buffer_set_line	(	Buffer	buffer,
		Integer	index,
		String	line,
		Error *	err
	)

Sets a buffer line

Deprecated:: use nvim_buf_set_lines instead. for positive indices use "nvim_buf_set_lines(buffer, index, index+1, true, [line])" for negative indices use "nvim_buf_set_lines(buffer, index-1, index, true, [line])"

Parameters

	buffer	Buffer handle
	index	Line index
	line	Contents of the new line
[out]	err	Error details, if any

void buffer_set_line_slice	(	Buffer	buffer,
		Integer	start,
		Integer	end,
		Boolean	include_start,
		Boolean	include_end,
		ArrayOf(String)	replacement,
		Error *	err
	)

Replaces a line range on the buffer

Deprecated:: use nvim_buf_set_lines(buffer, newstart, newend, false, lines) where newstart = start + int(not include_start) + int(start < 0) newend = end + int(include_end) + int(end < 0) int(bool) = 1 if bool is true else 0

Parameters

	buffer	Buffer handle, or 0 for current buffer
	start	First line index
	end	Last line index
	include_start	True if the slice includes the `start` parameter
	include_end	True if the slice includes the `end` parameter
	replacement	Array of lines to use as replacement (0-length
[out]	err	Error details, if any

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

Sets a buffer-scoped (b:) variable

Deprecated:

Parameters

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

Returns

Old value or nil if there was no previous value.

    @warning It may return nil if there was no previous value
             or if previous value was `v:null`.

Integer nvim_buf_add_highlight	(	Buffer	buffer,
		Integer	ns_id,
		String	hl_group,
		Integer	line,
		Integer	col_start,
		Integer	col_end,
		Error *	err
	)

Adds a highlight to buffer.

Useful for plugins that 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.

Namespaces are used for batch deletion/updating of a set of highlights. To create a namespace, use |nvim_create_namespace| which returns a namespace id. Pass it in to this function as ns_id to add highlights to the namespace. All highlights in the same namespace can then be cleared with single call to |nvim_buf_clear_namespace|. If the highlight never will be deleted by an API call, pass ns_id = -1.

As a shorthand, ns_id = 0 can be used to create a new namespace for the highlight, the allocated id is then returned. If hl_group is the empty string no highlight is added, but a new ns_id is still returned. This is supported for backwards compatibility, new code should use |nvim_create_namespace| to create a new empty namespace.

Parameters

	buffer	Buffer handle, or 0 for current buffer
	ns_id	namespace to use or -1 for ungrouped highlight
	hl_group	Name of the highlight group to use
	line	Line to highlight (zero-indexed)
	col_start	Start of (byte-indexed) column range to highlight
	col_end	End of (byte-indexed) column range to highlight, or -1 to highlight to end of line
[out]	err	Error details, if any

Returns: The ns_id that was used

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.

Parameters

	channel_id
	buffer	Buffer handle, or 0 for current buffer
	send_buffer	Set to true if the initial notification should contain the whole buffer. If so, the first notification will be a `nvim_buf_lines_event`. Otherwise, the first notification will be a `nvim_buf_changedtick_event`. Not used for lua callbacks.
	opts	Optional parameters. `on_lines`: lua callback received on change. `on_changedtick`: lua callback received on changedtick increment without text change. See \|api-buffer-updates-lua\| for more information
[out]	err	Error details, if any

Returns: False when updates couldn't be enabled because the buffer isn't loaded or opts contained an invalid key; otherwise True. TODO: LUA_API_NO_EVAL

void nvim_buf_clear_highlight	(	Buffer	buffer,
		Integer	ns_id,
		Integer	line_start,
		Integer	line_end,
		Error *	err
	)

Clears highlights and virtual text from namespace and range of lines

Deprecated:: use |nvim_buf_clear_namespace|.

Parameters

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

void nvim_buf_clear_namespace	(	Buffer	buffer,
		Integer	ns_id,
		Integer	line_start,
		Integer	line_end,
		Error *	err
	)

Clears namespaced objects, highlights and virtual text, from a line range

Lines are 0-indexed. |api-indexing| To clear the namespace in the entire buffer, specify line_start=0 and line_end=-1.

Parameters

	buffer	Buffer handle, or 0 for current buffer
	ns_id	Namespace to clear, or -1 to clear all namespaces.
	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 buffer.
[out]	err	Error details, if any

void nvim_buf_del_keymap	(	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

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

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

Deactivates buffer-update events on the channel.

Parameters

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

Returns: False when updates couldn't be disabled because the buffer isn't loaded; otherwise True.

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.

Dictionary nvim_buf_get_commands	(	Buffer	buffer,
		Dictionary	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.

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

Integer nvim_buf_get_number	(	Buffer	buffer,
		Error *	err
	)

Gets the buffer number

Deprecated:: The buffer number now is equal to the object id, so there is no need to use this function.

Parameters

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

Returns: Buffer number

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.

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

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

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.

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.

Integer nvim_buf_line_count	(	Buffer	buffer,
		Error *	err
	)

Gets the buffer line count

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|

void nvim_buf_set_keymap	(	Buffer	buffer,
		String	mode,
		String	lhs,
		String	rhs,
		Dictionary	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

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

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

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

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

Integer nvim_buf_set_virtual_text	(	Buffer	buffer,
		Integer	ns_id,
		Integer	line,
		Array	chunks,
		Dictionary	opts,
		Error *	err
	)

Set the virtual text (annotation) for a buffer line.

By default (and currently the only option) the text will be placed after the buffer text. Virtual text will never cause reflow, rather virtual text will be truncated at the end of the screen line. The virtual text will begin one cell (|lcs-eol| or space) after the ordinary text.

Namespaces are used to support batch deletion/updating of virtual text. To create a namespace, use |nvim_create_namespace|. Virtual text is cleared using |nvim_buf_clear_namespace|. The same ns_id can be used for both virtual text and highlights added by |nvim_buf_add_highlight|, both can then be cleared with a single call to |nvim_buf_clear_namespace|. If the virtual text never will be cleared by an API call, pass ns_id = -1.

As a shorthand, ns_id = 0 can be used to create a new namespace for the virtual text, the allocated id is then returned.

Parameters

	buffer	Buffer handle, or 0 for current buffer
	ns_id	Namespace to use or 0 to create a namespace, or -1 for a ungrouped annotation
	line	Line to annotate with virtual text (zero-indexed)
	chunks	A list of [text, hl_group] arrays, each representing a text chunk with specified highlight. `hl_group` element can be omitted for no highlight.
	opts	Optional parameters. Currently not used.
[out]	err	Error details, if any

Returns: The ns_id that was used

Functions

Function Documentation