vis

a vi-like editor based on Plan 9's structural regular expressions
vis.rst

(3870B)
      1 Vis
      2 ===
      3 
      4 The core Vis API.
      5 
      6 Lifecycle
      7 ---------
      8 
      9 .. doxygengroup:: vis_lifecycle
     10    :content-only:
     11 
     12 Draw
     13 ----
     14 
     15 .. doxygengroup:: vis_draw
     16    :content-only:
     17 
     18 Windows
     19 -------
     20 
     21 .. doxygengroup:: vis_windows
     22    :content-only:
     23 
     24 Input
     25 -----
     26 
     27 The editor core processes input through a sequences of symbolic keys:
     28 
     29  * Special keys such as ``<Enter>``, ``<Tab>`` or ``<Backspace>`` as reported by
     30    `termkey_strfkey <http://www.leonerd.org.uk/code/libtermkey/doc/termkey_strfkey.3.html>`_.
     31 
     32    .. note:: The prefixes ``C-``, ``S-`` and ``M-`` are used to denote the ``Ctrl``,
     33              ``Shift`` and ``Alt`` modifiers, respectively.
     34 
     35  * Key action names as registered with `vis_action_register`.
     36 
     37    .. note:: By convention they are prefixed with ``vis-`` as in ``<vis-nop>``.
     38 
     39  * Regular UTF-8 encoded input.
     40 
     41 .. note:: An exhaustive list of the first two types is displayed in the ``:help`` output.
     42 
     43 .. doxygengroup:: vis_keys
     44    :content-only:
     45 
     46 Key Map
     47 -------
     48 
     49 The key map is used to translate keys in non-input modes, *before* any key
     50 bindings are evaluated. It is intended to facilitate usage of non-latin keyboard
     51 layouts.
     52 
     53 .. doxygengroup:: vis_keymap
     54    :content-only:
     55 
     56 Key Binding
     57 -----------
     58 
     59 Each mode has a set of key bindings. A key binding maps a key to either
     60 another key (referred to as an alias) or a key action (implementing an
     61 editor operation).
     62 
     63 If a key sequence is ambiguous (i.e. it is a prefix of multiple mappings)
     64 more input is awaited, until a unique mapping can be resolved.
     65 
     66 .. warning:: Key aliases are always evaluated recursively.
     67 
     68 .. doxygengroup:: vis_keybind
     69    :content-only:
     70 
     71 Key Action
     72 ----------
     73 
     74 A key action is invoked by a key binding and implements a certain editor function.
     75 
     76 The editor operates like a finite state machine with key sequences as
     77 transition labels. Once a prefix of the input queue uniquely refers to a
     78 key action, it is invoked with the remainder of the input queue passed as argument.
     79 
     80 .. note:: A triggered key action currently does not know through which key binding
     81           it was invoked. TODO: change that?
     82 
     83 .. doxygengroup:: vis_action
     84    :content-only:
     85 
     86 Modes
     87 -----
     88 
     89 A mode defines *enter*, *leave* and *idle* actions and captures a set of
     90 key bindings.
     91 
     92 Modes are hierarchical, key bindings are searched recursively towards
     93 the top of the hierarchy stopping at the first match.
     94 
     95 .. doxygenenum:: VisMode
     96 .. doxygengroup:: vis_modes
     97    :content-only:
     98 
     99 Count
    100 -----
    101 
    102 Dictates how many times a motion or text object is evaluated. If none
    103 is specified, a minimal count of 1 is assumed.
    104 
    105 .. doxygengroup:: vis_count
    106    :content-only:
    107 
    108 Operators
    109 ---------
    110 
    111 .. doxygengroup:: vis_operators
    112    :content-only:
    113 
    114 Motions
    115 -------
    116 
    117 .. doxygengroup:: vis_motions
    118    :content-only:
    119 
    120 Text Objects
    121 ------------
    122 
    123 .. doxygengroup:: vis_textobjs
    124    :content-only:
    125 
    126 Marks
    127 -----
    128 
    129 Marks keep track of a given text position.
    130 
    131 .. note:: Marks are currently file local.
    132 
    133 .. doxygengroup:: vis_marks
    134    :content-only:
    135 
    136 Registers
    137 ---------
    138 
    139 .. doxygengroup:: vis_registers
    140    :content-only:
    141 
    142 Macros
    143 ------
    144 
    145 Macros are a sequence of keys stored in a Register which can be reprocessed
    146 as if entered by the user.
    147 
    148 .. warning:: Macro support is currently half-baked. If you do something stupid
    149              (e.g. use mutually recursive macros), you will likely encounter
    150              stack overflows.
    151 
    152 .. doxygengroup:: vis_macros
    153    :content-only:
    154 
    155 Commands
    156 --------
    157 
    158 .. doxygengroup:: vis_cmds
    159    :content-only:
    160 
    161 Options
    162 -------
    163 
    164 .. doxygengroup:: vis_options
    165    :content-only:
    166 
    167 Modification
    168 ------------
    169 
    170 These function operate on the currently focused window but ensure that
    171 all windows which show the affected region are redrawn too.
    172 
    173 .. doxygengroup:: vis_changes
    174    :content-only:
    175 
    176 Interaction
    177 -----------
    178 
    179 .. doxygengroup:: vis_info
    180    :content-only:
    181 
    182 Miscellaneous
    183 -------------
    184 
    185 .. doxygengroup:: vis_misc
    186    :content-only:
    187