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