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