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: c0d083f
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(text, command[, fullscreen])	Pipe a string to external process and collect output.
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:style_pos(id, x, y)	Style the single terminal cell at the given coordinates, relative to this window.
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.

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.
ui_draw()	Emitted immediately before the UI is drawn to the screen.
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.

events events

Vis.input_queue

Currently unconsumed keys in the input queue.

input_queue string

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.

mark string

Vis.mode

Currently active mode.

mode modes

Vis.modes

Mode constants.

modes modes

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")

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

Parameters:

inputfd io.file the stream to be closed

Returns:

bool

io.close

Vis:command(command)

Execute a `:`-command.

Parameters:

command string the command to execute

Returns:

bool

Usage:

vis:command("set number")

Vis:command_register(name, command[, help])

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

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:

name string the name of subprocess (to distinguish processes in the process_response event)
command string the command to execute

Returns:

io.open

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

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

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

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

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

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

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

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

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])

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

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:

name string the option name

Returns:

bool

Vis:pipe(text, command[, fullscreen])

Pipe a string to external process and collect output.

The editor core will be blocked while the external process is running.

Parameters:

text string the text written to the external command
command string the command to execute
fullscreen bool whether command is a fullscreen program (e.g. curses based) (optional)

Returns:

int code the exit status of the executed command
string stdout the data written to stdout
string stderr the data written to stderr

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:

int code the exit status of the executed command
string stdout the data written to stdout
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

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

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

Returns:

the new iterator

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. Changing the value to a file path will replace the current file with a new one for the specified path.

file File

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

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)

Fields:

bytes Range file bytes, from 0, at the start and end of the viewport
lines Range file lines, from 1, at the top and bottom of the viewport
height int lines in viewport, accounting for window decoration
width int columns in viewport, accounting for window decoration

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

Parameters:

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

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

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

Usage:

win:style_define(win.STYLE_DEFAULT, "fore:red")

Window:style_pos(id, x, y)

Style the single terminal cell at the given coordinates, relative to this window.

Completely independent of the file buffer, and can be used to style UI elements, such as the status bar. The style will be cleared after every window redraw.

Parameters:

id int display style registered with style_define
x int 0-based x coordinate within Win, where (0,0) is the top left corner
y int See above

Returns:

bool

Usage:

win:style_pos(win.STYLE_COLOR_COLUMN, 0, win.height - 1)
-- Styles the first character of the status bar (or the last line, if disabled)

Window:unmap(...)

Remove a window local key mapping. The function signature is the same as for Vis:unmap.

Parameters:

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

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

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

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

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

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

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

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

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

File:mark_set(pos)

Set mark.

Parameters:

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

Returns:

Mark

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

File:text_object_longword(pos)

WORD text object.

Parameters:

pos int the position which must be part of the word

Returns:

Range

File:text_object_word(pos)

Word text object.

Parameters:

pos int the position which must be part of the word

Returns:

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

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

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

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:

key string

Returns:

bool

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

ui_draw()

Emitted immediately before the UI is drawn to the screen. Allows last-minute overrides to the styling of UI elements.

*WARNING:* This is emitted every screen draw! Use sparingly and check for `nil` values!

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

Parameters:

win Window the window being opened

win_status(win)

Window status bar redraw.

Parameters:

win Window the affected window

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:

FILE_CLOSE see file_close
FILE_OPEN see file_open
FILE_SAVE_POST see file_save_post
FILE_SAVE_PRE see file_save_pre
INIT see init
INPUT see input
QUIT see quit
START see start
WIN_CLOSE see win_close
WIN_HIGHLIGHT see win_highlight
WIN_OPEN see win_open
WIN_STATUS see win_status
TERM_CSI see term_csi
PROCESS_RESPONSE see process_response
UI_DRAW see ui_draw

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.

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

Vis Editor

Contents

Modules

Module vis

Info:

Class Vis

Fields:

See also:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Parameters:

See also:

Parameters:

Returns:

See also:

Usage:

Parameters:

Returns:

See also:

Usage:

Parameters:

Returns:

See also:

Usage:

Parameters:

Returns:

See also:

Usage:

Returns:

Usage:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Usage:

Parameters:

See also:

Parameters:

Returns:

Usage:

Parameters:

Returns:

See also:

Returns:

See also:

Usage:

Class Ui

Class Window

Module `vis`