Functions
buffer.c File Reference
#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/change.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)
 
Dictionary nvim__buf_stats (Buffer buffer, Error *err)
 

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
bufferBuffer handle
startFirst line index
endLast line index
include_startTrue if the slice includes the start parameter
include_endTrue if the slice includes the end parameter
[out]errError 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
bufferBuffer handle, or 0 for current buffer
startFirst line index
endLast line index (exclusive)
strict_indexingWhether out-of-bounds should be an error.
[out]errError details, if any
Returns
Array of lines, or empty array for unloaded buffer.
ArrayOf ( Dictionary  )

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

Parameters
modeMode short-name ("n", "i", "v", ...)
bufferBuffer handle, or 0 for current buffer
[out]errError details, if any
Returns
Array of maparg()-like dictionaries describing mappings. The "buffer" key holds the associated buffer handle.
ArrayOf ( Integer  ,
 
)

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

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

Parameters
bufferBuffer handle, or 0 for current buffer
nameMark name
[out]errError details, if any
Returns
(row, col) tuple

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

Parameters
windowWindow handle, or 0 for current window
[out]errError 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
bufferbuffer handle
indexline index
[out]errError details, if any
Object buffer_del_var ( Buffer  buffer,
String  name,
Error err 
)

Removes a buffer-scoped (b:) variable

Deprecated:
Parameters
bufferBuffer handle, or 0 for current buffer
nameVariable name
[out]errError 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
bufferBuffer handle
indexLine index
[out]errError 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
bufferBuffer handle
lnumInsert the lines after lnum. If negative, appends to the end of the buffer.
linesArray of lines
[out]errError 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
bufferBuffer handle
indexLine index
lineContents of the new line
[out]errError 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
bufferBuffer handle, or 0 for current buffer
startFirst line index
endLast line index
include_startTrue if the slice includes the start parameter
include_endTrue if the slice includes the end parameter
replacementArray of lines to use as replacement (0-length
[out]errError details, if any
Object buffer_set_var ( Buffer  buffer,
String  name,
Object  value,
Error err 
)

Sets a buffer-scoped (b:) variable

Deprecated:
Parameters
bufferBuffer handle, or 0 for current buffer
nameVariable name
valueVariable value
[out]errError 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`.  
Dictionary nvim__buf_stats ( Buffer  buffer,
Error err 
)
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
bufferBuffer handle, or 0 for current buffer
ns_idnamespace to use or -1 for ungrouped highlight
hl_groupName of the highlight group to use
lineLine to highlight (zero-indexed)
col_startStart of (byte-indexed) column range to highlight
col_endEnd of (byte-indexed) column range to highlight, or -1 to highlight to end of line
[out]errError 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
bufferBuffer handle, or 0 for current buffer
send_bufferSet 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.
optsOptional parameters.
  • on_lines: lua callback received on change.
  • on_changedtick: lua callback received on changedtick increment without text change.
  • utf_sizes: include UTF-32 and UTF-16 size of the replaced region. See |api-buffer-updates-lua| for more information
[out]errError 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
bufferBuffer handle, or 0 for current buffer
ns_idNamespace to clear, or -1 to clear all.
line_startStart of range of lines to clear
line_endEnd of range of lines to clear (exclusive) or -1 to clear to end of file.
[out]errError 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
bufferBuffer handle, or 0 for current buffer
ns_idNamespace to clear, or -1 to clear all namespaces.
line_startStart of range of lines to clear
line_endEnd of range of lines to clear (exclusive) or -1 to clear to end of buffer.
[out]errError 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
bufferBuffer handle, or 0 for current buffer
void nvim_buf_del_var ( Buffer  buffer,
String  name,
Error err 
)

Removes a buffer-scoped (b:) variable

Parameters
bufferBuffer handle, or 0 for current buffer
nameVariable name
[out]errError details, if any
Boolean nvim_buf_detach ( uint64_t  channel_id,
Buffer  buffer,
Error err 
)

Deactivates buffer-update events on the channel.

For Lua callbacks see |api-lua-detach|.

Parameters
channel_id
bufferBuffer handle, or 0 for current buffer
[out]errError 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]bufferBuffer handle, or 0 for current buffer
[out]errError 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
bufferBuffer handle, or 0 for current buffer
optsOptional parameters. Currently not used.
[out]errError 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
bufferBuffer handle, or 0 for current buffer
[out]errError 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
bufferBuffer handle, or 0 for current buffer
[out]errError 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
bufferBuffer handle, or 0 for current buffer
indexLine index
[out]errError 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
bufferBuffer handle, or 0 for current buffer
nameOption name
[out]errError details, if any
Returns
Option value
Object nvim_buf_get_var ( Buffer  buffer,
String  name,
Error err 
)

Gets a buffer-scoped (b:) variable.

Parameters
bufferBuffer handle, or 0 for current buffer
nameVariable name
[out]errError 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
bufferBuffer 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
bufferBuffer 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
bufferBuffer handle, or 0 for current buffer
[out]errError 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
bufferBuffer 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
bufferBuffer handle, or 0 for current buffer
startFirst line index
endLast line index (exclusive)
strict_indexingWhether out-of-bounds should be an error.
replacementArray of lines to use as replacement
[out]errError details, if any
void nvim_buf_set_name ( Buffer  buffer,
String  name,
Error err 
)

Sets the full file name for a buffer

Parameters
bufferBuffer handle, or 0 for current buffer
nameBuffer name
[out]errError 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
bufferBuffer handle, or 0 for current buffer
nameOption name
valueOption value
[out]errError details, if any
void nvim_buf_set_var ( Buffer  buffer,
String  name,
Object  value,
Error err 
)

Sets a buffer-scoped (b:) variable

Parameters
bufferBuffer handle, or 0 for current buffer
nameVariable name
valueVariable value
[out]errError 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
bufferBuffer handle, or 0 for current buffer
ns_idNamespace to use or 0 to create a namespace, or -1 for a ungrouped annotation
lineLine to annotate with virtual text (zero-indexed)
chunksA list of [text, hl_group] arrays, each representing a text chunk with specified highlight. hl_group element can be omitted for no highlight.
optsOptional parameters. Currently not used.
[out]errError details, if any
Returns
The ns_id that was used