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
  16 typedef struct {
  17         void (*vis_init)(Vis*);
  18         void (*vis_start)(Vis*);
  19         void (*vis_quit)(Vis*);
  20         void (*file_open)(Vis*, File*);
  21         void (*file_save)(Vis*, File*);
  22         void (*file_close)(Vis*, File*);
  23         void (*win_open)(Vis*, Win*);
  24         void (*win_close)(Vis*, Win*);
  25 } VisEvent;
  26
  27 typedef union { /* various types of arguments passed to key action functions */
  28         bool b;
  29         int i;
  30         size_t u;
  31         const char *s;
  32         const void *v;
  33         void (*w)(View*);
  34         void (*f)(Vis*);
  35 } Arg;
  36
  37 typedef struct {             /* a KeyAction can be bound to a key binding */
  38         const char *name;    /* aliases can refer to this action by means of a pseudo key <name> */
  39         const char *help;    /* short (one line) human readable description, displayed by :help */
  40         /* action handling function, keys refers to the next characters found in the input queue
  41          * (an empty string "" indicates an empty queue). The return value of func has to point to
  42          * the first non consumed key. Returning NULL indicates that not enough keys were available
  43          * to complete the action. In this case the function will be called again when more input
  44          * becomes available */
  45         const char* (*func)(Vis*, const char *keys, const Arg*);
  46         Arg arg;       /* additional arguments which will be passed as to func */
  47 } KeyAction;
  48
  49 typedef struct {           /* a key binding either refers to an action or an alias */
  50         const char *key;   /* symbolic key to trigger this binding */
  51         const KeyAction *action; /* action to launch upon triggering this binding */
  52         const char *alias; /* replaces key with alias in the input queue */
  53 } KeyBinding;
  54
  55 /* creates a new editor instance using the specified user interface */
  56 Vis *vis_new(Ui*, VisEvent*);
  57 /* frees all resources associated with this editor instance, terminates ui */
  58 void vis_free(Vis*);
  59 /* instructs the user interface to draw to an internal buffer */
  60 void vis_draw(Vis*);
  61 void vis_redraw(Vis*);
  62 /* flushes the state of the internal buffer to the output device */
  63 void vis_update(Vis*);
  64 /* temporarily supsend the editor process, resumes upon receiving SIGCONT */
  65 void vis_suspend(Vis*);
  66
  67 /* creates a new window, and loads the given file. if filename is NULL
  68  * an unamed / empty buffer is created. If the given file is already opened
  69  * in another window, share the underlying text that is changes will be
  70  * visible in both windows */
  71 bool vis_window_new(Vis*, const char *filename);
  72 /* reload the file currently displayed in the window from disk */
  73 bool vis_window_reload(Win*);
  74 /* check whether closing the window would loose unsaved changes */
  75 bool vis_window_closable(Win*);
  76 /* close window, redraw user interface */
  77 void vis_window_close(Win*);
  78 /* split the given window. changes to the displayed text will be reflected
  79  * in both windows */
  80 bool vis_window_split(Win*);
  81 /* change file name associated with this window, affects syntax coloring */
  82 void vis_window_name(Win*, const char *filename);
  83 /* focus the next / previous window */
  84 void vis_window_next(Vis*);
  85 void vis_window_prev(Vis*);
  86 /* change currently focused window, receiving user input */
  87 void vis_window_focus(Win*);
  88 /* swap location of two windows */
  89 void vis_window_swap(Win*, Win*);
  90 /* display a user prompt with a certain title and default text */
  91 void vis_prompt_show(Vis*, const char *title);
  92
  93 /* display a one line message to the user, will be hidden upon keypress */
  94 void vis_info_show(Vis*, const char *msg, ...);
  95 void vis_info_hide(Vis*);
  96
  97 /* display an arbitrary long message in a special window/file */
  98 void vis_message_show(Vis*, const char *msg);
  99 void vis_message_hide(Vis*);
 100
 101 /* these function operate on the currently focused window but make sure
 102  * that all windows which show the affected region are redrawn too. */
 103 void vis_insert(Vis*, size_t pos, const char *data, size_t len);
 104 void vis_delete(Vis*, size_t pos, size_t len);
 105 void vis_replace(Vis*, size_t pos, const char *data, size_t len);
 106 /* these functions perform their operation at the current cursor position(s) */
 107 void vis_insert_key(Vis*, const char *data, size_t len);
 108 void vis_replace_key(Vis*, const char *data, size_t len);
 109 /* inserts a tab (peforms tab expansion based on current editing settings),
 110  * at all current cursor positions */
 111 void vis_insert_tab(Vis*);
 112 /* inserts a new line sequence (depending on the file type this might be \n or
 113  * \r\n) at all current cursor positions */
 114 void vis_insert_nl(Vis*);
 115
 116 /* processes the given command line arguments and starts the main loop, won't
 117  * return until editing session is terminated */
 118 int vis_run(Vis*, int argc, char *argv[]);
 119 /* terminate editing session, given status will be the return value of vis_run */
 120 void vis_exit(Vis*, int status);
 121 /* emergency exit, print given message, perform minimal ui cleanup and exit process */
 122 void vis_die(Vis*, const char *msg, ...) __attribute__((noreturn));
 123
 124 enum VisMode {
 125         VIS_MODE_NORMAL,
 126         VIS_MODE_OPERATOR_PENDING,
 127         VIS_MODE_VISUAL,
 128         VIS_MODE_VISUAL_LINE,
 129         VIS_MODE_INSERT,
 130         VIS_MODE_REPLACE,
 131         VIS_MODE_INVALID,
 132 };
 133
 134 void vis_mode_switch(Vis*, enum VisMode);
 135 /* in the specified mode: map a given key to a binding (binding->key is ignored),
 136  * fails if key is already mapped */
 137 bool vis_mode_map(Vis*, enum VisMode, const char *key, const KeyBinding*);
 138 bool vis_window_mode_map(Win*, enum VisMode, const char *key, const KeyBinding*);
 139 /* in the specified mode: unmap a given key, fails if the key is not currently mapped */
 140 bool vis_mode_unmap(Vis*, enum VisMode, const char *key);
 141 bool vis_window_mode_unmap(Win*, enum VisMode, const char *key);
 142 /* get the current mode's status line indicator */
 143 const char *vis_mode_status(Vis*);
 144 /* associates the special pseudo key <keyaction->name> with the given key action.
 145  * after successfull registration the pseudo key can be used key binding aliases */
 146 bool vis_action_register(Vis*, const KeyAction*);
 147 /* add a key mapping which is applied for all modes except insert/replace
 148  * before any key bindings are evaluated */
 149 bool vis_keymap_add(Vis*, const char *key, const char *mapping);
 150
 151 enum VisOperator {
 152         VIS_OP_DELETE,
 153         VIS_OP_CHANGE,
 154         VIS_OP_YANK,
 155         VIS_OP_PUT_AFTER,
 156         VIS_OP_SHIFT_RIGHT,
 157         VIS_OP_SHIFT_LEFT,
 158         VIS_OP_JOIN,
 159         VIS_OP_INSERT,
 160         VIS_OP_REPLACE,
 161         VIS_OP_CURSOR_SOL,
 162         VIS_OP_CASE_SWAP,
 163         VIS_OP_FILTER,
 164         VIS_OP_INVALID, /* denotes the end of the "real" operators */
 165         /* pseudo operators: keep them at the end to save space in array definition */
 166         VIS_OP_CASE_LOWER,
 167         VIS_OP_CASE_UPPER,
 168         VIS_OP_CURSOR_EOL,
 169         VIS_OP_PUT_AFTER_END,
 170         VIS_OP_PUT_BEFORE,
 171         VIS_OP_PUT_BEFORE_END,
 172 };
 173
 174 /* set operator to execute, has immediate effect if
 175  *  - a visual mode is active
 176  *  - the same operator was already set (range will be the current line)
 177  * otherwise waits until a range is determinded i.e.
 178  *  - a motion is provided (see vis_motion)
 179  *  - a text object is provided (vis_textobject)
 180  *
 181  * the expected varying arguments are as follows:
 182  *
 183  *  - VIS_OP_FILTER     a char pointer referring to the command to run
 184  */
 185 bool vis_operator(Vis*, enum VisOperator, ...);
 186
 187 enum VisMotion {
 188         VIS_MOVE_LINE_DOWN,
 189         VIS_MOVE_LINE_UP,
 190         VIS_MOVE_SCREEN_LINE_UP,
 191         VIS_MOVE_SCREEN_LINE_DOWN,
 192         VIS_MOVE_SCREEN_LINE_BEGIN,
 193         VIS_MOVE_SCREEN_LINE_MIDDLE,
 194         VIS_MOVE_SCREEN_LINE_END,
 195         VIS_MOVE_LINE_PREV,
 196         VIS_MOVE_LINE_BEGIN,
 197         VIS_MOVE_LINE_START,
 198         VIS_MOVE_LINE_FINISH,
 199         VIS_MOVE_LINE_LASTCHAR,
 200         VIS_MOVE_LINE_END,
 201         VIS_MOVE_LINE_NEXT,
 202         VIS_MOVE_LINE,
 203         VIS_MOVE_COLUMN,
 204         VIS_MOVE_CHAR_PREV,
 205         VIS_MOVE_CHAR_NEXT,
 206         VIS_MOVE_LINE_CHAR_PREV,
 207         VIS_MOVE_LINE_CHAR_NEXT,
 208         VIS_MOVE_WORD_START_NEXT,
 209         VIS_MOVE_WORD_END_PREV,
 210         VIS_MOVE_WORD_END_NEXT,
 211         VIS_MOVE_WORD_START_PREV,
 212         VIS_MOVE_LONGWORD_START_PREV,
 213         VIS_MOVE_LONGWORD_START_NEXT,
 214         VIS_MOVE_LONGWORD_END_PREV,
 215         VIS_MOVE_LONGWORD_END_NEXT,
 216         VIS_MOVE_SENTENCE_PREV,
 217         VIS_MOVE_SENTENCE_NEXT,
 218         VIS_MOVE_PARAGRAPH_PREV,
 219         VIS_MOVE_PARAGRAPH_NEXT,
 220         VIS_MOVE_FUNCTION_START_PREV,
 221         VIS_MOVE_FUNCTION_START_NEXT,
 222         VIS_MOVE_FUNCTION_END_PREV,
 223         VIS_MOVE_FUNCTION_END_NEXT,
 224         VIS_MOVE_BLOCK_START,
 225         VIS_MOVE_BLOCK_END,
 226         VIS_MOVE_PARENTHESE_START,
 227         VIS_MOVE_PARENTHESE_END,
 228         VIS_MOVE_BRACKET_MATCH,
 229         VIS_MOVE_LEFT_TO,
 230         VIS_MOVE_RIGHT_TO,
 231         VIS_MOVE_LEFT_TILL,
 232         VIS_MOVE_RIGHT_TILL,
 233         VIS_MOVE_FILE_BEGIN,
 234         VIS_MOVE_FILE_END,
 235         VIS_MOVE_MARK,
 236         VIS_MOVE_MARK_LINE,
 237         VIS_MOVE_SEARCH_WORD_FORWARD,
 238         VIS_MOVE_SEARCH_WORD_BACKWARD,
 239         VIS_MOVE_SEARCH_NEXT,
 240         VIS_MOVE_SEARCH_PREV,
 241         VIS_MOVE_WINDOW_LINE_TOP,
 242         VIS_MOVE_WINDOW_LINE_MIDDLE,
 243         VIS_MOVE_WINDOW_LINE_BOTTOM,
 244         VIS_MOVE_CHANGELIST_NEXT,
 245         VIS_MOVE_CHANGELIST_PREV,
 246         VIS_MOVE_JUMPLIST_NEXT,
 247         VIS_MOVE_JUMPLIST_PREV,
 248         VIS_MOVE_NOP,
 249         VIS_MOVE_PERCENT,
 250         VIS_MOVE_INVALID, /* denotes the end of the "real" motions */
 251         /* pseudo motions: keep them at the end to save space in array definition */
 252         VIS_MOVE_TOTILL_REPEAT,
 253         VIS_MOVE_TOTILL_REVERSE,
 254         VIS_MOVE_SEARCH_FORWARD,
 255         VIS_MOVE_SEARCH_BACKWARD,
 256         VIS_MOVE_LAST, /* denotes the end of all motions */
 257 };
 258
 259 /* set motion to perform, the following take an additional argument:
 260  *
 261  *  - VIS_MOVE_SEARCH_FORWARD and VIS_MOVE_SEARCH_BACKWARD
 262  *
 263  *     expect the search pattern as const char *
 264  *
 265  *  - VIS_MOVE_{LEFT,RIGHT}_{TO,TILL}
 266  *
 267  *     expect the character to search for as const char *
 268  *
 269  *  - VIS_MOVE_MARK and VIS_MOVE_MARK_LINE
 270  *
 271  *     expect a valid enum VisMark
 272  */
 273 bool vis_motion(Vis*, enum VisMotion, ...);
 274
 275 /* If no count is explicitly specified, operators, motions and
 276  * text object will always perform their function as if a minimal
 277  * count of 1 was given */
 278 #define VIS_COUNT_UNKNOWN (-1)
 279 int vis_count_get(Vis*);
 280 int vis_count_get_default(Vis*, int def);
 281 void vis_count_set(Vis*, int count);
 282
 283 enum VisMotionType {
 284         VIS_MOTIONTYPE_LINEWISE  = 1 << 0,
 285         VIS_MOTIONTYPE_CHARWISE  = 1 << 1,
 286 };
 287 /* force certain motion to behave in line or character wise mode */
 288 void vis_motion_type(Vis *vis, enum VisMotionType);
 289
 290 /* register a motion function, if positive the return value can be used
 291  * as an id for the vis_motion funntion. A negative return value indicates
 292  * an error */
 293 int vis_motion_register(Vis*, enum VisMotionType, void *data,
 294         size_t (*motion)(Vis*, Win*, void*, size_t pos));
 295
 296 enum VisTextObject {
 297         VIS_TEXTOBJECT_INNER_WORD,
 298         VIS_TEXTOBJECT_OUTER_WORD,
 299         VIS_TEXTOBJECT_INNER_LONGWORD,
 300         VIS_TEXTOBJECT_OUTER_LONGWORD,
 301         VIS_TEXTOBJECT_SENTENCE,
 302         VIS_TEXTOBJECT_PARAGRAPH,
 303         VIS_TEXTOBJECT_OUTER_SQUARE_BRACKET,
 304         VIS_TEXTOBJECT_INNER_SQUARE_BRACKET,
 305         VIS_TEXTOBJECT_OUTER_CURLY_BRACKET,
 306         VIS_TEXTOBJECT_INNER_CURLY_BRACKET,
 307         VIS_TEXTOBJECT_OUTER_ANGLE_BRACKET,
 308         VIS_TEXTOBJECT_INNER_ANGLE_BRACKET,
 309         VIS_TEXTOBJECT_OUTER_PARANTHESE,
 310         VIS_TEXTOBJECT_INNER_PARANTHESE,
 311         VIS_TEXTOBJECT_OUTER_QUOTE,
 312         VIS_TEXTOBJECT_INNER_QUOTE,
 313         VIS_TEXTOBJECT_OUTER_SINGLE_QUOTE,
 314         VIS_TEXTOBJECT_INNER_SINGLE_QUOTE,
 315         VIS_TEXTOBJECT_OUTER_BACKTICK,
 316         VIS_TEXTOBJECT_INNER_BACKTICK,
 317         VIS_TEXTOBJECT_OUTER_ENTIRE,
 318         VIS_TEXTOBJECT_INNER_ENTIRE,
 319         VIS_TEXTOBJECT_OUTER_FUNCTION,
 320         VIS_TEXTOBJECT_INNER_FUNCTION,
 321         VIS_TEXTOBJECT_OUTER_LINE,
 322         VIS_TEXTOBJECT_INNER_LINE,
 323         VIS_TEXTOBJECT_INDENTATION,
 324         VIS_TEXTOBJECT_SEARCH_FORWARD,
 325         VIS_TEXTOBJECT_SEARCH_BACKWARD,
 326         VIS_TEXTOBJECT_INVALID,
 327 };
 328
 329 bool vis_textobject(Vis*, enum VisTextObject);
 330
 331 /* register a new text object, if successful the returned id is positive
 332  * and can be used as argument for the vis_textobject function. */
 333 int vis_textobject_register(Vis*, int type, void *data,
 334         Filerange (*textobject)(Vis*, Win*, void*, size_t pos));
 335
 336
 337 enum VisMark {
 338         VIS_MARK_a, VIS_MARK_b, VIS_MARK_c, VIS_MARK_d, VIS_MARK_e,
 339         VIS_MARK_f, VIS_MARK_g, VIS_MARK_h, VIS_MARK_i, VIS_MARK_j,
 340         VIS_MARK_k, VIS_MARK_l, VIS_MARK_m, VIS_MARK_n, VIS_MARK_o,
 341         VIS_MARK_p, VIS_MARK_q, VIS_MARK_r, VIS_MARK_s, VIS_MARK_t,
 342         VIS_MARK_u, VIS_MARK_v, VIS_MARK_w, VIS_MARK_x, VIS_MARK_y,
 343         VIS_MARK_z,
 344         VIS_MARK_SELECTION_START, /* '< */
 345         VIS_MARK_SELECTION_END,   /* '> */
 346         VIS_MARK_INVALID,     /* has to be the last enum member */
 347 };
 348
 349 void vis_mark_set(Vis*, enum VisMark mark, size_t pos);
 350
 351 enum VisRegister {
 352         VIS_REG_a, VIS_REG_b, VIS_REG_c, VIS_REG_d, VIS_REG_e,
 353         VIS_REG_f, VIS_REG_g, VIS_REG_h, VIS_REG_i, VIS_REG_j,
 354         VIS_REG_k, VIS_REG_l, VIS_REG_m, VIS_REG_n, VIS_REG_o,
 355         VIS_REG_p, VIS_REG_q, VIS_REG_r, VIS_REG_s, VIS_REG_t,
 356         VIS_REG_u, VIS_REG_v, VIS_REG_w, VIS_REG_x, VIS_REG_y,
 357         VIS_REG_z,
 358         VIS_REG_DEFAULT, /* used when no other register is specified */
 359         VIS_REG_ZERO, /* yank register */
 360         VIS_REG_BLACKHOLE, /* /dev/null register */
 361         VIS_REG_CLIPBOARD, /* system clipboard register */
 362         VIS_REG_PROMPT,  /* internal register which shadows DEFAULT in PROMPT mode */
 363         VIS_MACRO_OPERATOR,      /* records entered keys after an operator */
 364         VIS_MACRO_REPEAT,        /* copy of the above macro once the recording is finished */
 365         VIS_REG_SEARCH,  /* last used search pattern "/ */
 366         VIS_REG_COMMAND, /* last used :-command ": */
 367         VIS_REG_INVALID, /* has to be the last 'real' register */
 368         VIS_REG_A, VIS_REG_B, VIS_REG_C, VIS_REG_D, VIS_REG_E,
 369         VIS_REG_F, VIS_REG_G, VIS_REG_H, VIS_REG_I, VIS_REG_J,
 370         VIS_REG_K, VIS_REG_L, VIS_REG_M, VIS_REG_N, VIS_REG_O,
 371         VIS_REG_P, VIS_REG_Q, VIS_REG_R, VIS_REG_S, VIS_REG_T,
 372         VIS_REG_U, VIS_REG_V, VIS_REG_W, VIS_REG_X, VIS_REG_Y,
 373         VIS_REG_Z,
 374         VIS_MACRO_LAST_RECORDED, /* pseudo macro referring to last recorded one */
 375 };
 376
 377 /* set the register to use, if none is given the DEFAULT register is used */
 378 void vis_register_set(Vis*, enum VisRegister);
 379 /* get register content */
 380 const char *vis_register_get(Vis*, enum VisRegister, size_t *len);
 381
 382 /* start a macro recording, fails if a recording is already on going */
 383 bool vis_macro_record(Vis*, enum VisRegister);
 384 /* stop recording, fails if there is nothing to stop */
 385 bool vis_macro_record_stop(Vis*);
 386 /* check whether a recording is currently on going */
 387 bool vis_macro_recording(Vis*);
 388 /* replay a macro. a macro currently being recorded can't be replayed */
 389 bool vis_macro_replay(Vis*, enum VisRegister);
 390
 391 /* repeat last operator, possibly with a new count if one was provided in the meantime */
 392 void vis_repeat(Vis*);
 393
 394 /* cancel pending operator, reset count, motion, text object, register etc. */
 395 void vis_cancel(Vis*);
 396
 397 /* execute a :-command (including an optinal range specifier) */
 398 bool vis_cmd(Vis*, const char *cmd);
 399
 400 /* type of user defined function which can be registered */
 401 typedef bool (*CmdFunc)(Vis*, Win*, void *data, bool force,
 402         const char *argv[], Cursor*, Filerange*);
 403 /* the function will be invoked whenever a command which matches a
 404  * unique prefix of the given name is executed */
 405 bool vis_cmd_register(Vis*, const char *name, void *data, CmdFunc);
 406 bool vis_cmd_unregister(Vis*, const char *name);
 407 /* execute any kind (:,?,/) of prompt command */
 408 bool vis_prompt_cmd(Vis*, const char *cmd);
 409
 410 /* pipe a given file range to an external process
 411  *
 412  * if argv contains only one non-NULL element the command is executed using
 413  * /bin/sh -c (i.e. argument expansion is performed by the shell). In contrast
 414  * if argv contains more than one non-NULL element execvp(argv[0], argv); will
 415  * be used.
 416  *
 417  * if read_std{out,err} are non-NULL they will be called when output from
 418  * the forked process is available.
 419  */
 420 int vis_pipe(Vis *vis, Filerange *range, const char *argv[],
 421         void *stdout_context, ssize_t (*read_stdout)(void *stdout_context, char *data, size_t len),
 422         void *stderr_context, ssize_t (*read_stderr)(void *stderr_context, char *data, size_t len));
 423
 424 /* given the start of a key, returns a pointer to the start of the one immediately
 425  * following as will be processed by the input system. skips over special keys
 426  * such as <Enter> as well as pseudo keys registered via vis_action_register. */
 427 const char *vis_keys_next(Vis*, const char *keys);
 428 /* vis operates as a finite state machine (FSM), feeding keys from an input
 429  * queue (or a previously recorded macro) to key handling functions (see struct
 430  * KeyAction) which consume the input.
 431  *
 432  * this functions pushes/appends further input to the end of the input queue.
 433  * if it is called from within a key handling function itself, the fed keys
 434  * will be interpreted once the key handler returns. otherwhise the keys are
 435  * immediately interpreted as if they were entered from a user. */
 436 void vis_keys_feed(Vis*, const char *keys);
 437
 438 /* inform vis that a signal occured, the return value indicates whether the signal
 439  * was handled by vis */
 440 bool vis_signal_handler(Vis*, int signum, const siginfo_t *siginfo, const void *context);
 441
 442 /* remember last search pattern, freeing the regex is the callers responsibility */
 443 Regex *vis_regex(Vis*, const char *pattern);
 444
 445 /* TODO: expose proper API to iterate through files etc */
 446 Text *vis_text(Vis*);
 447 View *vis_view(Vis*);
 448 Win *vis_window(Vis*);
 449
 450 bool vis_theme_load(Vis*, const char *name);
 451
 452 #endif