Functions
buffer.c File Reference
#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/buffer.h"
#include "nvim/buffer_updates.h"
#include "nvim/change.h"
#include "nvim/charset.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/fileio.h"
#include "nvim/getchar.h"
#include "nvim/lua/executor.h"
#include "nvim/map.h"
#include "nvim/map_defs.h"
#include "nvim/mark.h"
#include "nvim/memline.h"
#include "nvim/memory.h"
#include "nvim/misc1.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 (Buffer buffer, String mode, String lhs, String rhs, Dict(keymap) *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, 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
 
Dictionary nvim__buf_stats (Buffer buffer, Error *err)
 

Function Documentation

◆ ArrayOf() [1/3]

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() [2/3]

ArrayOf ( Integer  ,
 
)

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

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, (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
windowWindow handle, or 0 for current window
[out]errError 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
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.

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
namepattern of files to search for
allwhether to return all matches or only the first
Returns
list of absolute paths to the found files

Find files in runtime directories

Parameters
patpattern of files to search for
allwhether to return all matches or only the first
optionsis_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
bufferBuffer handle, or 0 for current buffer
send_bufferTrue 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.
optsOptional 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 "detach"
    • 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]errError 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 (calleed 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
bufferBuffer handle, or 0 for current buffer
funFunction to call inside the buffer (currently lua callable only)
[out]errError 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_del_keymap()

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

◆ 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
bufferBuffer to set the mark on
nameMark name
Returns
true if the mark was deleted, else false.
See also
|nvim_buf_set_mark()|
|nvim_del_mark()|

◆ nvim_buf_del_var()

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

◆ nvim_buf_delete()

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

Deletes the buffer. See |:bwipeout|

Parameters
bufferBuffer handle, or 0 for current buffer
optsOptional 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
bufferBuffer handle, or 0 for current buffer
[out]errError 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]bufferBuffer handle, or 0 for current buffer
[out]errError 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
bufferBuffer handle, or 0 for current buffer
optsOptional parameters. Currently not used.
[out]errError 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
bufferBuffer handle, or 0 for current buffer
[out]errError 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
bufferBuffer handle, or 0 for current buffer
indexLine index
[out]errError 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
bufferBuffer handle, or 0 for current buffer
nameOption name
[out]errError 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
bufferBuffer handle, or 0 for current buffer
nameVariable name
[out]errError 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
bufferBuffer 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
bufferBuffer 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 
)

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|

◆ nvim_buf_set_keymap()

void nvim_buf_set_keymap ( 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
bufferBuffer 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
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

◆ 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
bufferBuffer to set the mark on
nameMark name
lineLine number
colColumn/row number
optsOptional 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
bufferBuffer handle, or 0 for current buffer
nameBuffer name
[out]errError 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
bufferBuffer handle, or 0 for current buffer
nameOption name
valueOption value
[out]errError 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 and end-exclusive.

To insert text at a given index, set start and end ranges to the same index. To delete a range, set replacement to an array containing an empty string, or simply an empty array.

Prefer nvim_buf_set_lines when adding or deleting entire lines only.

Parameters
channel_id
bufferBuffer handle, or 0 for current buffer
start_rowFirst line index
start_columnLast column
end_rowLast line index
end_columnLast column
replacementArray of lines to use as replacement
[out]errError 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
bufferBuffer handle, or 0 for current buffer
nameVariable name
valueVariable value
[out]errError details, if any