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