diff options
Diffstat (limited to 'vis.h')
| -rw-r--r-- | vis.h | 835 |
1 files changed, 634 insertions, 201 deletions
@@ -52,19 +52,21 @@ typedef union { /** * 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. * @rst * .. note:: An empty string ``""`` indicates that no further input is available. * @endrst * @return Pointer to first non-consumed key. * @rst * .. 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. + * indicate that not enough input was available. In the latter case + * the function will be called again once more input has been received. * @endrst * @ingroup vis_action */ -typedef const char *KeyActionFunction(Vis*, const char *keys, const Arg*); +typedef const char *KeyActionFunction(Vis *vis, const char *keys, const Arg *arg); /** Key action definition. */ typedef struct { @@ -86,8 +88,13 @@ typedef struct { const char *alias; /**< Replaces ``key`` with ``alias`` at the front of the input queue. */ } KeyBinding; +/* +--- +## Core Lifecycle Functions +*/ + /** - * @defgroup vis_lifecycle + * @defgroup vis_lifecycle Vis Lifecycle * @{ */ /** Create a new editor instance. */ @@ -96,135 +103,257 @@ Vis *vis_new(void); void vis_free(Vis*); /** * Enter main loop, start processing user input. + * @param vis The editor instance. * @return The editor exit status code. */ int vis_run(Vis*); -/** Terminate editing session, the given ``status`` will be the return value of `vis_run`. */ -void vis_exit(Vis*, int status); +/** + * Terminate editing session, the given ``status`` will be the return value of `vis_run`. + * @param vis The editor instance. + * @param status The exit status. + */ +void vis_exit(Vis *vis, int status); /** * Emergency exit, print given message, perform minimal UI cleanup and exit process. + * @param vis The editor instance. + * @param msg The message to print. * @rst * .. note:: This function does not return. * @endrst */ -void vis_die(Vis*, const char *msg, ...) __attribute__((noreturn,format(printf, 2, 3))); +void vis_die(Vis *vis, const char *msg, ...) __attribute__((noreturn,format(printf, 2, 3))); /** * Inform the editor core that a signal occurred. + * @param vis The editor instance. + * @param signum The signal number. + * @param siginfo Pointer to `siginfo_t` structure. + * @param context Pointer to context. * @return Whether the signal was handled. * @rst * .. note:: Being designed as a library the editor core does *not* register any - * signal handlers on its own. + * signal handlers on its own. * .. note:: The remaining arguments match the prototype of ``sa_sigaction`` as - * specified in `sigaction(2)`. + * specified in `sigaction(2)`. * @endrst */ -bool vis_signal_handler(Vis*, int signum, const siginfo_t *siginfo, const void *context); +bool vis_signal_handler(Vis *vis, int signum, const siginfo_t *siginfo, const void *context); /** * Interrupt long running operation. + * @param vis The editor instance. * @rst * .. 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. + * 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``. * @endrst */ void vis_interrupt(Vis*); -/** Check whether interruption was requested. */ +/** + * Check whether interruption was requested. + * @param vis The editor instance. + */ bool vis_interrupt_requested(Vis*); +/** @} */ + +/* +--- +## Drawing and Redrawing +*/ + /** - * @} - * @defgroup vis_draw + * @defgroup vis_draw Vis Drawing * @{ */ -/** Draw user interface. */ +/** + * Draw user interface. + * @param vis The editor instance. + */ void vis_draw(Vis*); -/** Completely redraw user interface. */ +/** + * Completely redraw user interface. + * @param vis The editor instance. + */ void vis_redraw(Vis*); +/** @} */ + +/* +--- +## Window Management +*/ + /** - * @} - * @defgroup vis_windows + * @defgroup vis_windows Vis Windows * @{ */ /** * Create a new window and load the given file. + * @param vis The editor instance. * @param filename If ``NULL`` an unnamed, empty buffer is created. * @rst * .. note:: If the given file name is already opened in another window, - * the underlying File object is shared. + * the underlying File object is shared. * @endrst */ -bool vis_window_new(Vis*, const char *filename); +bool vis_window_new(Vis *vis, const char *filename); /** * Create a new window associated with a file descriptor. + * @param vis The editor instance. + * @param fd The file descriptor to associate with the window. * @rst * .. note:: No data is read from `fd`, but write commands without an - * explicit filename will instead write to the file descriptor. + * explicit filename will instead write to the file descriptor. * @endrst */ -bool vis_window_new_fd(Vis*, int fd); -/** Reload the file currently displayed in the window from disk. */ +bool vis_window_new_fd(Vis *vis, int fd); +/** + * Reload the file currently displayed in the window from disk. + * @param win The window to reload. + */ bool vis_window_reload(Win*); -/** Change the file currently displayed in the window. */ -bool vis_window_change_file(Win*, const char *filename); -/** Check whether closing the window would loose unsaved changes. */ +/** + * Change the file currently displayed in the window. + * @param win The window to change. + * @param filename The new file to display. + */ +bool vis_window_change_file(Win *win, const char *filename); +/** + * Check whether closing the window would loose unsaved changes. + * @param win The window to check. + */ bool vis_window_closable(Win*); -/** Close window, redraw user interface. */ +/** + * Close window, redraw user interface. + * @param win The window to close. + */ void vis_window_close(Win*); -/** Split the window, shares the underlying file object. */ +/** + * Split the window, shares the underlying file object. + * @param original The window to split. + */ bool vis_window_split(Win*); +/** + * Draw a specific window. + * @param win The window to draw. + */ void vis_window_draw(Win*); +/** + * Invalidate a window, forcing a redraw. + * @param win The window to invalidate. + */ void vis_window_invalidate(Win*); -/** Focus next window. */ +/** + * Focus next window. + * @param vis The editor instance. + */ void vis_window_next(Vis*); -/** Focus previous window. */ +/** + * Focus previous window. + * @param vis The editor instance. + */ void vis_window_prev(Vis*); -/** Change currently focused window, receiving user input. */ +/** + * Change currently focused window, receiving user input. + * @param win The window to focus. + */ void vis_window_focus(Win*); -/** Swap location of two windows. */ -void vis_window_swap(Win*, Win*); /** - * @} - * @defgroup vis_info + * Swap location of two windows. + * @param win1 The first window. + * @param win2 The second window. + */ +void vis_window_swap(Win *win1, Win *win2); +/** @} */ + +/* +--- +## Information and Messaging +*/ + +/** + * @defgroup vis_info Vis Info * @{ */ /** * Display a user prompt with a certain title. + * @param vis The editor instance. + * @param title The title of the prompt. * @rst * .. note:: The prompt is currently implemented as a single line height window. * @endrst */ -void vis_prompt_show(Vis*, const char *title); +void vis_prompt_show(Vis *vis, const char *title); /** * Display a single line message. + * @param vis The editor instance. + * @param msg The message to display. * @rst * .. note:: The message will automatically be hidden upon next input. * @endrst */ -void vis_info_show(Vis*, const char *msg, ...) __attribute__((format(printf, 2, 3))); +void vis_info_show(Vis *vis, const char *msg, ...) __attribute__((format(printf, 2, 3))); + +/** + * Display arbitrary long message in a dedicated window. + * @param vis The editor instance. + * @param msg The message to display. + */ +void vis_message_show(Vis *vis, const char *msg); +/** @} */ + +/* +--- +## Text Changes +*/ -/** Display arbitrary long message in a dedicated window. */ -void vis_message_show(Vis*, const char *msg); /** - * @} - * @defgroup vis_changes + * @defgroup vis_changes Vis Changes * @{ */ -void vis_insert(Vis*, size_t pos, const char *data, size_t len); -void vis_delete(Vis*, size_t pos, size_t len); -void vis_replace(Vis*, size_t pos, const char *data, size_t len); -/** Perform insertion at all cursor positions. */ -void vis_insert_key(Vis*, const char *data, size_t len); +/** + * Insert data into the file. + * @param vis The editor instance. + * @param pos The position to insert at. + * @param data The data to insert. + * @param len The length of the data to insert. + */ +void vis_insert(Vis *vis, size_t pos, const char *data, size_t len); +/** + * Delete data from the file. + * @param vis The editor instance. + * @param pos The starting position of the deletion. + * @param len The length of the data to delete. + */ +void vis_delete(Vis *vis, size_t pos, size_t len); +/** + * Replace data in the file. + * @param vis The editor instance. + * @param pos The position to replace at. + * @param data The new data. + * @param len The length of the new data. + */ +void vis_replace(Vis *vis, size_t pos, const char *data, size_t len); +/** + * Perform insertion at all cursor positions. + * @param vis The editor instance. + * @param data The data to insert. + * @param len The length of the data. + */ +void vis_insert_key(Vis *vis, const char *data, size_t len); /** * Perform character substitution at all cursor positions. + * @param vis The editor instance. + * @param data The character data to substitute. + * @param len The length of the data. * @rst * .. note:: Does not replace new line characters. * @endrst */ -void vis_replace_key(Vis*, const char *data, size_t len); +void vis_replace_key(Vis *vis, const char *data, size_t len); /** * Insert a tab at all cursor positions. + * @param vis The editor instance. * @rst * .. note:: Performs tab expansion according to current settings. * @endrst @@ -232,6 +361,7 @@ void vis_replace_key(Vis*, const char *data, size_t len); void vis_insert_tab(Vis*); /** * Inserts a new line character at every cursor position. + * @param vis The editor instance. * @rst * .. note:: Performs auto indentation according to current settings. * @endrst @@ -239,6 +369,17 @@ void vis_insert_tab(Vis*); void vis_insert_nl(Vis*); /** @} */ + +/* +--- +## Editor Modes +*/ + +/** + * @defgroup vis_modes Vis Modes + * @{ + */ + /** Mode specifiers. */ enum VisMode { VIS_MODE_NORMAL, @@ -251,31 +392,50 @@ enum VisMode { }; /** - * @defgroup vis_modes - * @{ - */ -/** * Switch mode. + * @param vis The editor instance. + * @param mode The mode to switch to. * @rst * .. 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. + * mode, followed by an enter event of the new mode. + * No events are emitted, if the specified mode is already active. * @endrst */ -void vis_mode_switch(Vis*, enum VisMode); -/** Translate human readable mode name to constant. */ -enum VisMode vis_mode_from(Vis*, const char *name); +void vis_mode_switch(Vis *vis, enum VisMode mode); +/** + * Translate human readable mode name to constant. + * @param vis The editor instance. + * @param name The name of the mode. + */ +enum VisMode vis_mode_from(Vis *vis, const char *name); + +/** @} */ + +/* +--- +## Keybinding and Actions +*/ /** - * @} - * @defgroup vis_keybind + * @defgroup vis_keybind Vis Keybindings * @{ */ +/** + * Create a new key binding. + * @param vis The editor instance. + */ KeyBinding *vis_binding_new(Vis*); -void vis_binding_free(Vis*, KeyBinding*); +/** + * Free a key binding. + * @param vis The editor instance. + * @param binding The key binding to free. + */ +void vis_binding_free(Vis *vis, KeyBinding *binding); /** * Set up a key binding. + * @param vis The editor instance. + * @param mode The mode in which the binding applies. * @param force Whether an existing mapping should be discarded. * @param key The symbolic key to map. * @param binding The binding to map. @@ -283,48 +443,104 @@ void vis_binding_free(Vis*, KeyBinding*); * .. note:: ``binding->key`` is always ignored in favor of ``key``. * @endrst */ -bool vis_mode_map(Vis*, enum VisMode, bool force, const char *key, const KeyBinding*); -/** Analogous to `vis_mode_map`, but window specific. */ -bool vis_window_mode_map(Win*, enum VisMode, bool force, const char *key, const KeyBinding*); -/** Unmap a symbolic key in a given mode. */ -bool vis_mode_unmap(Vis*, enum VisMode, const char *key); -/** Analogous to `vis_mode_unmap`, but window specific. */ -bool vis_window_mode_unmap(Win*, enum VisMode, const char *key); +bool vis_mode_map(Vis *vis, enum VisMode mode, bool force, const char *key, const KeyBinding *binding); /** - * @} - * @defgroup vis_action + * Analogous to `vis_mode_map`, but window specific. + * @param win The window for the mapping. + * @param mode The mode in which the binding applies. + * @param force Whether an existing mapping should be discarded. + * @param key The symbolic key to map. + * @param binding The binding to map. + */ +bool vis_window_mode_map(Win *win, enum VisMode mode, bool force, const char *key, const KeyBinding *binding); +/** + * Unmap a symbolic key in a given mode. + * @param vis The editor instance. + * @param mode The mode from which to unmap. + * @param key The symbolic key to unmap. + */ +bool vis_mode_unmap(Vis *vis, enum VisMode mode, const char *key); +/** + * Analogous to `vis_mode_unmap`, but window specific. + * @param win The window from which to unmap. + * @param mode The mode from which to unmap. + * @param key The symbolic key to unmap. + */ +bool vis_window_mode_unmap(Win *win, enum VisMode mode, const char *key); +/** @} */ + +/* +--- +## Key Actions +*/ + +/** + * @defgroup vis_action Vis Actions * @{ */ /** * Create new key action. + * @param vis The editor instance. * @param name The name to be used as symbolic key when registering. * @param help Optional single line help text. * @param func The function implementing the key action logic. * @param arg Argument passed to function. */ -KeyAction *vis_action_new(Vis*, const char *name, const char *help, KeyActionFunction*, Arg); -void vis_action_free(Vis*, KeyAction*); +KeyAction *vis_action_new(Vis *vis, const char *name, const char *help, KeyActionFunction *func, Arg arg); +/** + * Free a key action. + * @param vis The editor instance. + * @param action The key action to free. + */ +void vis_action_free(Vis *vis, KeyAction *action); /** * Register key action. + * @param vis The editor instance. + * @param keyaction The key action to register. * @rst * .. note:: Makes the key action available under the pseudo key name specified - * in ``keyaction->name``. + * in ``keyaction->name``. * @endrst */ -bool vis_action_register(Vis*, const KeyAction*); +bool vis_action_register(Vis *vis, const KeyAction *keyaction); + +/** @} */ + +/* +--- +## Keymap +*/ /** - * @} - * @defgroup vis_keymap + * @defgroup vis_keymap Vis Keymap * @{ */ -/** Add a key translation. */ -bool vis_keymap_add(Vis*, const char *key, const char *mapping); -/** Temporarily disable the keymap for the next key press. */ +/** + * Add a key translation. + * @param vis The editor instance. + * @param key The key to translate. + * @param mapping The string to map the key to. + */ +bool vis_keymap_add(Vis *vis, const char *key, const char *mapping); +/** + * Temporarily disable the keymap for the next key press. + * @param vis The editor instance. + */ void vis_keymap_disable(Vis*); /** @} */ + +/* +--- +## Operators +*/ + +/** + * @defgroup vis_operators Vis Operators + * @{ + */ + /** Operator specifiers. */ enum VisOperator { VIS_OP_DELETE, @@ -346,55 +562,77 @@ enum VisOperator { VIS_OP_LAST, /* has to be last enum member */ }; -/** - * @defgroup vis_operators - * @{ - */ typedef struct OperatorContext OperatorContext; /** * 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. * @rst * .. note:: The operator must return the new cursor position or ``EPOS`` if - * the cursor should be disposed. + * the cursor should be disposed. * .. note:: The last used operator can be repeated using `vis_repeat`. * @endrst */ -typedef size_t (VisOperatorFunction)(Vis*, Text*, OperatorContext*); +typedef size_t (VisOperatorFunction)(Vis *vis, Text *text, OperatorContext *context); /** * Register an operator. + * @param vis The editor instance. + * @param func The function implementing the operator logic. + * @param context User-supplied context for the operator. * @return Operator ID. Negative values indicate an error, positive ones can be - * used with `vis_operator`. + * used with `vis_operator`. */ -int vis_operator_register(Vis*, VisOperatorFunction*, void *context); +int vis_operator_register(Vis *vis, VisOperatorFunction *func, void *context); /** * Set operator to execute. + * @param vis The editor instance. + * @param op The operator to perform. + * @param ... Additional arguments depending on the operator type. * * Has immediate effect if: - * - A visual mode is active. - * - The same operator was already set (range will be the current line). + * - 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`). + * - 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. + * - `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. */ -bool vis_operator(Vis*, enum VisOperator, ...); +bool vis_operator(Vis *vis, enum VisOperator op, ...); -/** Repeat last operator, possibly with a new count if one was provided in the meantime. */ +/** + * Repeat last operator, possibly with a new count if one was provided in the meantime. + * @param vis The editor instance. + */ void vis_repeat(Vis*); -/** Cancel pending operator, reset count, motion, text object, register etc. */ +/** + * Cancel pending operator, reset count, motion, text object, register etc. + * @param vis The editor instance. + */ void vis_cancel(Vis*); /** @} */ + +/* +--- +## Motions +*/ + +/** + * @defgroup vis_motions Vis Motions + * @{ + */ + /** Motion specifiers. */ enum VisMotion { VIS_MOVE_LINE_DOWN, @@ -478,59 +716,79 @@ enum VisMotion { }; /** - * @defgroup vis_motions - * @{ - */ -/** * Set motion to perform. + * @param vis The editor instance. + * @param motion The motion to perform. + * @param ... Additional arguments depending on the motion type. * * The following motions take an additional argument: * - * - `VIS_MOVE_SEARCH_FORWARD` and `VIS_MOVE_SEARCH_BACKWARD` + * - `VIS_MOVE_SEARCH_FORWARD` and `VIS_MOVE_SEARCH_BACKWARD` * - * The search pattern as ``const char *``. + * The search pattern as ``const char *``. * - * - ``VIS_MOVE_{LEFT,RIGHT}_{TO,TILL}`` + * - ``VIS_MOVE_{LEFT,RIGHT}_{TO,TILL}`` * - * The character to search for as ``const char *``. + * The character to search for as ``const char *``. */ -bool vis_motion(Vis*, enum VisMotion, ...); +bool vis_motion(Vis *vis, enum VisMotion motion, ...); enum VisMotionType { VIS_MOTIONTYPE_LINEWISE = 1 << 0, VIS_MOTIONTYPE_CHARWISE = 1 << 1, }; -/** Force currently specified motion to behave in line or character wise mode. */ -void vis_motion_type(Vis *vis, enum VisMotionType); +/** + * Force currently specified motion to behave in line or character wise mode. + * @param vis The editor instance. + * @param type The motion type (line-wise or character-wise). + */ +void vis_motion_type(Vis *vis, enum VisMotionType type); /** * 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. * @rst * .. note:: Should a motion not be possible, the original position must be returned. - * TODO: we might want to change that to ``EPOS``? + * TODO: we might want to change that to ``EPOS``? * @endrst */ -typedef size_t (VisMotionFunction)(Vis*, Win*, void *context, size_t pos); +typedef size_t (VisMotionFunction)(Vis *vis, Win *win, void *context, size_t pos); /** * Register a motion function. + * @param vis The editor instance. + * @param context User-supplied context for the motion. + * @param func The function implementing the motion logic. * @return Motion ID. Negative values indicate an error, positive ones can be - * used with `vis_motion`. + * used with `vis_motion`. */ -int vis_motion_register(Vis*, void *context, VisMotionFunction*); +int vis_motion_register(Vis *vis, void *context, VisMotionFunction *func); + +/** @} */ + +/* +--- +## Count Iteration +*/ /** - * @} - * @defgroup vis_count + * @defgroup vis_count Vis Count * @{ */ /** No count was specified. */ #define VIS_COUNT_UNKNOWN (-1) #define VIS_COUNT_DEFAULT(count, def) ((count) == VIS_COUNT_UNKNOWN ? (def) : (count)) #define VIS_COUNT_NORMALIZE(count) ((count) < 0 ? VIS_COUNT_UNKNOWN : (count)) -/** Set the shell */ -void vis_shell_set(Vis*, const char *new_shell); +/** + * Set the shell. + * @param vis The editor instance. + * @param new_shell The new shell to set. + */ +void vis_shell_set(Vis *vis, const char *new_shell); typedef struct { Vis *vis; @@ -538,21 +796,41 @@ typedef struct { int count; } VisCountIterator; -/** Get iterator initialized with current count or ``def`` if not specified. */ -VisCountIterator vis_count_iterator_get(Vis*, int def); -/** Get iterator initialized with a count value. */ -VisCountIterator vis_count_iterator_init(Vis*, int count); +/** + * Get iterator initialized with current count or ``def`` if not specified. + * @param vis The editor instance. + * @param def The default count if none is specified. + */ +VisCountIterator vis_count_iterator_get(Vis *vis, int def); +/** + * Get iterator initialized with a count value. + * @param vis The editor instance. + * @param count The count value to initialize with. + */ +VisCountIterator vis_count_iterator_init(Vis *vis, int count); /** * Increment iterator counter. + * @param iter Pointer to the iterator. * @return Whether iteration should continue. * @rst * .. note:: Terminates iteration if the editor was - * `interrupted <vis_interrupt>`_ in the meantime. + * `interrupted <vis_interrupt>`_ in the meantime. * @endrst */ -bool vis_count_iterator_next(VisCountIterator*); +bool vis_count_iterator_next(VisCountIterator *iter); /** @} */ + +/* +--- +## Text Objects +*/ + +/** + * @defgroup vis_textobjs Vis Text Objects + * @{ + */ + /** Text object specifier. */ enum VisTextObject { VIS_TEXTOBJECT_INNER_WORD, @@ -585,30 +863,48 @@ enum VisTextObject { }; /** - * @defgroup vis_textobjs - * @{ - */ - -/** * 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. * @rst * .. note:: The originating position does not necessarily have to be contained in - * the resulting range. + * the resulting range. * @endrst */ -typedef Filerange (VisTextObjectFunction)(Vis*, Win*, void *context, size_t pos); +typedef Filerange (VisTextObjectFunction)(Vis *vis, Win *win, void *context, size_t pos); /** * Register a new text object. + * @param vis The editor instance. + * @param type The type of the text object. + * @param data User-supplied data for the text object. + * @param func The function implementing the text object logic. * @return Text object ID. Negative values indicate an error, positive ones can be - * used with `vis_textobject`. + * used with `vis_textobject`. */ -int vis_textobject_register(Vis*, int type, void *data, VisTextObjectFunction*); +int vis_textobject_register(Vis *vis, int type, void *data, VisTextObjectFunction *func); -/** Set text object to use. */ -bool vis_textobject(Vis*, enum VisTextObject); +/** + * Set text object to use. + * @param vis The editor instance. + * @param textobj The text object to set. + */ +bool vis_textobject(Vis *vis, enum VisTextObject textobj); /** @} */ + +/* +--- +## Marks +*/ + +/** + * @defgroup vis_marks Vis Marks + * @{ + */ + /** Mark specifiers. */ enum VisMark { VIS_MARK_DEFAULT, @@ -623,57 +919,91 @@ enum VisMark { }; /** - * @} - * @defgroup vis_marks - * @{ + * Translate between single character mark name and corresponding constant. + * @param vis The editor instance. + * @param mark The character representing the mark. + */ +enum VisMark vis_mark_from(Vis *vis, char mark); +/** + * Translate between mark constant and single character mark name. + * @param vis The editor instance. + * @param mark The mark constant. */ -/** Translate between single character mark name and corresponding constant. */ -enum VisMark vis_mark_from(Vis*, char mark); -char vis_mark_to(Vis*, enum VisMark); +char vis_mark_to(Vis *vis, enum VisMark mark); /** * Specify mark to use. + * @param vis The editor instance. + * @param mark The mark to use. * @rst * .. note:: If none is specified `VIS_MARK_DEFAULT` will be used. * @endrst */ -void vis_mark(Vis*, enum VisMark); +void vis_mark(Vis *vis, enum VisMark mark); +/** + * Get the currently used mark. + * @param vis The editor instance. + */ enum VisMark vis_mark_used(Vis*); /** * Store a set of ``Filerange``s in a mark. * - * @param id The register to use. + * @param win The window whose selections to store. + * @param id The mark ID to use. * @param sel The array containing the file ranges. */ -void vis_mark_set(Win*, enum VisMark id, Array *sel); +void vis_mark_set(Win *win, enum VisMark id, Array *sel); /** * Get an array of file ranges stored in the mark. - * + * @param win The window whose mark to retrieve. + * @param id The mark ID to retrieve. + * @return An array of file ranges. * @rst * .. warning:: The caller must eventually free the Array by calling - * ``array_release``. + * ``array_release``. * @endrst */ -Array vis_mark_get(Win*, enum VisMark id); +Array vis_mark_get(Win *win, enum VisMark id); /** * Normalize an Array of Fileranges. + * @param array The array of file ranges to normalize. * * Removes invalid ranges, merges overlapping ones and sorts * according to the start position. */ -void vis_mark_normalize(Array*); -/** Add selections of focused window to jump list. */ +void vis_mark_normalize(Array *array); +/** + * Add selections of focused window to jump list. + * @param vis The editor instance. + */ bool vis_jumplist_save(Vis*); -/** Navigate jump list backwards. */ +/** + * Navigate jump list backwards. + * @param vis The editor instance. + */ bool vis_jumplist_prev(Vis*); -/** Navigate jump list forwards. */ +/** + * Navigate jump list forwards. + * @param vis The editor instance. + */ bool vis_jumplist_next(Vis*); /** @} */ + +/* +--- +## Registers +*/ + +/** + * @defgroup vis_registers Vis Registers + * @{ + */ + /** Register specifiers. */ enum VisRegister { VIS_REG_DEFAULT, /* used when no other register is specified */ VIS_REG_ZERO, /* yank register */ VIS_REG_AMPERSAND, /* last regex match */ - VIS_REG_1, /* 1-9 last sub-expression matches */ + VIS_REG_1, /* 1-9 last sub-expression matches */ VIS_REG_2, VIS_REG_3, VIS_REG_4, @@ -709,72 +1039,114 @@ enum VisRegister { }; /** - * @defgroup vis_registers - * @{ + * Translate between single character register name and corresponding constant. + * @param vis The editor instance. + * @param reg The character representing the register. + */ +enum VisRegister vis_register_from(Vis *vis, char reg); +/** + * Translate between register constant and single character register name. + * @param vis The editor instance. + * @param reg The register constant. */ -/** Translate between single character register name and corresponding constant. */ -enum VisRegister vis_register_from(Vis*, char reg); -char vis_register_to(Vis*, enum VisRegister); +char vis_register_to(Vis *vis, enum VisRegister reg); /** * Specify register to use. + * @param vis The editor instance. + * @param reg The register to use. * @rst * .. note:: If none is specified `VIS_REG_DEFAULT` will be used. * @endrst */ -void vis_register(Vis*, enum VisRegister); +void vis_register(Vis *vis, enum VisRegister reg); +/** + * Get the currently used register. + * @param vis The editor instance. + */ enum VisRegister vis_register_used(Vis*); /** * Get register content. + * @param vis The editor instance. + * @param id The register ID to retrieve. * @return An array of ``TextString`` structs. * @rst * .. warning:: The caller must eventually free the array resources using - * ``array_release``. + * ``array_release``. * @endrst */ -Array vis_register_get(Vis*, enum VisRegister); +Array vis_register_get(Vis *vis, enum VisRegister id); /** * Set register content. + * @param vis The editor instance. + * @param id The register ID to set. * @param data The array comprised of ``TextString`` structs. */ -bool vis_register_set(Vis*, enum VisRegister, Array *data); +bool vis_register_set(Vis *vis, enum VisRegister id, Array *data); +/** @} */ + +/* +--- +## Macros +*/ + /** - * @} - * @defgroup vis_macros + * @defgroup vis_macros Vis Macros * @{ */ /** * Start recording a macro. + * @param vis The editor instance. + * @param reg The register to record the macro into. * @rst * .. note:: Fails if a recording is already ongoing. * @endrst */ -bool vis_macro_record(Vis*, enum VisRegister); -/** Stop recording, fails if there is nothing to stop. */ +bool vis_macro_record(Vis *vis, enum VisRegister reg); +/** + * Stop recording, fails if there is nothing to stop. + * @param vis The editor instance. + */ bool vis_macro_record_stop(Vis*); -/** Check whether a recording is currently ongoing. */ +/** + * Check whether a recording is currently ongoing. + * @param vis The editor instance. + */ bool vis_macro_recording(Vis*); /** * Replay a macro. + * @param vis The editor instance. + * @param reg The register containing the macro to replay. * @rst * .. note:: A macro currently being recorded can not be replayed. * @endrst */ -bool vis_macro_replay(Vis*, enum VisRegister); +bool vis_macro_replay(Vis *vis, enum VisRegister reg); + +/** @} */ + +/* +--- +## Commands +*/ /** - * @} - * @defgroup vis_cmds + * @defgroup vis_cmds Vis Commands * @{ */ -/** Execute a ``:``-command. */ -bool vis_cmd(Vis*, const char *cmd); +/** + * Execute a ``:``-command. + * @param vis The editor instance. + * @param cmd The command string to execute. + */ +bool vis_cmd(Vis *vis, const char *cmd); /** Command handler function. */ typedef bool (VisCommandFunction)(Vis*, Win*, void *data, bool force, const char *argv[], Selection*, Filerange*); /** * Register new ``:``-command. + * @param vis The editor instance. * @param name The command name. * @param help Optional single line help text. * @param context User supplied context pointer passed to the handler function. @@ -783,14 +1155,24 @@ typedef bool (VisCommandFunction)(Vis*, Win*, void *data, bool force, * .. note:: Any unique prefix of the command name will invoke the command. * @endrst */ -bool vis_cmd_register(Vis*, const char *name, const char *help, void *context, VisCommandFunction*); +bool vis_cmd_register(Vis *vis, const char *name, const char *help, void *context, VisCommandFunction *func); + +/** + * Unregister ``:``-command. + * @param vis The editor instance. + * @param name The name of the command to unregister. + */ +bool vis_cmd_unregister(Vis *vis, const char *name); + +/** @} */ -/** Unregister ``:``-command. */ -bool vis_cmd_unregister(Vis*, const char *name); +/* +--- +## Options +*/ /** - * @} - * @defgroup vis_options + * @defgroup vis_options Vis Options * @{ */ /** Option properties. */ @@ -805,19 +1187,22 @@ enum VisOption { /** * 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 arg The new option value. + * @param value The new option value. */ -typedef bool (VisOptionFunction)(Vis*, Win*, void *context, bool toggle, - enum VisOption, const char *name, Arg *value); +typedef bool (VisOptionFunction)(Vis *vis, Win *win, void *context, bool force, + enum VisOption option_flags, const char *name, Arg *value); /** * Register a new ``:set`` option. + * @param vis The editor instance. * @param names A ``NULL`` terminated array of option names. - * @param option Option properties. + * @param option_flags The applicable option flags. * @param func The function handling the option. * @param context User supplied context pointer passed to the handler function. * @param help Optional single line help text. @@ -825,21 +1210,36 @@ typedef bool (VisOptionFunction)(Vis*, Win*, void *context, bool toggle, * .. note:: Fails if any of the given option names is already registered. * @endrst */ -bool vis_option_register(Vis*, const char *names[], enum VisOption, - VisOptionFunction*, void *context, const char *help); +bool vis_option_register(Vis *vis, const char *names[], enum VisOption option_flags, + VisOptionFunction *func, void *context, const char *help); /** * Unregister an existing ``:set`` option. + * @param vis The editor instance. + * @param name The name of the option to unregister. * @rst * .. note:: Also unregisters all aliases as given to `vis_option_register`. * @endrst */ -bool vis_option_unregister(Vis*, const char *name); +bool vis_option_unregister(Vis *vis, const char *name); -/** Execute any kind (``:``, ``?``, ``/``) of prompt command */ -bool vis_prompt_cmd(Vis*, const char *cmd); +/** + * Execute any kind (``:``, ``?``, ``/``) of prompt command + * @param vis The editor instance. + * @param cmd The command string. + */ +bool vis_prompt_cmd(Vis *vis, const char *cmd); /** * Pipe a given file range to an external process. + * @param vis The editor instance. + * @param file The file to pipe. + * @param range The file range to pipe. + * @param argv Argument list, must be ``NULL`` terminated. + * @param stdout_context Context for stdout callback. + * @param read_stdout Callback for stdout data. + * @param stderr_context Context for stderr callback. + * @param read_stderr Callback for stderr data. + * @param fullscreen Whether the external process is a fullscreen program (e.g. curses based) * * If the range is invalid 'interactive' mode is enabled, meaning that * stdin and stderr are passed through the underlying command, stdout @@ -863,7 +1263,7 @@ bool vis_prompt_cmd(Vis*, const char *cmd); * * @return The exit status of the forked process. */ -int vis_pipe(Vis*, File*, Filerange*, const char *argv[], +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); @@ -871,79 +1271,112 @@ int vis_pipe(Vis*, File*, Filerange*, const char *argv[], /** * Pipe a Filerange to an external process, return its exit status and capture * everything that is written to stdout/stderr. + * @param vis The editor instance. + * @param file The file to pipe. + * @param range The file range to pipe. * @param argv Argument list, must be ``NULL`` terminated. * @param out Data written to ``stdout``, will be ``NUL`` terminated. * @param err Data written to ``stderr``, will be ``NUL`` terminated. * @param fullscreen Whether the external process is a fullscreen program (e.g. curses based) * @rst * .. warning:: The pointers stored in ``out`` and ``err`` need to be `free(3)`-ed - * by the caller. + * by the caller. * @endrst */ -int vis_pipe_collect(Vis*, File*, Filerange*, const char *argv[], char **out, char **err, bool fullscreen); +int vis_pipe_collect(Vis *vis, File *file, Filerange *range, 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. + * @param vis The editor instance. + * @param buf The buffer to pipe. * @param argv Argument list, must be ``NULL`` terminated. * @param out Data written to ``stdout``, will be ``NUL`` terminated. * @param err Data written to ``stderr``, will be ``NUL`` terminated. * @param fullscreen Whether the external process is a fullscreen program (e.g. curses based) * @rst * .. warning:: The pointers stored in ``out`` and ``err`` need to be `free(3)`-ed - * by the caller. + * by the caller. * @endrst */ -int vis_pipe_buf_collect(Vis*, const char*, const char *argv[], char **out, char **err, bool fullscreen); +int vis_pipe_buf_collect(Vis *vis, const char *buf, const char *argv[], char **out, char **err, bool fullscreen); + +/** @} */ + +/* +--- +## Keys +*/ /** - * @} - * @defgroup vis_keys + * @defgroup vis_keys Vis Keys * @{ */ /** * Advance to the start of the next symbolic key. + * @param vis The editor instance. + * @param keys The current symbolic key string. * * Given the start of a symbolic key, returns a pointer to the start of the one * immediately following it. */ -const char *vis_keys_next(Vis*, const char *keys); -/** Convert next symbolic key to an Unicode code point, returns ``-1`` for unknown keys. */ -long vis_keys_codepoint(Vis*, const char *keys); +const char *vis_keys_next(Vis *vis, const char *keys); +/** + * Convert next symbolic key to an Unicode code point, returns ``-1`` for unknown keys. + * @param vis The editor instance. + * @param keys The symbolic key string. + */ +long vis_keys_codepoint(Vis *vis, const char *keys); /** * Convert next symbolic key to a UTF-8 sequence. + * @param vis The editor instance. + * @param keys The symbolic key string. + * @param utf8 Buffer to store the UTF-8 sequence. * @return Whether conversion was successful, if not ``utf8`` is left unmodified. * @rst * .. note:: Guarantees that ``utf8`` is NUL terminated on success. * @endrst */ -bool vis_keys_utf8(Vis*, const char *keys, char utf8[static UTFmax+1]); -/** Process symbolic keys as if they were user originated input. */ -void vis_keys_feed(Vis*, const char *keys); +bool vis_keys_utf8(Vis *vis, const char *keys, char utf8[static UTFmax+1]); +/** + * Process symbolic keys as if they were user originated input. + * @param vis The editor instance. + * @param keys The symbolic key string to feed. + */ +void vis_keys_feed(Vis *vis, const char *keys); +/** @} */ + +/* +--- +## Miscellaneous +*/ + /** - * @} - * @defgroup vis_misc + * @defgroup vis_misc Vis Miscellaneous * @{ */ /** * Get a regex object matching pattern. - * @param regex The regex pattern to compile, if ``NULL`` the most recently used - * one is substituted. + * @param vis The editor instance. + * @param pattern The regex pattern to compile, if ``NULL`` the most recently used + * one is substituted. * @return A Regex object or ``NULL`` in case of an error. * @rst * .. warning:: The caller must free the regex object using `text_regex_free`. * @endrst */ -Regex *vis_regex(Vis*, const char *pattern); +Regex *vis_regex(Vis *vis, const char *pattern); /** * Take an undo snapshot to which we can later revert. + * @param vis The editor instance. + * @param file The file for which to take a snapshot. * @rst * .. note:: Does nothing when invoked while replaying a macro. * @endrst */ -void vis_file_snapshot(Vis*, File*); +void vis_file_snapshot(Vis *vis, File *file); /** @} */ /* TODO: expose proper API to iterate through files etc */ |