Module vis

Lua Extension API for the [Vis Editor](https://github.com/martanne/vis).

*WARNING:* there is no stability guarantee at this time, the API might change without notice!

This document might be out of date, run `make luadoc` to regenerate it.

Info:

  • Release: 6f537f3
  • License: ISC
  • Author: Marc André Tanner

Class Vis

Vis.VERSION Version information.
Vis.count Current count.
Vis.events Events.
Vis.input_queue Currently unconsumed keys in the input queue.
Vis.lexers Scintillua lexer module.
Vis.lpeg LPeg lexer module.
Vis.mark Mark name in use.
Vis.mode Currently active mode.
Vis.modes Mode constants.
Vis.options Vis Options
Vis.recording Whether a macro is being recorded.
Vis.register Register name in use.
Vis.registers Registers.
Vis.ui User interface.
Vis.win Currently active window.
Vis:action_register(name, func[, help]) Register a Lua function as key action.
Vis:close(inputfd) Closes a stream returned by Vis:communicate.
Vis:command(command) Execute a `:`-command.
Vis:command_register(name, command[, help]) Register a custom `:`-command.
Vis:communicate(name, command) Open new process and return its input stream (stdin).
Vis:exit(code) Terminate editor process.
Vis:feedkeys(keys) Push keys to input queue and interpret them.
Vis:files() Create an iterator over all files.
Vis:info(message) Display a short message.
Vis:insert(keys) Insert keys at all cursor positions of active window.
Vis:map(mode, key, func[, help]) Map a key to a Lua function.
Vis:map(mode, key, action) Map a key to a key action.
Vis:map(mode, key, alias) Setup a key alias.
Vis:mappings(mode) Get all currently active mappings of a mode.
Vis:mark_names() Create an iterator over all mark names.
Vis:message(message) Display a multi line message.
Vis:module_exist(name) Check whether a Lua module exists
Vis:motion_new(key, motion[, help]) Map a new motion.
Vis:operator_new(key, operator[, help]) Map a new operator.
Vis:option_register(name, type, handler[, help]) Register a custom `:set` option.
Vis:option_unregister(name) Unregister a `:set` option.
Vis:pipe([file][, range], command[, fullscreen]) Pipe file range to external process and collect output.
Vis:redraw() Redraw complete user interface.
Vis:register_names() Create an iterator over all register names.
Vis:replace(keys) Replace keys at all cursor positions of active window.
Vis:textobject_new(key, textobject[, help]) Map a new text object.
Vis:unmap(mode, key) Unmap a global key binding.
Vis:windows() Create an iterator over all windows.

Class Ui

Ui.colors Number of available colors.
Ui.layout Current layout.

Class Window

Window.file The file being displayed in this window.
Window.height The window height.
Window.marks Window marks.
Window.options Window Options
Window.selection The primary selection of this window.
Window.selections The selections of this window.
Window.syntax The file type associated with this window.
Window.viewport Viewport currently being displayed.
Window.width The window width.
Window:close(force) Close window.
Window:draw() Redraw window content.
Window:map(...) Set up a window local key mapping.
Window:selections_iterator() Create an iterator over all selections of this window.
Window:set_syntax(syntax) Change syntax lexer to use for this window
Window:status(left[, right]) Set window status line.
Window:style(id, start, finish) Style a window range.
Window:style_define(id, style) Define a display style.
Window:unmap(...) Remove a window local key mapping.

Class Selection

Selection.anchored Whether this selection is anchored.
Selection.col The 1-based column position the cursor of this selection resides on.
Selection.line The 1-based line the cursor of this selection resides on.
Selection.number The 1-based selection index.
Selection.pos The zero based byte position in the file.
Selection.range The range covered by this selection.
Selection:remove() Remove selection.
Selection:to(line, col) Move cursor of selection.

Class File

File.lines File content by logical lines.
File.modified File state.
File.name File name.
File.path File path.
File.permission File permission.
File.savemethod File save method
File.size File size in bytes.
File:content(range) Get file content of range.
File:content(pos, len) Get file content of position and length.
File:delete(range) Delete file range.
File:delete(pos, len) Delete data at position.
File:insert(pos, data) Insert data at position.
File:lines_iterator() Create an iterator over all lines of the file.
File:mark_get(mark) Get position of mark.
File:mark_set(pos) Set mark.
File:match_at(pattern, pos[, horizon]) Check whether LPeg pattern matches at a given file position.
File:text_object_longword(pos) WORD text object.
File:text_object_word(pos) Word text object.

Class Range

Range.finish The end of the range.
Range.start The beginning of the range.

Layouts

layouts Layout Constants.

Modes

modes Mode constants.

Key Handling

keyhandler(keys) Example of a key handling function.

Core Events

file_close(file) File close.
file_open(file) File open.
file_save_post(file, path) File post save.
file_save_pre(file, path) File pre save.
init() Editor initialization completed.
input(key) Input key event in either input or replace mode.
process_response(name, response_type, code, buffer) The response received from the process started via Vis:communicate.
quit() Editor is about to terminate.
start() Editor startup completed.
term_csi(List) CSI command received from terminal.
win_close(win) Window close.
win_highlight(win) Window highlight.
win_open(win) Window open.
win_status(win) Window status bar redraw.

Events

events Event names.
events.emit(event, ...) Generate event.
events.subscribe(event, handler[, index]) Subscribe to an event.
events.unsubscribe(event, handler) Unsubscribe from an event.


Class Vis

The main editor object.
Vis.VERSION
Version information.
  • VERSION string version information in `git describe` format, same as reported by `vis -v`.
Vis.count
Current count.
  • count int the specified count for the current command or `nil` if none was given
Vis.events
Events.
Vis.input_queue
Currently unconsumed keys in the input queue.
Vis.lexers
Scintillua lexer module.
  • lexers might be `nil` if module is not found
Vis.lpeg
LPeg lexer module.
  • lpeg might be `nil` if module is not found
Vis.mark
Mark name in use.
Vis.mode
Currently active mode.
Vis.modes
Mode constants.
Vis.options
Vis Options

Fields:

  • autoindent boolean {ai} (default false)
  • changecolors boolean (default false)
  • escdelay int (default 50)
  • ignorecase boolean {ic} (default false)
  • loadmethod string `"auto"`, `"read"`, or `"mmap"`. (default "auto")
  • shell string (default "/bin/sh")

See also:

Vis.recording
Whether a macro is being recorded.
  • recording bool
Vis.register
Register name in use.
Vis.registers
Registers.
  • registers array to access the register by single letter name
Vis.ui
User interface.
  • ui Ui the user interface being used
Vis.win
Currently active window.

See also:

Vis:action_register(name, func[, help])
Register a Lua function as key action.

Parameters:

  • name string the name of the action, can be referred to in key bindings as `` pseudo key
  • func Function the lua function implementing the key action (see keyhandler)
  • help string the single line help text as displayed in `:help` (optional)

Returns:

    KeyAction action the registered key action

See also:

Vis:close(inputfd)
Closes a stream returned by Vis:communicate.

Parameters:

  • inputfd io.file the stream to be closed

Returns:

    bool identical to io.close
Vis:command(command)
Execute a `:`-command.

Parameters:

  • command string the command to execute

Returns:

    bool whether the command succeeded

Usage:

    vis:command("set number")
Vis:command_register(name, command[, help])
Register a custom `:`-command.

Parameters:

  • name string the command name
  • command function the Lua function implementing the command
  • help string the single line help text as displayed in `:help` (optional)

Returns:

    bool whether the command has been successfully registered

Usage:

    vis:command_register("foo", function(argv, force, win, selection, range)
    	 for i,arg in ipairs(argv) do
    		 print(i..": "..arg)
    	 end
    	 print("was command forced with ! "..(force and "yes" or "no"))
    	 print(win.file.name)
    	 print(selection.pos)
    	 print(range ~= nil and ('['..range.start..', '..range.finish..']') or "invalid range")
    	 return true;
    end)
Vis:communicate(name, command)
Open new process and return its input stream (stdin). If the stream is closed (by calling the close method or by being removed by a garbage collector) the spawned process will be killed by SIGTERM. When the process will quit or will output anything to stdout or stderr, the process_response event will be fired.

The editor core won't be blocked while the external process is running.

Parameters:

Returns:

    the file handle to write data to the process, in case of error the return values are equivalent to io.open error values.
Vis:exit(code)
Terminate editor process.

Termination happens upon the next iteration of the main event loop. This means the calling Lua code will be executed further until it eventually hands over control to the editor core. The exit status of the most recent call is used.

All unsaved changes will be lost!

Parameters:

  • code int the exit status returned to the operating system
Vis:feedkeys(keys)
Push keys to input queue and interpret them.

The keys are processed as if they were read from the keyboard.

Parameters:

  • keys string the keys to interpret
Vis:files()
Create an iterator over all files.

Returns:

    the new iterator

Usage:

    for file in vis:files() do
    	-- do something with file
    end
Vis:info(message)
Display a short message.

The single line message will be displayed at the bottom of the screen and automatically hidden once a key is pressed.

Parameters:

  • message string the message to display
Vis:insert(keys)
Insert keys at all cursor positions of active window.

This function behaves as if the keys were entered in insert mode, but in contrast to Vis:feedkeys it bypasses the input queue, meaning mappings do not apply and the keys will not be recorded in macros.

Parameters:

  • keys string the keys to insert

See also:

Vis:map(mode, key, func[, help])
Map a key to a Lua function.

Creates a new key mapping in a given mode.

Parameters:

  • mode int the mode to which the mapping should be added
  • key string the key to map
  • func function the Lua function to handle the key mapping (see keyhandler)
  • help string the single line help text as displayed in `:help` (optional)

Returns:

    bool whether the mapping was successfully established

See also:

Usage:

    vis:map(vis.modes.INSERT, "<C-k>", function(keys)
    	if #keys < 2 then
    		return -1 -- need more input
    	end
    	local digraph = keys:sub(1, 2)
    	if digraph == "l*" then
    		vis:feedkeys('λ')
    		return 2 -- consume 2 bytes of input
    	end
    end, "Insert digraph")
Vis:map(mode, key, action)
Map a key to a key action.

Parameters:

  • mode int the mode to which the mapping should be added
  • key string the key to map
  • action the action to map

Returns:

    bool whether the mapping was successfully established

See also:

Usage:

    local action = vis:action_register("info", function()
      vis:info("Mapping works!")
    end, "Info message help text")
    vis:map(vis.modes.NORMAL, "gh", action)
    vis:map(vis.modes.NORMAL, "gl", action)
Vis:map(mode, key, alias)
Setup a key alias.

This is equivalent to `vis:command('map! mode key alias')`.

Mappings are always recursive!

Parameters:

  • mode int the mode to which the mapping should be added
  • key string the key to map
  • alias string the key to map to

Returns:

    bool whether the mapping was successfully established

See also:

Usage:

    vis:map(vis.modes.NORMAL, "j", "k")
Vis:mappings(mode)
Get all currently active mappings of a mode.

Parameters:

  • mode int the mode to query

Returns:

    table the active mappings and their associated help texts

See also:

Usage:

    local bindings = vis:mappings(vis.modes.NORMAL)
    for key, help in pairs(bindings) do
    	-- do something
    end
Vis:mark_names()
Create an iterator over all mark names.

Returns:

    the new iterator

Usage:

    local marks = vis.win.marks
    for name in vis:mark_names() do
    	local mark = marks[name]
    	for i = 1, #mark do
    		-- do something with: name, mark[i].start, mark[i].finish
    	end
    end
Vis:message(message)
Display a multi line message.

Opens a new window and displays an arbitrarily long message.

Parameters:

  • message string the message to display
Vis:module_exist(name)
Check whether a Lua module exists Checks whether a subsequent require call will succeed.

Parameters:

  • name string the module name to check

Returns:

    bool whether the module was found
Vis:motion_new(key, motion[, help])
Map a new motion.

Sets up a mapping in normal, visual and operator pending mode. The motion function will receive the Window and an initial position (in bytes from the start of the file) as argument and is expected to return the resulting position.

Parameters:

  • key string the key to associate with the new option
  • motion function the motion logic implemented as Lua function
  • help string the single line help text as displayed in `:help` (optional)

Returns:

    bool whether the new motion could be installed

Usage:

    vis:motion_new("<C-l>", function(win, pos)
    	return pos+1
    end, "Advance to next byte")
Vis:operator_new(key, operator[, help])
Map a new operator.

Sets up a mapping in normal, visual and operator pending mode. The operator function will receive the File, Range and position to operate on and is expected to return the new cursor position.

Parameters:

  • key string the key to associate with the new operator
  • operator function the operator logic implemented as Lua function
  • help string the single line help text as displayed in `:help` (optional)

Returns:

    bool whether the new operator could be installed

Usage:

    vis:operator_new("gq", function(file, range, pos)
    	local status, out, err = vis:pipe(file, range, "fmt")
    	if status ~= 0 then
    		vis:info(err)
    	else
    		file:delete(range)
    		file:insert(range.start, out)
    	end
    	return range.start -- new cursor location
    end, "Formatting operator, filter range through fmt(1)")
Vis:option_register(name, type, handler[, help])
Register a custom `:set` option.

Parameters:

  • name string the option name
  • type string the option type (`bool`, `string` or `number`)
  • handler function the Lua function being called when the option is changed
  • help string the single line help text as displayed in `:help` (optional)

Returns:

    bool whether the option was successfully registered

Usage:

    vis:option_register("foo", "bool", function(value, toggle)
    	if not vis.win then return false end
    	vis.win.foo = toggle and not vis.win.foo or value
    	vis:info("Option foo = " .. tostring(vis.win.foo))
    	return true
    end, "Foo enables superpowers")
Vis:option_unregister(name)
Unregister a `:set` option.

Parameters:

Returns:

    bool whether the option was successfully unregistered
Vis:pipe([file][, range], command[, fullscreen])
Pipe file range to external process and collect output.

The editor core will be blocked while the external process is running. File and Range can be omitted or nil to indicate empty input.

Parameters:

  • file File the file to which the range applies (optional)
  • range Range the range to pipe (optional)
  • command string the command to execute
  • fullscreen bool whether command is a fullscreen program (e.g. curses based) (optional)

Returns:

  1. int code the exit status of the executed command
  2. string stdout the data written to stdout
  3. string stderr the data written to stderr
Vis:redraw()
Redraw complete user interface.

Will trigger redraw events, make sure to avoid recursive events.

Vis:register_names()
Create an iterator over all register names.

Returns:

    the new iterator

Usage:

    for name in vis:register_names() do
    	local reg = vis.registers[name]
    	for i = 1, #reg do
    		-- do something with register value reg[i]
    	end
    end
Vis:replace(keys)
Replace keys at all cursor positions of active window.

This function behaves as if the keys were entered in replace mode, but in contrast to Vis:feedkeys it bypasses the input queue, meaning mappings do not apply and the keys will not be recorded in macros.

Parameters:

  • keys string the keys to insert

See also:

Vis:textobject_new(key, textobject[, help])
Map a new text object.

Sets up a mapping in visual and operator pending mode. The text object function will receive the Window and an initial position(in bytes from the start of the file) as argument and is expected to return the resulting range or `nil`.

Parameters:

  • key string the key associated with the new text object
  • textobject function the text object logic implemented as Lua function
  • help string the single line help text as displayed in `:help` (optional)

Returns:

    bool whether the new text object could be installed

Usage:

    vis:textobject_new("<C-l>", function(win, pos)
    	return pos, pos+1
    end, "Single byte text object")
Vis:unmap(mode, key)
Unmap a global key binding.

Parameters:

  • mode int the mode from which the mapping should be removed
  • key string the mapping to remove

Returns:

    bool whether the mapping was successfully removed

See also:

Vis:windows()
Create an iterator over all windows.

Returns:

    the new iterator

See also:

Usage:

    for win in vis:windows() do
    	-- do something with win
    end

Class Ui

The user interface.
Ui.colors
Number of available colors.
  • colors int
Ui.layout
Current layout.
  • layout layouts current window layout.

Class Window

A window object.
Window.file
The file being displayed in this window.
Window.height
The window height.
  • height int
Window.marks
Window marks. Most of these marks are stored in the associated File object, meaning they are the same in all windows displaying the same file.
  • marks array to access the marks of this window by single letter name

See also:

Window.options
Window Options

Fields:

  • breakat string {brk} (default "")
  • colorcolumn int {cc} (default 0)
  • cursorline boolean {cul} (default false)
  • expandtab boolean {et} (default false)
  • numbers boolean {nu} (default false)
  • relativenumbers boolean {rnu} (default false)
  • showeof boolean (default true)
  • shownewlines boolean (default false)
  • showspaces boolean (default false)
  • showtabs boolean (default false)
  • statusbar boolean (default true)
  • tabwidth int {tw} (default 8)
  • wrapcolumn int {wc} (default 0)

See also:

Window.selection
The primary selection of this window.
Window.selections
The selections of this window.
  • selections Array(Selection)
Window.syntax
The file type associated with this window.
  • syntax string the syntax lexer name or `nil` if unset
Window.viewport
Viewport currently being displayed.
Window.width
The window width.
  • width int
Window:close(force)
Close window.

After a successful call the Window reference becomes invalid and must no longer be used. Attempting to close the last window will always fail.

Parameters:

  • force bool whether unsaved changes should be discarded

Returns:

    bool whether the window was closed

See also:

Window:draw()
Redraw window content.
Window:map(...)
Set up a window local key mapping. The function signatures are the same as for Vis:map.

Parameters:

  • ...

See also:

Window:selections_iterator()
Create an iterator over all selections of this window.

Returns:

    the new iterator
Window:set_syntax(syntax)
Change syntax lexer to use for this window

Parameters:

  • syntax string the syntax lexer name or `nil` to disable syntax highlighting

Returns:

    bool whether the lexer could be changed
Window:status(left[, right])
Set window status line.

Parameters:

  • left string the left aligned part of the status line
  • right string the right aligned part of the status line (optional)
Window:style(id, start, finish)
Style a window range.

The style will be cleared after every window redraw.

Parameters:

  • id int the display style as registered with style_define
  • start int the absolute file position in bytes
  • finish int the end position

See also:

Usage:

    win:style(win.STYLE_DEFAULT, 0, 10)
Window:style_define(id, style)
Define a display style.

Parameters:

  • id int the style id to use
  • style string the style definition

Returns:

    bool whether the style definition has been successfully associated with the given id

See also:

Usage:

    win:style_define(win.STYLE_DEFAULT, "fore:red")
Window:unmap(...)
Remove a window local key mapping. The function signature is the same as for Vis:unmap.

Parameters:

  • ...

See also:

Class Selection

A selection object.

A selection is a non-empty, directed range with two endpoints called *cursor* and *anchor*. A selection can be anchored in which case the anchor remains fixed while only the position of the cursor is adjusted. For non-anchored selections both endpoints are updated. A singleton selection covers one character on which both cursor and anchor reside. There always exists a primary selection which remains visible (i.e. changes to its position will adjust the viewport).

The range covered by a selection is represented as an interval whose endpoints are absolute byte offsets from the start of the file. Valid addresses are within the closed interval `[0, file.size]`.

Selections are currently implemented using character marks into the underlying persistent [text management data structure](https://github.com/martanne/vis/wiki/Text-management-using-a-piece-chain).

This has a few consequences you should be aware of:

- A selection becomes invalid when the delimiting boundaries of the underlying text it is referencing is deleted:

-- leaves selection in an invalid state win.file:delete(win.selection.pos, 1) assert(win.selection.pos == nil)

Like a regular mark it will become valid again when the text is reverted to the state before the deletion.

- Inserts after the selection position (`> selection.pos`) will not affect the selection position.

local pos = win.selection.pos win.file:insert(pos+1, "-") assert(win.selection.pos == pos)

- Non-cached inserts before the selection position (`<= selection.pos`) will affect the mark and adjust the selection position by the number of bytes which were inserted.

local pos = win.selection.pos win.file:insert(pos, "-") assert(win.selection.pos == pos+1)

- Cached inserts before the selection position (`<= selection.pos`) will not affect the selection position because the underlying text is replaced inplace.

For these reasons it is generally recommended to update the selection position after a modification. The general procedure amounts to:

1. Read out the current selection position 2. Perform text modifications 3. Update the selection position

This is what Vis:insert and Vis:replace do internally.

Usage:

local data = "new text"
local pos = win.selection.pos
win.file:insert(pos, data)
win.selection.pos = pos + #data
Selection.anchored
Whether this selection is anchored.
  • anchored bool
Selection.col
The 1-based column position the cursor of this selection resides on.
  • col int

See also:

Selection.line
The 1-based line the cursor of this selection resides on.
  • line int

See also:

Selection.number
The 1-based selection index.
  • number int
Selection.pos
The zero based byte position in the file.

Might be `nil` if the selection is in an invalid state. Setting this field will move the cursor endpoint of the selection to the given position.

  • pos int
Selection.range
The range covered by this selection.
Selection:remove()
Remove selection.
Selection:to(line, col)
Move cursor of selection.

Parameters:

  • line int the 1-based line number
  • col int the 1-based column number

Class File

A file object.
File.lines
File content by logical lines.

Assigning to array element `0` (`#lines+1`) will insert a new line at the beginning (end) of the file.

  • lines Array(string) the file content accessible as 1-based array

See also:

Usage:

    local lines = vis.win.file.lines
    for i=1, #lines do
    	lines[i] = i .. ": " .. lines[i]
    end
File.modified
File state.
  • modified bool whether the file contains unsaved changes
File.name
File name.
  • name string the file name relative to current working directory or `nil` if not yet named
File.path
File path.
  • path string the absolute file path or `nil` if not yet named
File.permission
File permission.
  • permission int the file permission bits as of the most recent load/save
File.savemethod
File save method
  • savemethod string `"auto"`, `"atomic"`, or `"inplace"`. (default "auto")
File.size
File size in bytes.
  • size int the current file size in bytes
File:content(range)
Get file content of range.

Parameters:

  • range Range the range to read

Returns:

    string the file content corresponding to the range
File:content(pos, len)
Get file content of position and length.

Parameters:

  • pos int the 0-based file position in bytes
  • len int the length in bytes to read

Returns:

    string the file content corresponding to the range

See also:

Usage:

    local file = vis.win.file
    local text = file:content(0, file.size)
File:delete(range)
Delete file range.

Parameters:

  • range Range the range to delete

Returns:

    bool whether the file content was successfully changed
File:delete(pos, len)
Delete data at position.

Parameters:

  • pos int the 0-based file position in bytes
  • len int the length in bytes to delete

Returns:

    bool whether the file content was successfully changed
File:insert(pos, data)
Insert data at position.

Parameters:

  • pos int the 0-based file position in bytes
  • data string the data to insert

Returns:

    bool whether the file content was successfully changed
File:lines_iterator()
Create an iterator over all lines of the file.

For large files this is probably faster than lines.

Returns:

    the new iterator

See also:

Usage:

    for line in file:lines_iterator() do
    	-- do something with line
    end
File:mark_get(mark)
Get position of mark.

Parameters:

  • mark Mark the mark to look up

Returns:

    int pos the position of the mark, or `nil` if invalid
File:mark_set(pos)
Set mark.

Parameters:

  • pos int the position to set the mark to, must be in [0, file.size]

Returns:

    Mark mark the mark which can be looked up later
File:match_at(pattern, pos[, horizon])
Check whether LPeg pattern matches at a given file position.

Parameters:

  • pattern the LPeg pattern
  • pos int the absolute file position which should be tested for a match
  • horizon int the number of bytes around `pos` to consider (defaults to 1K) (optional)

Returns:

    int start,end the range of the matched region or `nil`
File:text_object_longword(pos)
WORD text object.

Parameters:

  • pos int the position which must be part of the word

Returns:

    Range range the range
File:text_object_word(pos)
Word text object.

Parameters:

  • pos int the position which must be part of the word

Returns:

    Range range the range

Class Range

A file range.

For a valid range `start <= finish` holds. An invalid range is represented as `nil`.

Range.finish
The end of the range.
  • finish int
Range.start
The beginning of the range.
  • start int

Layouts

layouts
Layout Constants.

Fields:

  • HORIZONTAL int
  • VERTICAL int

Modes

modes
Mode constants.

Fields:

  • NORMAL int
  • OPERATOR_PENDING int
  • INSERT int
  • REPLACE int
  • VISUAL int
  • VISUAL_LINE int

See also:

Key Handling

This section describes the contract between the editor core and Lua key handling functions mapped to symbolic keys using either Vis:map or Window:map.

keyhandler(keys)
Example of a key handling function.

The keyhandler is invoked with the pending content of the input queue given as argument. This might be the empty string if no further input is available.

The function is expected to return the number of *bytes* it has consumed from the passed input keys. A negative return value is interpreted as an indication that not enough input was available. The function will be called again once the user has provided more input. A missing return value (i.e. `nil`) is interpreted as zero, meaning no further input was consumed but the function completed successfully.

Parameters:

  • keys string the keys following the mapping

Returns:

    int the number of *bytes* being consumed by the function (see above)

See also:

Usage:

    vis:map(vis.modes.INSERT, "<C-k>", function(keys)
    	if #keys < 2 then
    		return -1 -- need more input
    	end
    	local digraph = keys:sub(1, 2)
    	if digraph == "l*" then
    		vis:feedkeys('λ')
    		return 2 -- consume 2 bytes of input
    	end
    end, "Insert digraph")

Core Events

These events are invoked from the editor core. The following functions are invoked if they are registered in the `vis.events` table. Users scripts should generally use the [Events](#events) mechanism instead which multiplexes these core events.

file_close(file)
File close. The last window displaying the file has been closed.

Parameters:

  • file File the file being closed
file_open(file)
File open.

Parameters:

  • file File the file to be opened
file_save_post(file, path)
File post save. Triggered *after* a successful write operation.

Parameters:

  • file File the file which was written
  • path string the absolute path to which it was written, `nil` if standard output
file_save_pre(file, path)
File pre save. Triggered *before* the file is being written.

Parameters:

  • file File the file being written
  • path string the absolute path to which the file will be written, `nil` if standard output

Returns:

    bool whether the write operation should be proceeded
init()
Editor initialization completed. This event is emitted immediately after `visrc.lua` has been sourced, but before any other events have occurred, in particular the command line arguments have not yet been processed.

Can be used to set *global* configuration options.

input(key)
Input key event in either input or replace mode.

Parameters:

Returns:

    bool whether the key was consumed or not
process_response(name, response_type, code, buffer)
The response received from the process started via Vis:communicate.

Parameters:

  • name string the name of process given to Vis:communicate
  • response_type string can be "STDOUT" or "STDERR" if new output was received in corresponding channel, "SIGNAL" if the process was terminated by a signal or "EXIT" when the process terminated normally
  • code int the exit code number if response_type is "EXIT", or the signal number if response_type is "SIGNAL"
  • buffer string the available content sent by the process
quit()
Editor is about to terminate.
start()
Editor startup completed. This event is emitted immediately before the main loop starts. At this point all files are loaded and corresponding windows are created. We are about to process interactive keyboard input.
term_csi(List)
CSI command received from terminal.

Parameters:

  • List of CSI parameters
win_close(win)
Window close. An window is being closed.

Parameters:

  • win Window the window being closed
win_highlight(win)
Window highlight. The window has been redrawn and the syntax highlighting needs to be performed.

Parameters:

  • win Window the window being redrawn

See also:

win_open(win)
Window open. A new window has been created.

Parameters:

  • win Window the window being opened
win_status(win)
Window status bar redraw.

Parameters:

  • win Window the affected window

See also:

Events

User scripts can subscribe Lua functions to certain events. Multiple functions can be associated with the same event. They will be called in the order they were registered. The first function which returns a non `nil` value terminates event propagation. The remaining event handler will not be called.

Keep in mind that the editor is blocked while the event handlers are being executed, avoid long running tasks.

events
Event names.

Fields:

events.emit(event, ...)
Generate event.

Invokes all event handlers in the order they were registered. Passes all arguments to the handler. The first handler which returns a non `nil` value terminates the event propagation. The other handlers will not be called.

Parameters:

  • event string the event name
  • ... ... the remaining parameters are passed on to the handler
events.subscribe(event, handler[, index])
Subscribe to an event.

Register an event handler.

Parameters:

  • event string the event name
  • handler function the event handler
  • index int the index at which to insert the handler (1 is the highest priority) (optional)

Usage:

    vis.events.subscribe(vis.events.FILE_SAVE_PRE, function(file, path)
    	-- do something useful
    	return true
    end)
events.unsubscribe(event, handler)
Unsubscribe from an event.

Remove a registered event handler.

Parameters:

  • event string the event name
  • handler function the event handler to unsubscribe

Returns:

    bool whether the handler was successfully removed
generated by LDoc 1.4.6 Last updated 2024-03-27 12:06:37