Vis Editor API Documentation

Vis

The core Vis API.

Lifecycle

Vis *vis_new(void)

Create a new editor instance.

void vis_free(Vis*)

Free all resources associated with this editor instance, terminates UI.

int vis_run(Vis*)

Enter main loop, start processing user input.

Parameters:

vis – The editor instance.

Returns:

The editor exit status code.

void vis_exit(Vis *vis, int status)

Terminate editing session, the given status will be the return value of vis_run.

Parameters:

• vis – The editor instance.

• status – The exit status.

void vis_die(Vis *vis, const char *msg, ...)

Emergency exit, print given message, perform minimal UI cleanup and exit process.

Parameters:

• vis – The editor instance.

• msg – The message to print.

  Note

  This function does not return.

bool vis_signal_handler(Vis *vis, int signum, const siginfo_t *siginfo, const void *context)

Inform the editor core that a signal occurred.

Parameters:

• vis – The editor instance.

• signum – The signal number.

• siginfo – Pointer to siginfo_t structure.

• context – Pointer to context.

Returns:

Whether the signal was handled.

Note

Being designed as a library the editor core does not register any

signal handlers on its own. .. note:: The remaining arguments match the prototype of sa_sigaction as specified in sigaction(2).

void vis_interrupt(Vis*)

Interrupt long running operation.

Parameters:

vis – The editor instance.

Warning

There is no guarantee that a long running operation is actually

interrupted. It is analogous to cooperative multitasking where the operation has to voluntarily yield control. .. note:: It is invoked from vis_signal_handler when receiving SIGINT.

bool vis_interrupt_requested(Vis*)

Check whether interruption was requested.

Parameters:

vis – The editor instance.

Draw

void vis_draw(Vis*)

Draw user interface.

Parameters:

vis – The editor instance.

void vis_redraw(Vis*)

Completely redraw user interface.

Parameters:

vis – The editor instance.

Windows

bool vis_window_new(Vis *vis, const char *filename)

Create a new window and load the given file.

Parameters:

• vis – The editor instance.

• filename – If NULL an unnamed, empty buffer is created.

  Note

  If the given file name is already opened in another window,

  the underlying File object is shared.

bool vis_window_new_fd(Vis *vis, int fd)

Create a new window associated with a file descriptor.

Parameters:

• vis – The editor instance.

• fd – The file descriptor to associate with the window.

  Note

  No data is read from fd, but write commands without an

  explicit filename will instead write to the file descriptor.

bool vis_window_reload(Win*)

Reload the file currently displayed in the window from disk.

Parameters:

win – The window to reload.

bool vis_window_change_file(Win *win, const char *filename)

Change the file currently displayed in the window.

Parameters:

• win – The window to change.

• filename – The new file to display.

bool vis_window_closable(Win*)

Check whether closing the window would loose unsaved changes.

Parameters:

win – The window to check.

void vis_window_close(Win*)

Close window, redraw user interface.

Parameters:

win – The window to close.

bool vis_window_split(Win*)

Split the window, shares the underlying file object.

Parameters:

original – The window to split.

void vis_window_draw(Win*)

Draw a specific window.

Parameters:

win – The window to draw.

void vis_window_invalidate(Win*)

Invalidate a window, forcing a redraw.

Parameters:

win – The window to invalidate.

void vis_window_next(Vis*)

Focus next window.

Parameters:

vis – The editor instance.

void vis_window_prev(Vis*)

Focus previous window.

Parameters:

vis – The editor instance.

void vis_window_focus(Win*)

Change currently focused window, receiving user input.

Parameters:

win – The window to focus.

void vis_window_swap(Win *win1, Win *win2)

Swap location of two windows.

Parameters:

• win1 – The first window.

• win2 – The second window.

Input

The editor core processes input through a sequences of symbolic keys:

• Special keys such as <Enter>, <Tab> or <Backspace> as reported by termkey_strfkey.

  Note

  The prefixes C-, S- and M- are used to denote the Ctrl, Shift and Alt modifiers, respectively.

• Key action names as registered with vis_action_register.

  Note

  By convention they are prefixed with vis- as in <vis-nop>.

• Regular UTF-8 encoded input.

Note

An exhaustive list of the first two types is displayed in the :help output.

const char *vis_keys_next(Vis *vis, const char *keys)

Advance to the start of the next symbolic key.

Given the start of a symbolic key, returns a pointer to the start of the one immediately following it.

Parameters:

• vis – The editor instance.

• keys – The current symbolic key string.

long vis_keys_codepoint(Vis *vis, const char *keys)

Convert next symbolic key to an Unicode code point, returns -1 for unknown keys.

Parameters:

• vis – The editor instance.

• keys – The symbolic key string.

bool vis_keys_utf8(Vis *vis, const char *keys, char utf8[static UTFmax+1])

Convert next symbolic key to a UTF-8 sequence.

Parameters:

• vis – The editor instance.

• keys – The symbolic key string.

• utf8 – Buffer to store the UTF-8 sequence.

Returns:

Whether conversion was successful, if not utf8 is left unmodified.

Note

Guarantees that utf8 is NUL terminated on success.

void vis_keys_feed(Vis *vis, const char *keys)

Process symbolic keys as if they were user originated input.

Parameters:

• vis – The editor instance.

• keys – The symbolic key string to feed.

void vis_keys_handle(Vis *vis)

Handle keys from stdin.

void vis_pump_events(Vis *vis)

Process pending events from subprocesses and stdin.

Key Map

The key map is used to translate keys in non-input modes, before any key bindings are evaluated. It is intended to facilitate usage of non-latin keyboard layouts.

bool vis_keymap_add(Vis *vis, const char *key, const char *mapping)

Add a key translation.

Parameters:

• vis – The editor instance.

• key – The key to translate.

• mapping – The string to map the key to.

void vis_keymap_disable(Vis*)

Temporarily disable the keymap for the next key press.

Parameters:

vis – The editor instance.

Key Binding

Each mode has a set of key bindings. A key binding maps a key to either another key (referred to as an alias) or a key action (implementing an editor operation).

If a key sequence is ambiguous (i.e. it is a prefix of multiple mappings) more input is awaited, until a unique mapping can be resolved.

Warning

Key aliases are always evaluated recursively.

KeyBinding *vis_binding_new(Vis*)

Create a new key binding.

Parameters:

vis – The editor instance.

void vis_binding_free(Vis *vis, KeyBinding *binding)

Free a key binding.

Parameters:

• vis – The editor instance.

• binding – The key binding to free.

bool vis_mode_map(Vis *vis, enum VisMode mode, bool force, const char *key, const KeyBinding *binding)

Set up a key binding.

Parameters:

• vis – The editor instance.

• mode – The mode in which the binding applies.

• force – Whether an existing mapping should be discarded.

• key – The symbolic key to map.

• binding – The binding to map.

  Note

  binding->key is always ignored in favor of key.

bool vis_window_mode_map(Win *win, enum VisMode mode, bool force, const char *key, const KeyBinding *binding)

Analogous to vis_mode_map, but window specific.

Parameters:

• win – The window for the mapping.

• mode – The mode in which the binding applies.

• force – Whether an existing mapping should be discarded.

• key – The symbolic key to map.

• binding – The binding to map.

bool vis_mode_unmap(Vis *vis, enum VisMode mode, const char *key)

Unmap a symbolic key in a given mode.

Parameters:

• vis – The editor instance.

• mode – The mode from which to unmap.

• key – The symbolic key to unmap.

bool vis_window_mode_unmap(Win *win, enum VisMode mode, const char *key)

Analogous to vis_mode_unmap, but window specific.

Parameters:

• win – The window from which to unmap.

• mode – The mode from which to unmap.

• key – The symbolic key to unmap.

Key Action

A key action is invoked by a key binding and implements a certain editor function.

The editor operates like a finite state machine with key sequences as transition labels. Once a prefix of the input queue uniquely refers to a key action, it is invoked with the remainder of the input queue passed as argument.

Note

A triggered key action currently does not know through which key binding it was invoked. TODO: change that?

typedef const char *KeyActionFunction(Vis *vis, const char *keys, const Arg *arg)

Key action handling function.

Param vis:

The editor instance.

Param keys:

Input queue content after the binding which invoked this function.

Param arg:

Arguments for the key action.

Note

An empty string "" indicates that no further input is available.

Return:

Pointer to first non-consumed key.

Warning

Must be in range [keys, keys+strlen(keys)] or NULL to

indicate that not enough input was available. In the latter case the function will be called again once more input has been received.

KeyAction *vis_action_new(Vis *vis, const char *name, const char *help, KeyActionFunction *func, Arg arg)

Create new key action.

Parameters:

• vis – The editor instance.

• name – The name to be used as symbolic key when registering.

• help – Optional single line help text.

• func – The function implementing the key action logic.

• arg – Argument passed to function.

void vis_action_free(Vis *vis, KeyAction *action)

Free a key action.

Parameters:

• vis – The editor instance.

• action – The key action to free.

bool vis_action_register(Vis *vis, const KeyAction *keyaction)

Register key action.

Parameters:

• vis – The editor instance.

• keyaction – The key action to register.

  Note

  Makes the key action available under the pseudo key name specified

  in keyaction->name.

Modes

A mode defines enter, leave and idle actions and captures a set of key bindings.

Modes are hierarchical, key bindings are searched recursively towards the top of the hierarchy stopping at the first match.

enum VisMode

Mode specifiers.

Values:

enumerator VIS_MODE_NORMAL

enumerator VIS_MODE_OPERATOR_PENDING

enumerator VIS_MODE_VISUAL

enumerator VIS_MODE_VISUAL_LINE

Sub mode of VIS_MODE_VISUAL.

enumerator VIS_MODE_INSERT

enumerator VIS_MODE_REPLACE

Sub mode of VIS_MODE_INSERT.

enumerator VIS_MODE_INVALID

enum VisMode

Mode specifiers.

Values:

enumerator VIS_MODE_NORMAL

enumerator VIS_MODE_OPERATOR_PENDING

enumerator VIS_MODE_VISUAL

enumerator VIS_MODE_VISUAL_LINE

Sub mode of VIS_MODE_VISUAL.

enumerator VIS_MODE_INSERT

enumerator VIS_MODE_REPLACE

Sub mode of VIS_MODE_INSERT.

enumerator VIS_MODE_INVALID

void vis_mode_switch(Vis *vis, enum VisMode mode)

Switch mode.

Parameters:

• vis – The editor instance.

• mode – The mode to switch to.

  Note

  Will first trigger the leave event of the currently active

  mode, followed by an enter event of the new mode. No events are emitted, if the specified mode is already active.

enum VisMode vis_mode_from(Vis *vis, const char *name)

Translate human readable mode name to constant.

Parameters:

• vis – The editor instance.

• name – The name of the mode.

Count

Dictates how many times a motion or text object is evaluated. If none is specified, a minimal count of 1 is assumed.

void vis_shell_set(Vis *vis, const char *new_shell)

Set the shell.

Parameters:

• vis – The editor instance.

• new_shell – The new shell to set.

VisCountIterator vis_count_iterator_get(Vis *vis, int def)

Get iterator initialized with current count or def if not specified.

Parameters:

• vis – The editor instance.

• def – The default count if none is specified.

VisCountIterator vis_count_iterator_init(Vis *vis, int count)

Get iterator initialized with a count value.

Parameters:

• vis – The editor instance.

• count – The count value to initialize with.

bool vis_count_iterator_next(VisCountIterator *iter)

Increment iterator counter.

Parameters:

iter – Pointer to the iterator.

Returns:

Whether iteration should continue.

Note

Terminates iteration if the editor was

interrupted in the meantime.

VIS_COUNT_UNKNOWN

No count was specified.

VIS_COUNT_DEFAULT(count, def)

VIS_COUNT_NORMALIZE(count)

struct VisCountIterator

#include <vis.h>

Operators

enum VisOperator

Operator specifiers.

Values:

enumerator VIS_OP_DELETE

enumerator VIS_OP_CHANGE

enumerator VIS_OP_YANK

enumerator VIS_OP_PUT_AFTER

enumerator VIS_OP_SHIFT_RIGHT

enumerator VIS_OP_SHIFT_LEFT

enumerator VIS_OP_JOIN

enumerator VIS_OP_MODESWITCH

enumerator VIS_OP_REPLACE

enumerator VIS_OP_CURSOR_SOL

enumerator VIS_OP_INVALID

enumerator VIS_OP_CURSOR_EOL

enumerator VIS_OP_PUT_AFTER_END

enumerator VIS_OP_PUT_BEFORE

enumerator VIS_OP_PUT_BEFORE_END

enumerator VIS_OP_LAST

typedef size_t VisOperatorFunction(Vis *vis, Text *text, OperatorContext *context)

An operator performs a certain function on a given text range.

Param vis:

The editor instance.

Param text:

The text buffer to operate on.

Param context:

Operator-specific context.

Note

The operator must return the new cursor position or EPOS if

the cursor should be disposed. .. note:: The last used operator can be repeated using vis_repeat.

int vis_operator_register(Vis *vis, VisOperatorFunction *func, void *context)

Register an operator.

Parameters:

• vis – The editor instance.

• func – The function implementing the operator logic.

• context – User-supplied context for the operator.

Returns:

Operator ID. Negative values indicate an error, positive ones can be used with vis_operator.

bool vis_operator(Vis *vis, enum VisOperator op, ...)

Set operator to execute.

Has immediate effect if:

• A visual mode is active.

• The same operator was already set (range will be the current line).

Otherwise the operator will be executed on the range determined by:

• A motion (see vis_motion).

• A text object (vis_textobject).

The expected varying arguments are:

• VIS_OP_JOIN a char pointer referring to the text to insert between lines.

• VIS_OP_MODESWITCH an enum VisMode indicating the mode to switch to.

• VIS_OP_REPLACE a char pointer referring to the replacement character.

Parameters:

• vis – The editor instance.

• op – The operator to perform.

• ... – Additional arguments depending on the operator type.

void vis_repeat(Vis*)

Repeat last operator, possibly with a new count if one was provided in the meantime.

Parameters:

vis – The editor instance.

void vis_cancel(Vis*)

Cancel pending operator, reset count, motion, text object, register etc.

Parameters:

vis – The editor instance.

Motions

enum VisMotion

Motion specifiers.

Values:

enumerator VIS_MOVE_LINE_DOWN

enumerator VIS_MOVE_LINE_UP

enumerator VIS_MOVE_SCREEN_LINE_UP

enumerator VIS_MOVE_SCREEN_LINE_DOWN

enumerator VIS_MOVE_SCREEN_LINE_BEGIN

enumerator VIS_MOVE_SCREEN_LINE_MIDDLE

enumerator VIS_MOVE_SCREEN_LINE_END

enumerator VIS_MOVE_LINE_PREV

enumerator VIS_MOVE_LINE_BEGIN

enumerator VIS_MOVE_LINE_START

enumerator VIS_MOVE_LINE_FINISH

enumerator VIS_MOVE_LINE_LASTCHAR

enumerator VIS_MOVE_LINE_END

enumerator VIS_MOVE_LINE_NEXT

enumerator VIS_MOVE_LINE

enumerator VIS_MOVE_COLUMN

enumerator VIS_MOVE_CHAR_PREV

enumerator VIS_MOVE_CHAR_NEXT

enumerator VIS_MOVE_LINE_CHAR_PREV

enumerator VIS_MOVE_LINE_CHAR_NEXT

enumerator VIS_MOVE_CODEPOINT_PREV

enumerator VIS_MOVE_CODEPOINT_NEXT

enumerator VIS_MOVE_WORD_NEXT

enumerator VIS_MOVE_WORD_START_NEXT

enumerator VIS_MOVE_WORD_END_PREV

enumerator VIS_MOVE_WORD_END_NEXT

enumerator VIS_MOVE_WORD_START_PREV

enumerator VIS_MOVE_LONGWORD_NEXT

enumerator VIS_MOVE_LONGWORD_START_PREV

enumerator VIS_MOVE_LONGWORD_START_NEXT

enumerator VIS_MOVE_LONGWORD_END_PREV

enumerator VIS_MOVE_LONGWORD_END_NEXT

enumerator VIS_MOVE_SENTENCE_PREV

enumerator VIS_MOVE_SENTENCE_NEXT

enumerator VIS_MOVE_PARAGRAPH_PREV

enumerator VIS_MOVE_PARAGRAPH_NEXT

enumerator VIS_MOVE_FUNCTION_START_PREV

enumerator VIS_MOVE_FUNCTION_START_NEXT

enumerator VIS_MOVE_FUNCTION_END_PREV

enumerator VIS_MOVE_FUNCTION_END_NEXT

enumerator VIS_MOVE_BLOCK_START

enumerator VIS_MOVE_BLOCK_END

enumerator VIS_MOVE_PARENTHESIS_START

enumerator VIS_MOVE_PARENTHESIS_END

enumerator VIS_MOVE_BRACKET_MATCH

enumerator VIS_MOVE_TO_LEFT

enumerator VIS_MOVE_TO_RIGHT

enumerator VIS_MOVE_TO_LINE_LEFT

enumerator VIS_MOVE_TO_LINE_RIGHT

enumerator VIS_MOVE_TILL_LEFT

enumerator VIS_MOVE_TILL_RIGHT

enumerator VIS_MOVE_TILL_LINE_LEFT

enumerator VIS_MOVE_TILL_LINE_RIGHT

enumerator VIS_MOVE_FILE_BEGIN

enumerator VIS_MOVE_FILE_END

enumerator VIS_MOVE_SEARCH_WORD_FORWARD

enumerator VIS_MOVE_SEARCH_WORD_BACKWARD

enumerator VIS_MOVE_SEARCH_REPEAT_FORWARD

enumerator VIS_MOVE_SEARCH_REPEAT_BACKWARD

enumerator VIS_MOVE_WINDOW_LINE_TOP

enumerator VIS_MOVE_WINDOW_LINE_MIDDLE

enumerator VIS_MOVE_WINDOW_LINE_BOTTOM

enumerator VIS_MOVE_CHANGELIST_NEXT

enumerator VIS_MOVE_CHANGELIST_PREV

enumerator VIS_MOVE_NOP

enumerator VIS_MOVE_PERCENT

enumerator VIS_MOVE_BYTE

enumerator VIS_MOVE_BYTE_LEFT

enumerator VIS_MOVE_BYTE_RIGHT

enumerator VIS_MOVE_INVALID

enumerator VIS_MOVE_TOTILL_REPEAT

enumerator VIS_MOVE_TOTILL_REVERSE

enumerator VIS_MOVE_SEARCH_FORWARD

enumerator VIS_MOVE_SEARCH_BACKWARD

enumerator VIS_MOVE_SEARCH_REPEAT

enumerator VIS_MOVE_SEARCH_REPEAT_REVERSE

enumerator VIS_MOVE_LAST

enum VisMotionType

Values:

enumerator VIS_MOTIONTYPE_LINEWISE

enumerator VIS_MOTIONTYPE_CHARWISE

typedef size_t VisMotionFunction(Vis *vis, Win *win, void *context, size_t pos)

Motions take a starting position and transform it to an end position.

Param vis:

The editor instance.

Param win:

The window in which the motion is performed.

Param context:

User-supplied context for the motion.

Param pos:

The starting position.

Note

Should a motion not be possible, the original position must be returned.

TODO: we might want to change that to EPOS?

bool vis_motion(Vis *vis, enum VisMotion motion, ...)

Set motion to perform.

The following motions take an additional argument:

• VIS_MOVE_SEARCH_FORWARD and VIS_MOVE_SEARCH_BACKWARD

The search pattern as const char *.

• VIS_MOVE_{LEFT,RIGHT}_{TO,TILL}

The character to search for as const char *.

Parameters:

• vis – The editor instance.

• motion – The motion to perform.

• ... – Additional arguments depending on the motion type.

void vis_motion_type(Vis *vis, enum VisMotionType type)

Force currently specified motion to behave in line or character wise mode.

Parameters:

• vis – The editor instance.

• type – The motion type (line-wise or character-wise).

int vis_motion_register(Vis *vis, void *context, VisMotionFunction *func)

Register a motion function.

Parameters:

• vis – The editor instance.

• context – User-supplied context for the motion.

• func – The function implementing the motion logic.

Returns:

Motion ID. Negative values indicate an error, positive ones can be used with vis_motion.

Text Objects

enum VisTextObject

Text object specifier.

Values:

enumerator VIS_TEXTOBJECT_INNER_WORD

enumerator VIS_TEXTOBJECT_OUTER_WORD

enumerator VIS_TEXTOBJECT_INNER_LONGWORD

enumerator VIS_TEXTOBJECT_OUTER_LONGWORD

enumerator VIS_TEXTOBJECT_SENTENCE

enumerator VIS_TEXTOBJECT_PARAGRAPH

enumerator VIS_TEXTOBJECT_PARAGRAPH_OUTER

enumerator VIS_TEXTOBJECT_OUTER_SQUARE_BRACKET

enumerator VIS_TEXTOBJECT_INNER_SQUARE_BRACKET

enumerator VIS_TEXTOBJECT_OUTER_CURLY_BRACKET

enumerator VIS_TEXTOBJECT_INNER_CURLY_BRACKET

enumerator VIS_TEXTOBJECT_OUTER_ANGLE_BRACKET

enumerator VIS_TEXTOBJECT_INNER_ANGLE_BRACKET

enumerator VIS_TEXTOBJECT_OUTER_PARENTHESIS

enumerator VIS_TEXTOBJECT_INNER_PARENTHESIS

enumerator VIS_TEXTOBJECT_OUTER_QUOTE

enumerator VIS_TEXTOBJECT_INNER_QUOTE

enumerator VIS_TEXTOBJECT_OUTER_SINGLE_QUOTE

enumerator VIS_TEXTOBJECT_INNER_SINGLE_QUOTE

enumerator VIS_TEXTOBJECT_OUTER_BACKTICK

enumerator VIS_TEXTOBJECT_INNER_BACKTICK

enumerator VIS_TEXTOBJECT_OUTER_LINE

enumerator VIS_TEXTOBJECT_INNER_LINE

enumerator VIS_TEXTOBJECT_INDENTATION

enumerator VIS_TEXTOBJECT_SEARCH_FORWARD

enumerator VIS_TEXTOBJECT_SEARCH_BACKWARD

enumerator VIS_TEXTOBJECT_INVALID

typedef Filerange VisTextObjectFunction(Vis *vis, Win *win, void *context, size_t pos)

Text objects take a starting position and return a text range.

Param vis:

The editor instance.

Param win:

The window in which the text object is applied.

Param context:

User-supplied context for the text object.

Param pos:

The starting position.

Note

The originating position does not necessarily have to be contained in

the resulting range.

int vis_textobject_register(Vis *vis, int type, void *data, VisTextObjectFunction *func)

Register a new text object.

Parameters:

• vis – The editor instance.

• type – The type of the text object.

• data – User-supplied data for the text object.

• func – The function implementing the text object logic.

Returns:

Text object ID. Negative values indicate an error, positive ones can be used with vis_textobject.

bool vis_textobject(Vis *vis, enum VisTextObject textobj)

Set text object to use.

Parameters:

• vis – The editor instance.

• textobj – The text object to set.

Marks

Marks keep track of a given text position.

Note

Marks are currently file local.

enum VisMark

Mark specifiers.

Values:

enumerator VIS_MARK_DEFAULT

enumerator VIS_MARK_SELECTION

enumerator VIS_MARK_a

enumerator VIS_MARK_b

enumerator VIS_MARK_c

enumerator VIS_MARK_d

enumerator VIS_MARK_e

enumerator VIS_MARK_f

enumerator VIS_MARK_g

enumerator VIS_MARK_h

enumerator VIS_MARK_i

enumerator VIS_MARK_j

enumerator VIS_MARK_k

enumerator VIS_MARK_l

enumerator VIS_MARK_m

enumerator VIS_MARK_n

enumerator VIS_MARK_o

enumerator VIS_MARK_p

enumerator VIS_MARK_q

enumerator VIS_MARK_r

enumerator VIS_MARK_s

enumerator VIS_MARK_t

enumerator VIS_MARK_u

enumerator VIS_MARK_v

enumerator VIS_MARK_w

enumerator VIS_MARK_x

enumerator VIS_MARK_y

enumerator VIS_MARK_z

enumerator VIS_MARK_INVALID

enum VisMark vis_mark_from(Vis *vis, char mark)

Translate between single character mark name and corresponding constant.

Parameters:

• vis – The editor instance.

• mark – The character representing the mark.

char vis_mark_to(Vis *vis, enum VisMark mark)

Translate between mark constant and single character mark name.

Parameters:

• vis – The editor instance.

• mark – The mark constant.

void vis_mark(Vis *vis, enum VisMark mark)

Specify mark to use.

Parameters:

• vis – The editor instance.

• mark – The mark to use.

  Note

  If none is specified VIS_MARK_DEFAULT will be used.

enum VisMark vis_mark_used(Vis*)

Get the currently used mark.

Parameters:

vis – The editor instance.

void vis_mark_set(Win *win, enum VisMark id, Array *sel)

Store a set of Fileranges in a mark.

Parameters:

• win – The window whose selections to store.

• id – The mark ID to use.

• sel – The array containing the file ranges.

Array vis_mark_get(Win *win, enum VisMark id)

Get an array of file ranges stored in the mark.

Parameters:

• win – The window whose mark to retrieve.

• id – The mark ID to retrieve.

Returns:

An array of file ranges.

Warning

The caller must eventually free the Array by calling

array_release.

void vis_mark_normalize(Array *array)

Normalize an Array of Fileranges.

Removes invalid ranges, merges overlapping ones and sorts according to the start position.

Parameters:

array – The array of file ranges to normalize.

bool vis_jumplist_save(Vis*)

Add selections of focused window to jump list.

Parameters:

vis – The editor instance.

bool vis_jumplist_prev(Vis*)

Navigate jump list backwards.

Parameters:

vis – The editor instance.

bool vis_jumplist_next(Vis*)

Navigate jump list forwards.

Parameters:

vis – The editor instance.

Registers

enum VisRegister

Register specifiers.

Values:

enumerator VIS_REG_DEFAULT

enumerator VIS_REG_ZERO

enumerator VIS_REG_AMPERSAND

enumerator VIS_REG_1

enumerator VIS_REG_2

enumerator VIS_REG_3

enumerator VIS_REG_4

enumerator VIS_REG_5

enumerator VIS_REG_6

enumerator VIS_REG_7

enumerator VIS_REG_8

enumerator VIS_REG_9

enumerator VIS_REG_BLACKHOLE

enumerator VIS_REG_CLIPBOARD

enumerator VIS_REG_PRIMARY

enumerator VIS_REG_DOT

enumerator VIS_REG_SEARCH

enumerator VIS_REG_COMMAND

enumerator VIS_REG_SHELL

enumerator VIS_REG_NUMBER

enumerator VIS_REG_a

enumerator VIS_REG_b

enumerator VIS_REG_c

enumerator VIS_REG_d

enumerator VIS_REG_e

enumerator VIS_REG_f

enumerator VIS_REG_g

enumerator VIS_REG_h

enumerator VIS_REG_i

enumerator VIS_REG_j

enumerator VIS_REG_k

enumerator VIS_REG_l

enumerator VIS_REG_m

enumerator VIS_REG_n

enumerator VIS_REG_o

enumerator VIS_REG_p

enumerator VIS_REG_q

enumerator VIS_REG_r

enumerator VIS_REG_s

enumerator VIS_REG_t

enumerator VIS_REG_u

enumerator VIS_REG_v

enumerator VIS_REG_w

enumerator VIS_REG_x

enumerator VIS_REG_y

enumerator VIS_REG_z

enumerator VIS_MACRO_OPERATOR

enumerator VIS_REG_PROMPT

enumerator VIS_REG_INVALID

enumerator VIS_REG_A

enumerator VIS_REG_B

enumerator VIS_REG_C

enumerator VIS_REG_D

enumerator VIS_REG_E

enumerator VIS_REG_F

enumerator VIS_REG_G

enumerator VIS_REG_H

enumerator VIS_REG_I

enumerator VIS_REG_J

enumerator VIS_REG_K

enumerator VIS_REG_L

enumerator VIS_REG_M

enumerator VIS_REG_N

enumerator VIS_REG_O

enumerator VIS_REG_P

enumerator VIS_REG_Q

enumerator VIS_REG_R

enumerator VIS_REG_S

enumerator VIS_REG_T

enumerator VIS_REG_U

enumerator VIS_REG_V

enumerator VIS_REG_W

enumerator VIS_REG_X

enumerator VIS_REG_Y

enumerator VIS_REG_Z

enumerator VIS_MACRO_LAST_RECORDED

enum VisRegister vis_register_from(Vis *vis, char reg)

Translate between single character register name and corresponding constant.

Parameters:

• vis – The editor instance.

• reg – The character representing the register.

char vis_register_to(Vis *vis, enum VisRegister reg)

Translate between register constant and single character register name.

Parameters:

• vis – The editor instance.

• reg – The register constant.

void vis_register(Vis *vis, enum VisRegister reg)

Specify register to use.

Parameters:

• vis – The editor instance.

• reg – The register to use.

  Note

  If none is specified VIS_REG_DEFAULT will be used.

enum VisRegister vis_register_used(Vis*)

Get the currently used register.

Parameters:

vis – The editor instance.

Array vis_register_get(Vis *vis, enum VisRegister id)

Get register content.

Parameters:

• vis – The editor instance.

• id – The register ID to retrieve.

Returns:

An array of TextString structs.

Warning

The caller must eventually free the array resources using

array_release.

bool vis_register_set(Vis *vis, enum VisRegister id, Array *data)

Set register content.

Parameters:

• vis – The editor instance.

• id – The register ID to set.

• data – The array comprised of TextString structs.

Macros

Macros are a sequence of keys stored in a Register which can be reprocessed as if entered by the user.

Warning

Macro support is currently half-baked. If you do something stupid (e.g. use mutually recursive macros), you will likely encounter stack overflows.

bool vis_macro_record(Vis *vis, enum VisRegister reg)

Start recording a macro.

Parameters:

• vis – The editor instance.

• reg – The register to record the macro into.

  Note

  Fails if a recording is already ongoing.

bool vis_macro_record_stop(Vis*)

Stop recording, fails if there is nothing to stop.

Parameters:

vis – The editor instance.

bool vis_macro_recording(Vis*)

Check whether a recording is currently ongoing.

Parameters:

vis – The editor instance.

bool vis_macro_replay(Vis *vis, enum VisRegister reg)

Replay a macro.

Parameters:

• vis – The editor instance.

• reg – The register containing the macro to replay.

  Note

  A macro currently being recorded can not be replayed.

Commands

typedef bool VisCommandFunction(Vis*, Win*, void *data, bool force, const char *argv[], Selection*, Filerange*)

Command handler function.

bool vis_cmd(Vis *vis, const char *cmd)

Execute a :-command.

Parameters:

• vis – The editor instance.

• cmd – The command string to execute.

bool vis_cmd_register(Vis *vis, const char *name, const char *help, void *context, VisCommandFunction *func)

Register new :-command.

Parameters:

• vis – The editor instance.

• name – The command name.

• help – Optional single line help text.

• context – User supplied context pointer passed to the handler function.

• func – The function implementing the command logic.

  Note

  Any unique prefix of the command name will invoke the command.

bool vis_cmd_unregister(Vis *vis, const char *name)

Unregister :-command.

Parameters:

• vis – The editor instance.

• name – The name of the command to unregister.

Options

enum VisOption

Option properties.

Values:

enumerator VIS_OPTION_TYPE_BOOL

enumerator VIS_OPTION_TYPE_STRING

enumerator VIS_OPTION_TYPE_NUMBER

enumerator VIS_OPTION_VALUE_OPTIONAL

enumerator VIS_OPTION_NEED_WINDOW

enumerator VIS_OPTION_DEPRECATED

typedef bool VisOptionFunction(Vis *vis, Win *win, void *context, bool force, enum VisOption option_flags, const char *name, Arg *value)

Option handler function.

Param vis:

The editor instance.

Param win:

The window to which option should apply, might be NULL.

Param context:

User provided context pointer as given to vis_option_register.

Param force:

Whether the option was specified with a bang !.

Param option_flags:

The applicable option flags.

Param name:

Name of option which was set.

Param value:

The new option value.

bool vis_option_register(Vis *vis, const char *names[], enum VisOption option_flags, VisOptionFunction *func, void *context, const char *help)

Register a new :set option.

Parameters:

• vis – The editor instance.

• names – A NULL terminated array of option names.

• option_flags – The applicable option flags.

• func – The function handling the option.

• context – User supplied context pointer passed to the handler function.

• help – Optional single line help text.

  Note

  Fails if any of the given option names is already registered.

bool vis_option_unregister(Vis *vis, const char *name)

Unregister an existing :set option.

Parameters:

• vis – The editor instance.

• name – The name of the option to unregister.

  Note

  Also unregisters all aliases as given to vis_option_register.

bool vis_prompt_cmd(Vis *vis, const char *cmd)

Execute any kind (:, ?, /) of prompt command.

Parameters:

• vis – The editor instance.

• cmd – The command string.

void vis_print_cmds(Vis*, Buffer *buf)

Write newline separated list of available commands to buf.

Parameters:

• vis – The editor instance.

• buf – The buffer to write to.

int vis_pipe(Vis *vis, File *file, Filerange *range, const char *argv[], void *stdout_context, ssize_t (*read_stdout)(void *stdout_context, char *data, size_t len), void *stderr_context, ssize_t (*read_stderr)(void *stderr_context, char *data, size_t len), bool fullscreen)

Pipe a given file range to an external process.

If the range is invalid ‘interactive’ mode is enabled, meaning that stdin and stderr are passed through the underlying command, stdout points to vis’ stderr.

If argv contains only one non-NULL element the command is executed through an intermediate shell (using /bin/sh -c argv[0]) that is argument expansion is performed by the shell. Otherwise the argument list will be passed unmodified to execvp(argv[0], argv).

If the read_stdout and read_stderr callbacks are non-NULL they will be invoked when output from the forked process is available.

If fullscreen is set to true the external process is assumed to be a fullscreen program (e.g. curses based) and the ui context is restored accordingly.

Warning

The editor core is blocked until this function returns.

Parameters:

• vis – The editor instance.

• file – The file to pipe.

• range – The file range to pipe.

• argv – Argument list, must be NULL terminated.

• stdout_context – Context for stdout callback.

• read_stdout – Callback for stdout data.

• stderr_context – Context for stderr callback.

• read_stderr – Callback for stderr data.

• fullscreen – Whether the external process is a fullscreen program (e.g. curses based)

Returns:

The exit status of the forked process.

int vis_pipe_collect(Vis *vis, File *file, Filerange *range, const char *argv[], char **out, char **err, bool fullscreen)

Pipe a Filerange to an external process, return its exit status and capture everything that is written to stdout/stderr.

Parameters:

• vis – The editor instance.

• file – The file to pipe.

• range – The file range to pipe.

• argv – Argument list, must be NULL terminated.

• out – Data written to stdout, will be NUL terminated.

• err – Data written to stderr, will be NUL terminated.

• fullscreen – Whether the external process is a fullscreen program (e.g. curses based)

  Warning

  The pointers stored in out and err need to be free(3)-ed

  by the caller.

int vis_pipe_buf_collect(Vis *vis, const char *buf, const char *argv[], char **out, char **err, bool fullscreen)

Pipe a buffer to an external process, return its exit status and capture everything that is written to stdout/stderr.

Parameters:

• vis – The editor instance.

• buf – The buffer to pipe.

• argv – Argument list, must be NULL terminated.

• out – Data written to stdout, will be NUL terminated.

• err – Data written to stderr, will be NUL terminated.

• fullscreen – Whether the external process is a fullscreen program (e.g. curses based)

  Warning

  The pointers stored in out and err need to be free(3)-ed

  by the caller.

Modification

These function operate on the currently focused window but ensure that all windows which show the affected region are redrawn too.

void vis_insert(Vis *vis, size_t pos, const char *data, size_t len)

Insert data into the file.

Parameters:

• vis – The editor instance.

• pos – The position to insert at.

• data – The data to insert.

• len – The length of the data to insert.

void vis_delete(Vis *vis, size_t pos, size_t len)

Delete data from the file.

Parameters:

• vis – The editor instance.

• pos – The starting position of the deletion.

• len – The length of the data to delete.

void vis_replace(Vis *vis, size_t pos, const char *data, size_t len)

Replace data in the file.

Parameters:

• vis – The editor instance.

• pos – The position to replace at.

• data – The new data.

• len – The length of the new data.

void vis_insert_key(Vis *vis, const char *data, size_t len)

Perform insertion at all cursor positions.

Parameters:

• vis – The editor instance.

• data – The data to insert.

• len – The length of the data.

void vis_replace_key(Vis *vis, const char *data, size_t len)

Perform character substitution at all cursor positions.

Parameters:

• vis – The editor instance.

• data – The character data to substitute.

• len – The length of the data.

  Note

  Does not replace new line characters.

void vis_insert_tab(Vis*)

Insert a tab at all cursor positions.

Parameters:

vis – The editor instance.

Note

Performs tab expansion according to current settings.

void vis_insert_nl(Vis*)

Inserts a new line character at every cursor position.

Parameters:

vis – The editor instance.

Note

Performs auto indentation according to current settings.

Interaction

void vis_prompt_show(Vis *vis, const char *title)

Display a user prompt with a certain title.

Parameters:

• vis – The editor instance.

• title – The title of the prompt.

  Note

  The prompt is currently implemented as a single line height window.

void vis_info_show(Vis *vis, const char *msg, ...)

Display a single line message.

Parameters:

• vis – The editor instance.

• msg – The message to display.

  Note

  The message will automatically be hidden upon next input.

void vis_message_show(Vis *vis, const char *msg)

Display arbitrary long message in a dedicated window.

Parameters:

• vis – The editor instance.

• msg – The message to display.

Miscellaneous

Regex *vis_regex(Vis *vis, const char *pattern)

Get a regex object matching pattern.

Parameters:

• vis – The editor instance.

• pattern – The regex pattern to compile, if NULL the most recently used one is substituted.

Returns:

A Regex object or NULL in case of an error.

Warning

The caller must free the regex object using text_regex_free.

void vis_file_snapshot(Vis *vis, File *file)

Take an undo snapshot to which we can later revert.

Parameters:

• vis – The editor instance.

• file – The file for which to take a snapshot.

  Note

  Does nothing when invoked while replaying a macro.

Text

The core text management data structure which supports efficient modifications and provides a byte string interface. Text positions are represented as size_t. Valid addresses are in range [0, text_size(txt)]. An invalid position is denoted by EPOS. Access to the non-contigiuos pieces is available by means of an iterator interface or a copy mechanism. Text revisions are tracked in an history graph.

Note

The text is assumed to be encoded in UTF-8.

Load

enum TextLoadMethod

Method used to load existing file content.

Values:

enumerator TEXT_LOAD_AUTO

Automatically chose best option.

enumerator TEXT_LOAD_READ

Read file content and copy it to an in-memory buffer.

Subsequent changes to the underlying file will have no effect on this text instance.

Note

Load time is linear in the file size.

enumerator TEXT_LOAD_MMAP

Memory map the file from disk.

Use file system / virtual memory subsystem as a caching layer.

Note

Load time is (almost) independent of the file size.

Warning

Inplace modifications of the underlying file will be reflected in the current text content. In particular, truncation will raise SIGBUS and result in data loss.

Text *text_load(const char *filename)

Create a text instance populated with the given file content.

Note

Equivalent to text_load_method(filename, TEXT_LOAD_AUTO).

Text *text_load_method(const char *filename, enum TextLoadMethod method)

Create a text instance populated with the given file content.

Parameters:

• filename – The name of the file to load, if NULL an empty text is created.

• method – How the file content should be loaded.

Returns:

The new Text object or NULL in case of an error.

Note

When attempting to load a non-regular file, errno will be set to:

• EISDIR for a directory.

• ENOTSUP otherwise.

Text *text_loadat_method(int dirfd, const char *filename, enum TextLoadMethod)

void text_free(Text*)

Release all resources associated with this text instance.

State

size_t text_size(const Text*)

Return the size in bytes of the whole text.

struct stat text_stat(const Text*)

Get file information at time of load or last save, whichever happened more recently.

Note

If an empty text instance was created using text_load(NULL) and it has not yet been saved, an all zero struct stat will be returned.

Returns:

See stat(2) for details.

bool text_modified(const Text*)

Query whether the text contains any unsaved modifications.

Modify

bool text_insert(Text *txt, size_t pos, const char *data, size_t len)

Insert data at the given byte position.

Parameters:

• txt – The text instance to modify.

• pos – The absolute byte position.

• data – The data to insert.

• len – The length of the data in bytes.

Returns:

Whether the insertion succeeded.

bool text_delete(Text *txt, size_t pos, size_t len)

Delete data at given byte position.

Parameters:

• txt – The text instance to modify.

• pos – The absolute byte position.

• len – The number of bytes to delete, starting from pos.

Returns:

Whether the deletion succeeded.

bool text_delete_range(Text *txt, const Filerange*)

bool text_printf(Text *txt, size_t pos, const char *format, ...)

bool text_appendf(Text *txt, const char *format, ...)

Access

The individual pieces of the text are not necessarily stored in a contiguous memory block. These functions perform a copy to such a region.

bool text_byte_get(const Text *txt, size_t pos, char *byte)

Get byte stored at pos.

Parameters:

• txt – The text instance to modify.

• pos – The absolute position.

• byte – Destination address to store the byte.

Returns:

Whether pos was valid and byte updated accordingly.

Note

Unlike text_iterator_byte_get() this function does not return an artificial NUL byte at EOF.

size_t text_bytes_get(const Text *txt, size_t pos, size_t len, char *buf)

Store at most len bytes starting from pos into buf.

Parameters:

• txt – The text instance to modify.

• pos – The absolute starting position.

• len – The length in bytes.

• buf – The destination buffer.

Returns:

The number of bytes (<= len) stored at buf.

Warning

buf will not be NUL terminated.

char *text_bytes_alloc0(const Text *txt, size_t pos, size_t len)

Fetch text range into newly allocate memory region.

Parameters:

• txt – The text instance to modify.

• pos – The absolute starting position.

• len – The length in bytes.

Returns:

A contiguous NUL terminated buffer holding the requested range, or NULL in error case.

Warning

The returned pointer must be freed by the caller.

Iterator

An iterator points to a given text position and provides interfaces to adjust said position or read the underlying byte value. Functions which take a char pointer will generally assign the byte value after the iterator was updated.

struct Iterator

Iterator used to navigate the buffer content.

Captures the position within a Piece.

Note

Should be treated as an opaque type.

Warning

Any change to the Text will invalidate the iterator state.

Iterator text_iterator_get(const Text*, size_t pos)

bool text_iterator_init(const Text*, Iterator*, size_t pos)

const Text *text_iterator_text(const Iterator*)

bool text_iterator_valid(const Iterator*)

bool text_iterator_has_next(const Iterator*)

bool text_iterator_has_prev(const Iterator*)

bool text_iterator_next(Iterator*)

bool text_iterator_prev(Iterator*)

Byte

Note

For a read attempt at EOF (i.e. text_size) an artificial NUL byte which is not actually part of the file is returned.

bool text_iterator_byte_get(const Iterator*, char *b)

bool text_iterator_byte_prev(Iterator*, char *b)

bool text_iterator_byte_next(Iterator*, char *b)

bool text_iterator_byte_find_prev(Iterator*, char b)

bool text_iterator_byte_find_next(Iterator*, char b)

Codepoint

These functions advance to the next/previous leading byte of an UTF-8 encoded Unicode codepoint by skipping over all continuation bytes of the form 10xxxxxx.

bool text_iterator_codepoint_next(Iterator *it, char *c)

bool text_iterator_codepoint_prev(Iterator *it, char *c)

Grapheme Clusters

These functions advance to the next/previous grapheme cluster.

Note

The grapheme cluster boundaries are currently not implemented according to UAX#29 rules. Instead a base character followed by arbitrarily many combining character as reported by wcwidth(3) are skipped.

bool text_iterator_char_next(Iterator*, char *c)

bool text_iterator_char_prev(Iterator*, char *c)

Lines

Translate between 1 based line numbers and 0 based byte offsets.

size_t text_pos_by_lineno(Text*, size_t lineno)

size_t text_lineno_by_pos(Text*, size_t pos)

History

Interfaces to the history graph.

bool text_snapshot(Text*)

Create a text snapshot, that is a vertex in the history graph.

size_t text_undo(Text*)

Revert to previous snapshot along the main branch.

Note

Takes an implicit snapshot.

Returns:

The position of the first change or EPOS, if already at the oldest state i.e. there was nothing to undo.

size_t text_redo(Text*)

Reapply an older change along the main branch.

Note

Takes an implicit snapshot.

Returns:

The position of the first change or EPOS, if already at the newest state i.e. there was nothing to redo.

size_t text_earlier(Text*)

size_t text_later(Text*)

size_t text_restore(Text*, time_t)

Restore the text to the state closest to the time given.

time_t text_state(const Text*)

Get creation time of current state.

Note

TODO: This is currently not the same as the time of the last snapshot.

Marks

A mark keeps track of a text position. Subsequent text changes will update all marks placed after the modification point. Reverting to an older text state will hide all affected marks, redoing the changes will restore them.

Warning

Due to an optimization cached modifications (i.e. no text_snapshot was performed between setting the mark and issuing the changes) might not adjust mark positions accurately.

typedef uintptr_t Mark

A mark.

EMARK

An invalid mark, lookup of which will yield EPOS.

Mark text_mark_set(Text *txt, size_t pos)

Set a mark.

Note

Setting a mark to text_size will always return the current text size upon lookup.

Parameters:

• txt – The text instance to modify.

• pos – The position at which to store the mark.

Returns:

The mark or EMARK if an invalid position was given.

size_t text_mark_get(const Text *txt, Mark mark)

Lookup a mark.

Parameters:

• txt – The text instance to modify.

• mark – The mark to look up.

Returns:

The byte position or EPOS for an invalid mark.

Save

enum TextSaveMethod

Method used to save the text.

Values:

enumerator TEXT_SAVE_AUTO

Automatically chose best option.

enumerator TEXT_SAVE_ATOMIC

Save file atomically using rename(2).

Creates a temporary file, restores all important meta data, before moving it atomically to its final (possibly already existing) destination using rename(2). For new files, permissions are set to 0666 & ~umask.

Warning

This approach does not work if:

• The file is a symbolic link.

• The file is a hard link.

• File ownership can not be preserved.

• File group can not be preserved.

• Directory permissions do not allow creation of a new file.

• POSIX ACL can not be preserved (if enabled).

• SELinux security context can not be preserved (if enabled).

enumerator TEXT_SAVE_INPLACE

Overwrite file in place.

Warning

I/O failure might cause data loss.

void text_mark_current_revision(Text*)

Marks the current text revision as saved.

bool text_save_begin(TextSave*)

Setup a sequence of write operations.

The returned TextSave pointer can be used to write multiple, possibly non-contiguous, file ranges.

Warning

For every call to text_save_begin there must be exactly one matching call to either text_save_commit or text_save_cancel to release the underlying resources.

ssize_t text_save_write_range(TextSave*, const Filerange*)

Write file range.

Returns:

The number of bytes written or -1 in case of an error.

bool text_save_commit(TextSave*)

Commit changes to disk.

Returns:

Whether changes have been saved.

Note

Releases the underlying resources and frees the given TextSave pointer which must no longer be used.

void text_save_cancel(TextSave*)

Abort a save operation.

Note

Does not guarantee to undo the previous writes (they might have been performed in-place). However, it releases the underlying resources and frees the given TextSave pointer which must no longer be used.

ssize_t text_write_range(const Text*, const Filerange*, int fd)

Write file range to file descriptor.

Returns:

The number of bytes written or -1 in case of an error.

text_save_default(...)

struct TextSave

#include <text.h>

Miscellaneous

bool text_mmaped(const Text*, const char *ptr)

Check whether ptr is part of a memory mapped region associated with this text instance.

ssize_t write_all(int fd, const char *buf, size_t count)

Write complete buffer to file descriptor.

Returns:

The number of bytes written or -1 in case of an error.

View

Provides a viewport of a text instance and manages selections.

Lifecycle

bool view_init(struct Win*, Text*)

void view_free(View*)

void view_reload(View*, Text*)

Viewport

The cursor of the primary selection is always visible.

bool view_coord_get(View *view, size_t pos, Line **line, int *row, int *col)

Get window coordinate of text position.

Parameters:

• view – The view to manipulate.

• pos – The position to query.

• line – Will be updated with screen line on which pos resides.

• row – Will be updated with zero based window row on which pos resides.

• col – Will be updated with zero based window column on which pos resides.

Returns:

Whether pos is visible. If not, the pointer arguments are left unmodified.

size_t view_screenline_goto(View*, int n)

Get position at the start of the n-th window line, counting from 1.

size_t view_slide_up(View*, int lines)

size_t view_slide_down(View*, int lines)

size_t view_scroll_up(View*, int lines)

size_t view_scroll_down(View*, int lines)

size_t view_scroll_page_up(View*)

size_t view_scroll_page_down(View*)

size_t view_scroll_halfpage_up(View*)

size_t view_scroll_halfpage_down(View*)

void view_redraw_top(View*)

void view_redraw_center(View*)

void view_redraw_bottom(View*)

void view_scroll_to(View*, size_t pos)

VIEW_VIEWPORT_GET(v)

Get the currently displayed text range.

Dimension

bool view_resize(View*, int width, int height)

Draw

void view_draw(View*)

bool view_update(View*)

Selections

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

Creation and Destruction

Selection *view_selections_new(View*, size_t pos)

Create a new singleton selection at the given position.

Note

New selections are created non-anchored.

Warning

Fails if position is already covered by a selection.

Selection *view_selections_new_force(View*, size_t pos)

Create a new selection even if position is already covered by an existing selection.

Note

This should only be used if the old selection is eventually disposed.

bool view_selections_dispose(Selection*)

Dispose an existing selection.

Warning

Not applicable for the last existing selection.

bool view_selections_dispose_force(Selection*)

Forcefully dispose an existing selection.

If called for the last existing selection, it will be reduced and marked for destruction. As soon as a new selection is created this one will be disposed.

Selection *view_selection_disposed(View*)

Query state of primary selection.

If the primary selection was marked for destruction, return it and clear destruction flag.

void view_selections_dispose_all(View*)

Dispose all but the primary selection.

void view_selections_normalize(View*)

Dispose all invalid and merge all overlapping selections.

void view_selections_set_all(View *view, Array *array, bool anchored)

Replace currently active selections.

Parameters:

• view – The view to manipulate.

• array – The array of Filerange objects.

• anchored – Whether all selection should be anchored.

Array view_selections_get_all(View*)

Get array containing a Fileranges for each selection.

Navigation

Selection *view_selections_primary_get(View*)

void view_selections_primary_set(Selection*)

Selection *view_selections(View*)

Get first selection.

Selection *view_selections_prev(Selection*)

Get immediate predecessor of selection.

Selection *view_selections_next(Selection*)

Get immediate successor of selection.

int view_selections_number(Selection*)

Get selection index.

Note

Is always in range [0, count-1].

int view_selections_column_count(View*)

Get maximal number of selections on a single line.

Selection *view_selections_column(View *view, int column)

Starting from the start of the text, get the column-th selection on a line.

Parameters:

• view – The view to manipulate.

• column – The zero based column index.

Selection *view_selections_column_next(Selection *sel, int column)

Get the next column-th selection on a line.

Parameters:

• sel – The selection to manipulate.

• column – The zero based column index.

Cover

Filerange view_selections_get(Selection*)

Get an inclusive range of the selection cover.

bool view_selections_set(Selection*, const Filerange*)

Set selection cover.

Updates both cursor and anchor.

void view_selection_clear(Selection*)

Reduce selection to character currently covered by the cursor.

Note

Sets selection to non-anchored mode.

void view_selections_clear_all(View*)

Reduce all currently active selections.

void view_selections_flip(Selection*)

Flip selection orientation.

Swap cursor and anchor.

Note

Has no effect on singleton selections.

Anchor

Warning

doxygengroup: Cannot find group “view_anchor” in doxygen xml output for project “vis” from directory: build/doxygen/xml

Cursor

Selection endpoint to which cursor motions apply.

Properties

size_t view_cursors_pos(Selection*)

Get position of selection cursor.

size_t view_cursors_line(Selection*)

Get 1-based line number of selection cursor.

size_t view_cursors_col(Selection*)

Get 1-based column of selection cursor.

Note

Counts the number of graphemes on the logical line up to the cursor position.

Placement

void view_cursors_to(Selection*, size_t pos)

Place cursor of selection at pos.

Note

If the selection is not anchored, both selection endpoints will be adjusted to form a singleton selection covering one character starting at pos. Otherwise only the selection cursor will be changed while the anchor remains fixed.

If primary position was not visible before, we attempt to show the surrounding context. The viewport will be adjusted such that the line holding the primary cursor is shown in the middle of the window.

void view_cursors_scroll_to(Selection*, size_t pos)

Adjusts window viewport until the requested position becomes visible.

Note

For all but the primary selection this is equivalent to view_selection_to.

Warning

Repeatedly redraws the window content. Should only be used for short distances between current cursor position and destination.

void view_cursors_place(Selection *s, size_t line, size_t col)

Place cursor on given (line, column) pair.

Parameters:

• s – the selection to manipulate

• line – the 1-based line number

• col – the 1 based column

  Note

  Except for the different addressing format this is equivalent to view_selection_to.

int view_cursors_cell_set(Selection*, int cell)

Place selection cursor on zero based window cell index.

Warning

Fails if the selection cursor is currently not visible.

Motions

These functions perform motions based on the current selection cursor position.

size_t view_line_down(Selection*)

size_t view_line_up(Selection*)

size_t view_screenline_down(Selection*)

size_t view_screenline_up(Selection*)

size_t view_screenline_begin(Selection*)

size_t view_screenline_middle(Selection*)

size_t view_screenline_end(Selection*)

Primary Selection

These are convenience function which operate on the primary selection.

size_t view_cursor_get(View*)

Get cursor position of primary selection.

Save and Restore

Filerange view_regions_restore(View*, SelectionRegion*)

bool view_regions_save(View*, Filerange*, SelectionRegion*)

Style

void win_options_set(struct Win*, enum UiOption)

bool view_breakat_set(View*, const char *breakat)

void view_tabwidth_set(View*, int tabwidth)

Set how many spaces are used to display a tab \t character.

void win_style(struct Win*, enum UiStyle, size_t start, size_t end, bool keep_non_default)

Apply a style to a text range.

Buffer

A dynamically growing buffer storing arbitrary data.

Note

Used for Register, not Text content.

Functions

void buffer_release(Buffer*)

Release all resources, reinitialize buffer.

bool buffer_reserve(Buffer*, size_t size)

Reserve space to store at least size bytes.

bool buffer_grow(Buffer*, size_t len)

Reserve space for at least len more bytes.

bool buffer_terminate(Buffer*)

If buffer is non-empty, make sure it is NUL terminated.

bool buffer_put(Buffer*, const void *data, size_t len)

Set buffer content, growing the buffer as needed.

bool buffer_put0(Buffer*, const char *data)

Set buffer content to NUL terminated data.

bool buffer_remove(Buffer*, size_t pos, size_t len)

Remove len bytes starting at pos.

bool buffer_insert0(Buffer*, size_t pos, const char *data)

Insert NUL-terminated data at pos.

bool buffer_append(Buffer*, const void *data, size_t len)

Append further content to the end.

bool buffer_append0(Buffer*, const char *data)

Append NUL-terminated data.

bool buffer_appendf(Buffer*, const char *fmt, ...)

Append formatted buffer content, ensures NUL termination on success.

size_t buffer_length0(Buffer*)

Return length of a buffer without trailing NUL byte.

const char *buffer_content0(Buffer*)

Get pointer to buffer data.

Guaranteed to return a NUL terminated string even if buffer is empty.

ssize_t read_into_buffer(void *context, char *data, size_t len)

read(3p) like interface for reading into a Buffer (context)

struct Buffer

#include <buffer.h>

A dynamically growing buffer storing arbitrary data.

Public Members

char *data

Data pointer, NULL if empty.

size_t len

Current length of data.

size_t size

Maximal capacity of the buffer.

Array

A dynamically growing array, there exist two typical ways to use it:

1. To hold pointers to externally allocated memory regions.

   Use array_init for initialization, an element has the size of a pointer. Use the functions suffixed with _ptr to manage your pointers. The cleanup function array_release_full must only be used with this type of array.

2. To hold arbitrary sized objects.

   Use array_init_sized to specify the size of a single element. Use the regular (i.e. without the _ptr suffix) functions to manage your objects. Functions like array_add and array_set will copy the object into the array, array_get will return a pointer to the object stored within the array.

Functions

void array_init(Array*)

Initialize an Array object to store pointers.

Note

Is equivalent to array_init_sized(arr, sizeof(void*)).

void array_init_sized(Array*, size_t elem_size)

Initialize an Array object to store arbitrarily sized objects.

void array_init_from(Array*, const Array *from)

Initialize Array by using the same element size as in from.

void array_release(Array*)

Release storage space.

Reinitializes Array object.

void array_release_full(Array*)

Release storage space and call free(3) for each stored pointer.

Warning

Assumes array elements to be pointers.

void array_clear(Array*)

Empty array, keep allocated memory.

bool array_reserve(Array*, size_t count)

Reserve memory to store at least count elements.

void *array_get(const Array*, size_t idx)

Get array element.

Warning

Returns a pointer to the allocated array region. Operations which might cause reallocations (e.g. the insertion of new elements) might invalidate the pointer.

bool array_set(Array*, size_t idx, void *item)

Set array element.

Note

Copies the item into the Array. If item is NULL the corresponding memory region will be cleared.

void *array_get_ptr(const Array*, size_t idx)

Dereference pointer stored in array element.

bool array_set_ptr(Array*, size_t idx, void *item)

Store the address to which item points to into the array.

bool array_add(Array*, void *item)

Add element to the end of the array.

bool array_add_ptr(Array*, void *item)

Add pointer to the end of the array.

bool array_remove(Array*, size_t idx)

Remove an element by index.

Note

Might not shrink underlying memory region.

bool array_truncate(Array*, size_t length)

Remove all elements with index greater or equal to length, keep allocated memory.

bool array_resize(Array*, size_t length)

Change length.

Note

Has to be less or equal than the capacity. Newly accessible elements preserve their previous values.

void array_sort(Array*, int (*compar)(const void*, const void*))

Sort array, the comparision function works as for qsort(3).

bool array_push(Array*, void *item)

Push item onto the top of the stack.

Note

Is equivalent to array_add(arr, item).

void *array_pop(Array*)

Get and remove item at the top of the stack.

Warning

The same ownership rules as for array_get apply.

void *array_peek(const Array*)

Get item at the top of the stack without removing it.

Warning

The same ownership rules as for array_get apply.

struct Array

#include <array.h>

A dynamically growing array.

Public Members

char *items

size_t elem_size

Data pointer, NULL if empty.

size_t len

Size of one array element.

size_t count

Number of currently stored items.

Map

Crit-bit tree based map which supports unique prefix queries and ordered iteration.

Functions

Map *map_new(void)

Allocate a new map.

void *map_get(const Map *map, const char *key)

Lookup a value, returns NULL if not found.

Parameters:

• map – The map to search within.

• key – The key to look up.

void *map_first(const Map *map, const char **key)

Get first element of the map, or NULL if empty.

Parameters:

• map – The map to query.

• key – Updated with the key of the first element.

void *map_closest(const Map *map, const char *prefix)

Lookup element by unique prefix match.

Parameters:

• map – The map to search within.

• prefix – The prefix to search for.

Returns:

The corresponding value, if the given prefix is unique. Otherwise NULL. If no such prefix exists, then errno is set to ENOENT.

bool map_contains(const Map *map, const char *prefix)

Check whether the map contains the given prefix, or whether it can be extended to match a key of a map element.

Parameters:

• map – The map to check.

• prefix – The prefix to search for.

bool map_put(Map *map, const char *key, const void *value)

Store a key value pair in the map.

Parameters:

• map – The map to store the key-value pair in.

• key – The key to store.

• value – The value associated with the key.

Returns:

False if we run out of memory (errno = ENOMEM), or if the key already appears in the map (errno = EEXIST).

void *map_delete(Map *map, const char *key)

Remove a map element.

Parameters:

• map – The map to remove the element from.

• key – The key of the element to remove.

Returns:

The removed entry or NULL if no such element exists.

bool map_copy(Map *dest, Map *src)

Copy all entries from src into dest, overwrites existing entries in dest.

Parameters:

• dest – The destination map.

• src – The source map.

void map_iterate(const Map *map, bool (*handle)(const char *key, void *value, void *data), const void *data)

Ordered iteration over a map.

Invokes the passed callback for every map entry. If handle returns false, the iteration will stop.

Parameters:

• map – The map to iterate over.

• handle – A function invoked for every map element.

• data – A context pointer, passed as last argument to handle.

const Map *map_prefix(const Map *map, const char *prefix)

Get a sub map matching a prefix.

Parameters:

• map – The map to get the sub-map from.

• prefix – The prefix to match.

  Warning

  This returns a pointer into the original map.

  Do not alter the map while using the return value.

bool map_empty(const Map *map)

Test whether the map is empty (contains no elements).

Parameters:

map – The map to check.

void map_clear(Map *map)

Empty the map.

Parameters:

map – The map to clear.

void map_free(Map *map)

Release all memory associated with this map.

Parameters:

map – The map to free.

void map_free_full(Map *map)

Call free(3) for every map element, then free the map itself.

Parameters:

map – The map to free its elements and itself.

Warning

Assumes map elements to be pointers.