vis.h

   1 #ifndef VIS_H
   2 #define VIS_H
   3
   4 #include <signal.h>
   5 #include <stddef.h>
   6 #include <stdbool.h>
   7
   8 typedef struct Vis Vis;
   9 typedef struct File File;
  10 typedef struct Win Win;
  11
  12 #include "ui.h"
  13 #include "view.h"
  14 #include "text-regex.h"
  15 #include "libutf.h"
  16 #include "array.h"
  17
  18 #ifndef CONFIG_HELP
  19 #define CONFIG_HELP 1
  20 #endif
  21
  22 #if CONFIG_HELP
  23 #define VIS_HELP_DECL(x) x
  24 #define VIS_HELP_USE(x) x
  25 #define VIS_HELP(x) (x),
  26 #else
  27 #define VIS_HELP_DECL(x)
  28 #define VIS_HELP_USE(x) NULL
  29 #define VIS_HELP(x)
  30 #endif
  31
  32 /* simplify utility renames by distribution packagers */
  33 #ifndef VIS_OPEN
  34 #define VIS_OPEN "vis-open"
  35 #endif
  36 #ifndef VIS_CLIPBOARD
  37 #define VIS_CLIPBOARD "vis-clipboard"
  38 #endif
  39
  40 /* maximum bytes needed for string representation of a (pseudo) key */
  41 #define VIS_KEY_LENGTH_MAX 64
  42
  43 /**
  44  * Editor event handlers.
  45  */
  46 typedef struct {
  47         void (*init)(Vis*);
  48         void (*start)(Vis*);
  49         void (*quit)(Vis*);
  50         void (*mode_insert_input)(Vis*, const char *key, size_t len);
  51         void (*mode_replace_input)(Vis*, const char *key, size_t len);
  52         void (*file_open)(Vis*, File*);
  53         bool (*file_save_pre)(Vis*, File*, const char *path);
  54         void (*file_save_post)(Vis*, File*, const char *path);
  55         void (*file_close)(Vis*, File*);
  56         void (*win_open)(Vis*, Win*);
  57         void (*win_close)(Vis*, Win*);
  58         void (*win_highlight)(Vis*, Win*);
  59         void (*win_status)(Vis*, Win*);
  60 } VisEvent;
  61
  62 /** Union used to pass arguments to key action functions. */
  63 typedef union {
  64         bool b;
  65         int i;
  66         const char *s;
  67         const void *v;
  68         void (*w)(View*);
  69         void (*f)(Vis*);
  70         Filerange (*combine)(const Filerange*, const Filerange*);
  71 } Arg;
  72
  73 /**
  74  * Key action handling function.
  75  * @param keys Input queue content *after* the binding which invoked this function.
  76  * @rst
  77  * .. note:: An empty string ``""`` indicates that no further input is available.
  78  * @endrst
  79  * @return Pointer to first non-cosumed key.
  80  * @rst
  81  * .. warning:: Must be in range ``[keys, keys+strlen(keys)]`` or ``NULL`` to
  82  *              indicate that not enough input was available. In the latter case
  83  *              the function will be called again once more input has been received.
  84  * @endrst
  85  * @ingroup vis_action
  86  */
  87 typedef const char *KeyActionFunction(Vis*, const char *keys, const Arg*);
  88
  89 /** Key action definition. */
  90 typedef struct {
  91         const char *name;                /**< Name of a pseudo key ``<name>`` which can be used in mappings. */
  92         VIS_HELP_DECL(const char *help;) /**< One line human readable description, displayed by ``:help``. */
  93         KeyActionFunction *func;         /**< Key action implementation function. */
  94         Arg arg;                         /**< Options passes as last argument to ``func``. */
  95 } KeyAction;
  96
  97 /**
  98  * A key binding, refers to an action or an alias
  99  * @rst
 100  * .. note:: Either ``action`` or ``alias`` must be ``NULL``.
 101  * @endrst
 102  */
 103 typedef struct {
 104         const char *key;         /**< Symbolic key to trigger this binding. */
 105         const KeyAction *action; /**< Action to invoke when triggering this binding. */
 106         const char *alias;       /**< Replaces ``key`` with ``alias`` at the front of the input queue. */
 107 } KeyBinding;
 108
 109 /**
 110  * @defgroup vis_lifecycle
 111  * @{
 112  */
 113 /** Create a new editor instance using the given user interface and event handlers. */
 114 Vis *vis_new(Ui*, VisEvent*);
 115 /** Free all resources associated with this editor instance, terminates UI. */
 116 void vis_free(Vis*);
 117 /**
 118  * Enter main loop, start processing user input.
 119  * @return The editor exit status code.
 120  */
 121 int vis_run(Vis*);
 122 /** Terminate editing session, the given ``status`` will be the return value of `vis_run`. */
 123 void vis_exit(Vis*, int status);
 124 /**
 125  * Emergency exit, print given message, perform minimal UI cleanup and exit process.
 126  * @rst
 127  * .. note:: This function does not return.
 128  * @endrst
 129  */
 130 void vis_die(Vis*, const char *msg, ...) __attribute__((noreturn,format(printf, 2, 3)));
 131
 132 /**
 133  * Temporarily supsend the editor process.
 134  * @rst
 135  * .. note:: This function will generate a ``SIGTSTP`` signal.
 136  * @endrst
 137  **/
 138 void vis_suspend(Vis*);
 139 /**
 140  * Resume editor process.
 141  * @rst
 142  * .. note:: This function is usually called in response to a ``SIGCONT`` signal.
 143  * @endrst
 144  */
 145 void vis_resume(Vis*);
 146 /**
 147  * Inform the editor core that a signal occured.
 148  * @return Whether the signal was handled.
 149  * @rst
 150  * .. note:: Being designed as a library the editor core does *not* register any
 151  *           signal handlers on its own.
 152  * .. note:: The remaining arguments match the prototype of ``sa_sigaction`` as
 153  *           specified in `sigaction(2)`.
 154  * @endrst
 155  */
 156 bool vis_signal_handler(Vis*, int signum, const siginfo_t *siginfo, const void *context);
 157 /**
 158  * Interrupt long running operation.
 159  * @rst
 160  * .. warning:: There is no guarantee that a long running operation is actually
 161  *              interrupted. It is analogous to cooperative multitasking where
 162  *              the operation has to voluntarily yield control.
 163  * .. note:: It is invoked from `vis_signal_handler` when receiving ``SIGINT``.
 164  * @endrst
 165  */
 166 void vis_interrupt(Vis*);
 167 /** Check whether interruption was requested. */
 168 bool vis_interrupt_requested(Vis*);
 169 /**
 170  * @}
 171  * @defgroup vis_draw
 172  * @{
 173  */
 174 /** Draw user interface. */
 175 void vis_draw(Vis*);
 176 /** Completely redraw user interface. */
 177 void vis_redraw(Vis*);
 178 /** Blit user interface state to output device. */
 179 void vis_update(Vis*);
 180 /**
 181  * @}
 182  * @defgroup vis_windows
 183  * @{
 184  */
 185 /**
 186  * Create a new window and load the given file.
 187  * @param filename If ``NULL`` a unamed, empty buffer is created.
 188  * @rst
 189  * .. note:: If the given file name is already opened in another window,
 190  *           the underlying File object is shared.
 191  * .. warning:: This duplication detection is currently based on normalized,
 192  *              absolute file names. TODO: compare inodes instead.
 193  * @endrst
 194  */
 195 bool vis_window_new(Vis*, const char *filename);
 196 /**
 197  * Create a new window associated with a file descriptor.
 198  * @rst
 199  * .. note:: No data is read from `fd`, but write commands without an
 200  *           explicit filename will instead write to the file descriptor.
 201  * @endrst
 202  */
 203 bool vis_window_new_fd(Vis*, int fd);
 204 /** Reload the file currently displayed in the window from disk. */
 205 bool vis_window_reload(Win*);
 206 /** Check whether closing the window would loose unsaved changes. */
 207 bool vis_window_closable(Win*);
 208 /** Close window, redraw user interface. */
 209 void vis_window_close(Win*);
 210 /** Split the window, shares the underlying file object. */
 211 bool vis_window_split(Win*);
 212 /** Change status message of this window. */
 213 void vis_window_status(Win*, const char *status);
 214 void vis_window_draw(Win*);
 215 void vis_window_invalidate(Win*);
 216 /** Focus next window. */
 217 void vis_window_next(Vis*);
 218 /** Focus previous window. */
 219 void vis_window_prev(Vis*);
 220 /** Change currently focused window, receiving user input. */
 221 void vis_window_focus(Win*);
 222 /** Swap location of two windows. */
 223 void vis_window_swap(Win*, Win*);
 224 /** Query window dimension. */
 225 int vis_window_width_get(const Win*);
 226 /** Query window dimension. */
 227 int vis_window_height_get(const Win*);
 228 /**
 229  * @}
 230  * @defgroup vis_info
 231  * @{
 232  */
 233 /**
 234  * Display a user prompt with a certain title.
 235  * @rst
 236  * .. note:: The prompt is currently implemented as a single line height window.
 237  * @endrst
 238  */
 239 void vis_prompt_show(Vis*, const char *title);
 240
 241 /**
 242  * Display a single line message.
 243  * @rst
 244  * .. note:: The message will automatically be hidden upon next input.
 245  * @endrst
 246  */
 247 void vis_info_show(Vis*, const char *msg, ...) __attribute__((format(printf, 2, 3)));
 248 /** Hide informational message. */
 249 void vis_info_hide(Vis*);
 250
 251 /** Display arbitrary long message in a dedicated window. */
 252 void vis_message_show(Vis*, const char *msg);
 253 /** Close message window. */
 254 void vis_message_hide(Vis*);
 255 /**
 256  * @}
 257  * @defgroup vis_changes
 258  * @{
 259  */
 260 void vis_insert(Vis*, size_t pos, const char *data, size_t len);
 261 void vis_delete(Vis*, size_t pos, size_t len);
 262 void vis_replace(Vis*, size_t pos, const char *data, size_t len);
 263 /** Perform insertion at all cursor positions. */
 264 void vis_insert_key(Vis*, const char *data, size_t len);
 265 /**
 266  * Perform character subsitution at all cursor positions.
 267  * @rst
 268  * .. note:: Does not replace new line characters.
 269  * @endrst
 270  */
 271 void vis_replace_key(Vis*, const char *data, size_t len);
 272 /**
 273  * Insert a tab at all cursor positions.
 274  * @rst
 275  * .. note:: Performs tab expansion according to current settings.
 276  * @endrst
 277  */
 278 void vis_insert_tab(Vis*);
 279 /**
 280  * Inserts a new line character at every cursor position.
 281  * @rst
 282  * .. note:: Performs auto indentation according to current settings.
 283  * @endrst
 284  */
 285 void vis_insert_nl(Vis*);
 286
 287 /** @} */
 288 /** Mode specifiers. */
 289 enum VisMode {
 290         VIS_MODE_NORMAL,
 291         VIS_MODE_OPERATOR_PENDING,
 292         VIS_MODE_VISUAL,
 293         VIS_MODE_VISUAL_LINE, /**< Sub mode of `VIS_MODE_VISUAL`. */
 294         VIS_MODE_INSERT,
 295         VIS_MODE_REPLACE, /**< Sub mode of `VIS_MODE_INSERT`. */
 296         VIS_MODE_INVALID,
 297 };
 298
 299 /**
 300  * @defgroup vis_modes
 301  * @{
 302  */
 303 /**
 304  * Switch mode.
 305  * @rst
 306  * .. note:: Will first trigger the leave event of the currently active
 307  *           mode, followed by an enter event of the new mode.
 308  *           No events are emitted, if the specified mode is already active.
 309  * @endrst
 310  */
 311 void vis_mode_switch(Vis*, enum VisMode);
 312 /** Get currently active mode. */
 313 enum VisMode vis_mode_get(Vis*);
 314 /** Translate human readable mode name to constant. */
 315 enum VisMode vis_mode_from(Vis*, const char *name);
 316
 317 /**
 318  * @}
 319  * @defgroup vis_keybind
 320  * @{
 321  */
 322 KeyBinding *vis_binding_new(Vis*);
 323 void vis_binding_free(Vis*, KeyBinding*);
 324
 325 /**
 326  * Set up a key binding.
 327  * @param force Whether an existing mapping should be discarded.
 328  * @param key The symbolic key to map.
 329  * @param binding The binding to map.
 330  * @rst
 331  * .. note:: ``binding->key`` is always ignored in favor of ``key``.
 332  * @endrst
 333  */
 334 bool vis_mode_map(Vis*, enum VisMode, bool force, const char *key, const KeyBinding*);
 335 /** Analogous to `vis_mode_map`, but window specific. */
 336 bool vis_window_mode_map(Win*, enum VisMode, bool force, const char *key, const KeyBinding*);
 337 /** Unmap a symbolic key in a given mode. */
 338 bool vis_mode_unmap(Vis*, enum VisMode, const char *key);
 339 /** Analogous to `vis_mode_unmap`, but window specific. */
 340 bool vis_window_mode_unmap(Win*, enum VisMode, const char *key);
 341 /**
 342  * @}
 343  * @defgroup vis_action
 344  * @{
 345  */
 346 /**
 347  * Create new key action.
 348  * @param name The name to be used as symbolic key when registering.
 349  * @param help Optional single line help text.
 350  * @param func The function implementing the key action logic.
 351  * @param arg Argument passed to function.
 352  */
 353 KeyAction *vis_action_new(Vis*, const char *name, const char *help, KeyActionFunction*, Arg);
 354 void vis_action_free(Vis*, KeyAction*);
 355 /**
 356  * Register key action.
 357  * @rst
 358  * .. note:: Makes the key action available under the pseudo key name specified
 359  *           in ``keyaction->name``.
 360  * @endrst
 361  */
 362 bool vis_action_register(Vis*, const KeyAction*);
 363
 364 /**
 365  * @}
 366  * @defgroup vis_keymap
 367  * @{
 368  */
 369
 370 /** Add a key translation. */
 371 bool vis_keymap_add(Vis*, const char *key, const char *mapping);
 372 /** Temporarily disable the keymap for the next key press. */
 373 void vis_keymap_disable(Vis*);
 374
 375 /** @} */
 376 /** Operator specifiers. */
 377 enum VisOperator {
 378         VIS_OP_DELETE,
 379         VIS_OP_CHANGE,
 380         VIS_OP_YANK,
 381         VIS_OP_PUT_AFTER,
 382         VIS_OP_SHIFT_RIGHT,
 383         VIS_OP_SHIFT_LEFT,
 384         VIS_OP_JOIN,
 385         VIS_OP_MODESWITCH,
 386         VIS_OP_REPLACE,
 387         VIS_OP_CURSOR_SOL,
 388         VIS_OP_CASE_SWAP,
 389         VIS_OP_FILTER,
 390         VIS_OP_INVALID, /* denotes the end of the "real" operators */
 391         /* pseudo operators: keep them at the end to save space in array definition */
 392         VIS_OP_CASE_LOWER,
 393         VIS_OP_CASE_UPPER,
 394         VIS_OP_CURSOR_EOL,
 395         VIS_OP_PUT_AFTER_END,
 396         VIS_OP_PUT_BEFORE,
 397         VIS_OP_PUT_BEFORE_END,
 398         VIS_OP_LAST, /* has to be last enum member */
 399 };
 400
 401 /**
 402  * @defgroup vis_operators
 403  * @{
 404  */
 405 typedef struct OperatorContext OperatorContext;
 406
 407 /**
 408  * An operator performs a certain function on a given text range.
 409  * @rst
 410  * .. note:: The operator must return the new cursor position or ``EPOS`` if
 411  *           the cursor should be disposed.
 412  * .. note:: The last used operator can be repeated using `vis_repeat`.
 413  * @endrst
 414  */
 415 typedef size_t (VisOperatorFunction)(Vis*, Text*, OperatorContext*);
 416
 417 /**
 418  * Register an operator.
 419  * @return Operator ID. Negative values indicate an error, positive ones can be
 420  *         used with `vis_operator`.
 421  */
 422 int vis_operator_register(Vis*, VisOperatorFunction*, void *context);
 423
 424 /**
 425  * Set operator to execute.
 426  *
 427  * Has immediate effect if:
 428  *  - A visual mode is active.
 429  *  - The same operator was already set (range will be the current line).
 430  *
 431  * Otherwise the operator will be executed on the range determinded by:
 432  *  - A motion (see `vis_motion`).
 433  *  - A text object (`vis_textobject`).
 434  *
 435  * The expected varying arguments are:
 436  *
 437  *  - `VIS_OP_FILTER`     a char pointer referring to the command to run.
 438  *  - `VIS_OP_JOIN`       a char pointer referring to the text to insert between lines.
 439  *  - `VIS_OP_MODESWITCH` an ``enum VisMode`` indicating the mode to switch to.
 440  *  - `VIS_OP_REPLACE`    a char pointer reffering to the replacement character.
 441  */
 442 bool vis_operator(Vis*, enum VisOperator, ...);
 443
 444 /** Repeat last operator, possibly with a new count if one was provided in the meantime. */
 445 void vis_repeat(Vis*);
 446
 447 /** Cancel pending operator, reset count, motion, text object, register etc. */
 448 void vis_cancel(Vis*);
 449
 450 /** @} */
 451 /** Motion specifiers. */
 452 enum VisMotion {
 453         VIS_MOVE_LINE_DOWN,
 454         VIS_MOVE_LINE_UP,
 455         VIS_MOVE_SCREEN_LINE_UP,
 456         VIS_MOVE_SCREEN_LINE_DOWN,
 457         VIS_MOVE_SCREEN_LINE_BEGIN,
 458         VIS_MOVE_SCREEN_LINE_MIDDLE,
 459         VIS_MOVE_SCREEN_LINE_END,
 460         VIS_MOVE_LINE_PREV,
 461         VIS_MOVE_LINE_BEGIN,
 462         VIS_MOVE_LINE_START,
 463         VIS_MOVE_LINE_FINISH,
 464         VIS_MOVE_LINE_LASTCHAR,
 465         VIS_MOVE_LINE_END,
 466         VIS_MOVE_LINE_NEXT,
 467         VIS_MOVE_LINE,
 468         VIS_MOVE_COLUMN,
 469         VIS_MOVE_CHAR_PREV,
 470         VIS_MOVE_CHAR_NEXT,
 471         VIS_MOVE_LINE_CHAR_PREV,
 472         VIS_MOVE_LINE_CHAR_NEXT,
 473         VIS_MOVE_CODEPOINT_PREV,
 474         VIS_MOVE_CODEPOINT_NEXT,
 475         VIS_MOVE_WORD_NEXT,
 476         VIS_MOVE_WORD_START_NEXT,
 477         VIS_MOVE_WORD_END_PREV,
 478         VIS_MOVE_WORD_END_NEXT,
 479         VIS_MOVE_WORD_START_PREV,
 480         VIS_MOVE_LONGWORD_NEXT,
 481         VIS_MOVE_LONGWORD_START_PREV,
 482         VIS_MOVE_LONGWORD_START_NEXT,
 483         VIS_MOVE_LONGWORD_END_PREV,
 484         VIS_MOVE_LONGWORD_END_NEXT,
 485         VIS_MOVE_SENTENCE_PREV,
 486         VIS_MOVE_SENTENCE_NEXT,
 487         VIS_MOVE_PARAGRAPH_PREV,
 488         VIS_MOVE_PARAGRAPH_NEXT,
 489         VIS_MOVE_FUNCTION_START_PREV,
 490         VIS_MOVE_FUNCTION_START_NEXT,
 491         VIS_MOVE_FUNCTION_END_PREV,
 492         VIS_MOVE_FUNCTION_END_NEXT,
 493         VIS_MOVE_BLOCK_START,
 494         VIS_MOVE_BLOCK_END,
 495         VIS_MOVE_PARENTHESE_START,
 496         VIS_MOVE_PARENTHESE_END,
 497         VIS_MOVE_BRACKET_MATCH,
 498         VIS_MOVE_LEFT_TO,
 499         VIS_MOVE_RIGHT_TO,
 500         VIS_MOVE_LEFT_TILL,
 501         VIS_MOVE_RIGHT_TILL,
 502         VIS_MOVE_FILE_BEGIN,
 503         VIS_MOVE_FILE_END,
 504         VIS_MOVE_MARK,
 505         VIS_MOVE_MARK_LINE,
 506         VIS_MOVE_SEARCH_WORD_FORWARD,
 507         VIS_MOVE_SEARCH_WORD_BACKWARD,
 508         VIS_MOVE_SEARCH_REPEAT_FORWARD,
 509         VIS_MOVE_SEARCH_REPEAT_BACKWARD,
 510         VIS_MOVE_WINDOW_LINE_TOP,
 511         VIS_MOVE_WINDOW_LINE_MIDDLE,
 512         VIS_MOVE_WINDOW_LINE_BOTTOM,
 513         VIS_MOVE_CHANGELIST_NEXT,
 514         VIS_MOVE_CHANGELIST_PREV,
 515         VIS_MOVE_JUMPLIST_NEXT,
 516         VIS_MOVE_JUMPLIST_PREV,
 517         VIS_MOVE_NOP,
 518         VIS_MOVE_PERCENT,
 519         VIS_MOVE_BYTE,
 520         VIS_MOVE_BYTE_LEFT,
 521         VIS_MOVE_BYTE_RIGHT,
 522         VIS_MOVE_INVALID, /* denotes the end of the "real" motions */
 523         /* pseudo motions: keep them at the end to save space in array definition */
 524         VIS_MOVE_TOTILL_REPEAT,
 525         VIS_MOVE_TOTILL_REVERSE,
 526         VIS_MOVE_SEARCH_FORWARD,
 527         VIS_MOVE_SEARCH_BACKWARD,
 528         VIS_MOVE_SEARCH_REPEAT,
 529         VIS_MOVE_SEARCH_REPEAT_REVERSE,
 530         VIS_MOVE_LAST, /* denotes the end of all motions */
 531 };
 532
 533 /**
 534  * @defgroup vis_motions
 535  * @{
 536  */
 537 /**
 538  * Set motion to perform.
 539  *
 540  * The following motions take an additional argument:
 541  *
 542  *  - `VIS_MOVE_SEARCH_FORWARD` and `VIS_MOVE_SEARCH_BACKWARD`
 543  *
 544  *     The search pattern as ``const char *``.
 545  *
 546  *  - ``VIS_MOVE_{LEFT,RIGHT}_{TO,TILL}``
 547  *
 548  *     The character to search for as ``const char *``.
 549  *
 550  *  - `VIS_MOVE_MARK` and `VIS_MOVE_MARK_LINE`
 551  *
 552  *     A valid ``enum VisMark``.
 553  */
 554 bool vis_motion(Vis*, enum VisMotion, ...);
 555
 556 enum VisMotionType {
 557         VIS_MOTIONTYPE_LINEWISE  = 1 << 0,
 558         VIS_MOTIONTYPE_CHARWISE  = 1 << 1,
 559 };
 560
 561 /** Force currently specified motion to behave in line or character wise mode. */
 562 void vis_motion_type(Vis *vis, enum VisMotionType);
 563
 564 /**
 565  * Motions take a starting position and transform it to an end position.
 566  * @rst
 567  * .. note:: Should a motion not be possible, the original position must be returned.
 568  *           TODO: we might want to change that to ``EPOS``?
 569  * @endrst
 570  */
 571 typedef size_t (VisMotionFunction)(Vis*, Win*, void *context, size_t pos);
 572
 573 /**
 574  * Register a motion function.
 575  * @return Motion ID. Negative values indicate an error, positive ones can be
 576  *         used with `vis_motion`.
 577  */
 578 int vis_motion_register(Vis*, enum VisMotionType, void *context, VisMotionFunction*);
 579
 580 /**
 581  * @}
 582  * @defgroup vis_count
 583  * @{
 584  */
 585 /** No count was specified. */
 586 #define VIS_COUNT_UNKNOWN (-1)
 587 /** Get count, might return `VIS_COUNT_UNKNOWN`. */
 588 int vis_count_get(Vis*);
 589 /** Get count, if none was specified, return ``def``. */
 590 int vis_count_get_default(Vis*, int def);
 591 /** Set a count. */
 592 void vis_count_set(Vis*, int count);
 593
 594 typedef struct {
 595         Vis *vis;
 596         int iteration;
 597         int count;
 598 } VisCountIterator;
 599
 600 /** Get iterator initialized with current count or ``def`` if not specified. */
 601 VisCountIterator vis_count_iterator_get(Vis*, int def);
 602 /** Get iterator initialized with a count value. */
 603 VisCountIterator vis_count_iterator_init(Vis*, int count);
 604 /**
 605  * Increment iterator counter.
 606  * @return Whether iteration should continue.
 607  * @rst
 608  * .. note:: Terminates iteration if the edtior was
 609  *           `interrupted <vis_interrupt>`_ in the meantime.
 610  * @endrst
 611  */
 612 bool vis_count_iterator_next(VisCountIterator*);
 613
 614 /** @} */
 615 /** Text object specifier. */
 616 enum VisTextObject {
 617         VIS_TEXTOBJECT_INNER_WORD,
 618         VIS_TEXTOBJECT_OUTER_WORD,
 619         VIS_TEXTOBJECT_INNER_LONGWORD,
 620         VIS_TEXTOBJECT_OUTER_LONGWORD,
 621         VIS_TEXTOBJECT_SENTENCE,
 622         VIS_TEXTOBJECT_PARAGRAPH,
 623         VIS_TEXTOBJECT_OUTER_SQUARE_BRACKET,
 624         VIS_TEXTOBJECT_INNER_SQUARE_BRACKET,
 625         VIS_TEXTOBJECT_OUTER_CURLY_BRACKET,
 626         VIS_TEXTOBJECT_INNER_CURLY_BRACKET,
 627         VIS_TEXTOBJECT_OUTER_ANGLE_BRACKET,
 628         VIS_TEXTOBJECT_INNER_ANGLE_BRACKET,
 629         VIS_TEXTOBJECT_OUTER_PARANTHESE,
 630         VIS_TEXTOBJECT_INNER_PARANTHESE,
 631         VIS_TEXTOBJECT_OUTER_QUOTE,
 632         VIS_TEXTOBJECT_INNER_QUOTE,
 633         VIS_TEXTOBJECT_OUTER_SINGLE_QUOTE,
 634         VIS_TEXTOBJECT_INNER_SINGLE_QUOTE,
 635         VIS_TEXTOBJECT_OUTER_BACKTICK,
 636         VIS_TEXTOBJECT_INNER_BACKTICK,
 637         VIS_TEXTOBJECT_OUTER_ENTIRE,
 638         VIS_TEXTOBJECT_INNER_ENTIRE,
 639         VIS_TEXTOBJECT_OUTER_LINE,
 640         VIS_TEXTOBJECT_INNER_LINE,
 641         VIS_TEXTOBJECT_INDENTATION,
 642         VIS_TEXTOBJECT_SEARCH_FORWARD,
 643         VIS_TEXTOBJECT_SEARCH_BACKWARD,
 644         VIS_TEXTOBJECT_INVALID,
 645 };
 646
 647 /**
 648  * @defgroup vis_textobjs
 649  * @{
 650  */
 651
 652 /**
 653  * Text objects take a starting position and return a text range.
 654  * @rst
 655  * .. note:: The originating position does not necessarily have to be contained in
 656  *           the resulting range.
 657  * @endrst
 658  */
 659 typedef Filerange (VisTextObjectFunction)(Vis*, Win*, void *context, size_t pos);
 660
 661 /**
 662  * Register a new text object.
 663  * @return Text object ID. Negative values indicate an error, positive ones can be
 664  *         used with `vis_textobject`.
 665  */
 666 int vis_textobject_register(Vis*, int type, void *data, VisTextObjectFunction*);
 667
 668 /** Set text object to use. */
 669 bool vis_textobject(Vis*, enum VisTextObject);
 670
 671 /** @} */
 672 /** Mark specifiers. */
 673 enum VisMark {
 674         VIS_MARK_DEFAULT,
 675         VIS_MARK_SELECTION,
 676         VIS_MARK_a, VIS_MARK_b, VIS_MARK_c, VIS_MARK_d, VIS_MARK_e,
 677         VIS_MARK_f, VIS_MARK_g, VIS_MARK_h, VIS_MARK_i, VIS_MARK_j,
 678         VIS_MARK_k, VIS_MARK_l, VIS_MARK_m, VIS_MARK_n, VIS_MARK_o,
 679         VIS_MARK_p, VIS_MARK_q, VIS_MARK_r, VIS_MARK_s, VIS_MARK_t,
 680         VIS_MARK_u, VIS_MARK_v, VIS_MARK_w, VIS_MARK_x, VIS_MARK_y,
 681         VIS_MARK_z,
 682         VIS_MARK_INVALID,     /* has to be the last enum member */
 683 };
 684
 685 /**
 686  * @}
 687  * @defgroup vis_marks
 688  * @{
 689  */
 690 /** Translate single character mark name to corresponding constant. */
 691 enum VisMark vis_mark_from(Vis*, char mark);
 692 /**
 693  * Set a mark.
 694  * @rst
 695  * .. note:: The same semantics as for `text_mark_set` apply.
 696  * @endrst
 697  */
 698 void vis_mark_set(Vis*, enum VisMark mark, size_t pos);
 699
 700 /** @} */
 701 /** Register specifiers. */
 702 enum VisRegister {
 703         VIS_REG_DEFAULT,    /* used when no other register is specified */
 704         VIS_REG_ZERO,       /* yank register */
 705         VIS_REG_AMPERSAND,  /* last regex match */
 706         VIS_REG_1,          /* 1-9 last sub-expression matches */
 707         VIS_REG_2,
 708         VIS_REG_3,
 709         VIS_REG_4,
 710         VIS_REG_5,
 711         VIS_REG_6,
 712         VIS_REG_7,
 713         VIS_REG_8,
 714         VIS_REG_9,
 715         VIS_REG_BLACKHOLE,  /* /dev/null register */
 716         VIS_REG_CLIPBOARD,  /* system clipboard register */
 717         VIS_REG_DOT,        /* last inserted text, copy of VIS_MACRO_OPERATOR */
 718         VIS_REG_SEARCH,     /* last used search pattern "/ */
 719         VIS_REG_COMMAND,    /* last used :-command ": */
 720         VIS_REG_SHELL,      /* last used shell command given to either <, >, |, or ! */
 721         VIS_REG_NUMBER,     /* cursor number */
 722         VIS_REG_SELECTION, /* last used selections */
 723         VIS_REG_a, VIS_REG_b, VIS_REG_c, VIS_REG_d, VIS_REG_e,
 724         VIS_REG_f, VIS_REG_g, VIS_REG_h, VIS_REG_i, VIS_REG_j,
 725         VIS_REG_k, VIS_REG_l, VIS_REG_m, VIS_REG_n, VIS_REG_o,
 726         VIS_REG_p, VIS_REG_q, VIS_REG_r, VIS_REG_s, VIS_REG_t,
 727         VIS_REG_u, VIS_REG_v, VIS_REG_w, VIS_REG_x, VIS_REG_y,
 728         VIS_REG_z,
 729         VIS_MACRO_OPERATOR, /* records entered keys after an operator */
 730         VIS_REG_PROMPT, /* internal register which shadows DEFAULT in PROMPT mode */
 731         VIS_REG_INVALID, /* has to be the last 'real' register */
 732         VIS_REG_A, VIS_REG_B, VIS_REG_C, VIS_REG_D, VIS_REG_E,
 733         VIS_REG_F, VIS_REG_G, VIS_REG_H, VIS_REG_I, VIS_REG_J,
 734         VIS_REG_K, VIS_REG_L, VIS_REG_M, VIS_REG_N, VIS_REG_O,
 735         VIS_REG_P, VIS_REG_Q, VIS_REG_R, VIS_REG_S, VIS_REG_T,
 736         VIS_REG_U, VIS_REG_V, VIS_REG_W, VIS_REG_X, VIS_REG_Y,
 737         VIS_REG_Z,
 738         VIS_MACRO_LAST_RECORDED, /* pseudo macro referring to last recorded one */
 739 };
 740
 741 /**
 742  * @defgroup vis_registers
 743  * @{
 744  */
 745 /** Translate single character register name to corresponding constant. */
 746 enum VisRegister vis_register_from(Vis*, char reg);
 747 /**
 748  * Specify register to use.
 749  * @rst
 750  * .. note:: If none is specified `VIS_REG_DEFAULT` will be used.
 751  * @endrst
 752  */
 753 void vis_register(Vis*, enum VisRegister);
 754 enum VisRegister vis_register_used(Vis*);
 755 /** Get register content. */
 756 const char *vis_register_get(Vis*, enum VisRegister, size_t *len);
 757 const char *vis_register_slot_get(Vis*, enum VisRegister, size_t slot, size_t *len);
 758 /** Set register content. */
 759 bool vis_register_put(Vis*, enum VisRegister, const char *data, size_t len);
 760 bool vis_register_slot_put(Vis*, enum VisRegister, size_t slot, const char *data, size_t len);
 761 /**
 762  * Store a set of ``Filerange``s in a register.
 763  *
 764  * @param id The register to use.
 765  * @param sel The array containing the file ranges.
 766  */
 767 void vis_register_selections_set(Vis*, enum VisRegister id, Array *sel);
 768 /**
 769  * Get an array of file ranges stored in the register.
 770  *
 771  * @rst
 772  * .. warning:: The caller must eventually free the Array by calling
 773  *              ``array_release``.
 774  * @endrst
 775  */
 776 Array vis_register_selections_get(Vis*, enum VisRegister id);
 777
 778 /**
 779  * @}
 780  * @defgroup vis_macros
 781  * @{
 782  */
 783 /**
 784  * Start recording a macro.
 785  * @rst
 786  * .. note:: Fails if a recording is already ongoing.
 787  * @endrst
 788  */
 789 bool vis_macro_record(Vis*, enum VisRegister);
 790 /** Stop recording, fails if there is nothing to stop. */
 791 bool vis_macro_record_stop(Vis*);
 792 /** Check whether a recording is currently ongoing. */
 793 bool vis_macro_recording(Vis*);
 794 /**
 795  * Replay a macro.
 796  * @rst
 797  * .. note:: A macro currently being recorded can not be replayed.
 798  * @endrst
 799  */
 800 bool vis_macro_replay(Vis*, enum VisRegister);
 801
 802 /**
 803  * @}
 804  * @defgroup vis_cmds
 805  * @{
 806  */
 807
 808 /** Execute a ``:``-command. */
 809 bool vis_cmd(Vis*, const char *cmd);
 810
 811 /** Command handler function. */
 812 typedef bool (VisCommandFunction)(Vis*, Win*, void *data, bool force,
 813         const char *argv[], Selection*, Filerange*);
 814 /**
 815  * Register new ``:``-command.
 816  * @param name The command name.
 817  * @param help Optional single line help text.
 818  * @param context User supplied context pointer passed to the handler function.
 819  * @param func The function implementing the command logic.
 820  * @rst
 821  * .. note:: Any unique prefix of the command name will invoke the command.
 822  * @endrst
 823  */
 824 bool vis_cmd_register(Vis*, const char *name, const char *help, void *context, VisCommandFunction*);
 825
 826 /** Unregister ``:``-command. */
 827 bool vis_cmd_unregister(Vis*, const char *name);
 828
 829 /**
 830  * @}
 831  * @defgroup vis_options
 832  * @{
 833  */
 834 /** Option properties. */
 835 enum VisOption {
 836         VIS_OPTION_TYPE_BOOL = 1 << 0,
 837         VIS_OPTION_TYPE_STRING = 1 << 1,
 838         VIS_OPTION_TYPE_NUMBER = 1 << 2,
 839         VIS_OPTION_VALUE_OPTIONAL = 1 << 3,
 840         VIS_OPTION_NEED_WINDOW = 1 << 4,
 841 };
 842
 843 /**
 844  * Option handler function.
 845  * @param win The window to which option should apply, might be ``NULL``.
 846  * @param context User provided context pointer as given to `vis_option_register`.
 847  * @param force Whether the option was specfied with a bang ``!``.
 848  * @param name Name of option which was set.
 849  * @param arg The new option value.
 850  */
 851 typedef bool (VisOptionFunction)(Vis*, Win*, void *context, bool toggle,
 852                                  enum VisOption, const char *name, Arg *value);
 853
 854 /**
 855  * Register a new ``:set`` option.
 856  * @param names A ``NULL`` terminated array of option names.
 857  * @param option Option properties.
 858  * @param func The function handling the option.
 859  * @param context User supplied context pointer passed to the handler function.
 860  * @param help Optional single line help text.
 861  * @rst
 862  * .. note:: Fails if any of the given option names is already registered.
 863  * @endrst
 864  */
 865 bool vis_option_register(Vis*, const char *names[], enum VisOption,
 866                          VisOptionFunction*, void *context, const char *help);
 867 /**
 868  * Unregister an existing ``:set`` option.
 869  * @rst
 870  * .. note:: Also unregisters all aliases as given to `vis_option_register`.
 871  * @endrst
 872  */
 873 bool vis_option_unregister(Vis*, const char *name);
 874
 875 /** Execute any kind (``:``, ``?``, ``/``) of prompt command */
 876 bool vis_prompt_cmd(Vis*, const char *cmd);
 877
 878 /**
 879  * Pipe a given file range to an external process.
 880  *
 881  * If the range is invalid 'interactive' mode is enabled, meaning that
 882  * stdin and stderr are passed through the underlying command, stdout
 883  * points to vis' stderr.
 884  *
 885  * If ``argv`` contains only one non-NULL element the command is executed
 886  * through an intermediate shell (using ``/bin/sh -c argv[0]``) that is
 887  * argument expansion is performed by the shell. Otherwise the argument
 888  * list will be passed unmodified to ``execvp(argv[0], argv)``.
 889  *
 890  * If the ``read_stdout`` and ``read_stderr`` callbacks are non-NULL they
 891  * will be invoked when output from the forked process is available.
 892  *
 893  * @rst
 894  * .. warning:: The editor core is blocked until this function returns.
 895  * @endrst
 896  *
 897  * @return The exit status of the forked process.
 898  */
 899 int vis_pipe(Vis*, File*, Filerange*, const char *argv[],
 900         void *stdout_context, ssize_t (*read_stdout)(void *stdout_context, char *data, size_t len),
 901         void *stderr_context, ssize_t (*read_stderr)(void *stderr_context, char *data, size_t len));
 902
 903 /**
 904  * Pipe a Filerange to an external process, return its exit status and capture
 905  * everything that is written to stdout/stderr.
 906  * @param argv Argument list, must be ``NULL`` terminated.
 907  * @param out Data written to ``stdout``, will be ``NUL`` terminated.
 908  * @param err Data written to ``stderr``, will be ``NUL`` terminated.
 909  * @rst
 910  * .. warning:: The pointers stored in ``out`` and ``err`` need to be `free(3)`-ed
 911  *              by the caller.
 912  * @endrst
 913  */
 914 int vis_pipe_collect(Vis*, File*, Filerange*, const char *argv[], char **out, char **err);
 915
 916 /**
 917  * @}
 918  * @defgroup vis_keys
 919  * @{
 920  */
 921 /**
 922  * Advance to the start of the next symbolic key.
 923  *
 924  * Given the start of a symbolic key, returns a pointer to the start of the one
 925  * immediately following it.
 926  */
 927 const char *vis_keys_next(Vis*, const char *keys);
 928 /** Convert next symbolic key to an Unicode code point, returns ``-1`` for unknown keys. */
 929 long vis_keys_codepoint(Vis*, const char *keys);
 930 /**
 931  * Convert next symbolic key to a UTF-8 sequence.
 932  * @return Whether conversion was successful, if not ``utf8`` is left unmodified.
 933  * @rst
 934  * .. note:: Guarantees that ``utf8`` is NUL terminated on success.
 935  * @endrst
 936  */
 937 bool vis_keys_utf8(Vis*, const char *keys, char utf8[static UTFmax+1]);
 938 /** Process symbolic keys as if they were user originated input. */
 939 void vis_keys_feed(Vis*, const char *keys);
 940 /**
 941  * @}
 942  * @defgroup vis_misc
 943  * @{
 944  */
 945
 946 /**
 947  * Get a regex object matching pattern.
 948  * @param regex The regex pattern to compile, if ``NULL`` the most recently used
 949  *        one is substituted.
 950  * @return A Regex object or ``NULL`` in case of an error.
 951  * @rst
 952  * .. warning:: The caller must free the regex object using `text_regex_free`.
 953  * @endrst
 954  */
 955 Regex *vis_regex(Vis*, const char *pattern);
 956
 957 /**
 958  * Take an undo snaphost to which we can later revert to.
 959  * @rst
 960  * .. note:: Does nothing when invoked while replaying a macro.
 961  * @endrst
 962  */
 963 void vis_file_snapshot(Vis*, File*);
 964 /** @} */
 965
 966 /* TODO: expose proper API to iterate through files etc */
 967 Text *vis_text(Vis*);
 968 View *vis_view(Vis*);
 969 Win *vis_window(Vis*);
 970
 971 /* Get value of autoindent */
 972 bool vis_get_autoindent(const Vis*);
 973
 974 #endif