kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

modes.asciidoc (4425B)


      1 = Modes
      2 
      3 == Description
      4 
      5 Kakoune is a modal editor which means that keys have different effects depending
      6 on the current mode. Therefore, modes can be conceptualized as a way to group
      7 related behaviors together during a text editing workflow.
      8 
      9 Kakoune starts in Normal mode. A few keys let users enter other modes
     10 where they can focus on a specific task before going back to Normal mode.
     11 
     12 Modes are stored in a stack with the top of the stack being the active mode.
     13 So in some scenarios, the Normal mode may feel *nested* in another one.
     14 The `ModeChange` hook is triggered each time a mode is popped or pushed
     15 on this stack. See <<hooks#,`:doc hooks`>>
     16 
     17 To get a comprehensive list of commands available for each modes, see
     18 <<keys#,`:doc keys`>>. Most of them are described in *info* boxes in
     19 real-time if the `autoinfo` option is set.
     20 
     21 To customize key mappings in various modes, refer to <<mapping#,`:doc mapping`>>.
     22 
     23 == Builtin modes
     24 
     25 === Normal mode
     26 
     27 Normal mode is the default mode. It provides commands to manipulate
     28 selections, such as general movement, text object selection, searching,
     29 splitting, and commands to manipulate the text underlying the current
     30 selections, such as yanking, pasting, deleting…
     31 
     32 It also provides commands to enter other modes.
     33 
     34 See normal commands <<keys#movement,`:doc keys movement`>>.
     35 
     36 === Insert mode
     37 
     38 Insert mode provides an efficient way to interactively write text into
     39 the buffer. Most keys will insert their corresponding characters before
     40 every selections cursors. It also provides completion support for inserted
     41 text along with some commands for basic movement.
     42 
     43 Insert mode can be entered from Normal modes through a set of commands
     44 such as `i` to insert before selection, `a` to insert after selection,
     45 `o` to insert in a new line below selections… It can then be exited with
     46 `<esc>` to return to Normal mode.
     47 
     48 See changes <<keys#changes,`:doc keys changes`>>.
     49 
     50 From Insert mode, `<a-;>` provides a way to temporarily enter a new
     51 Normal mode for a single command, before returning to Insert mode.
     52 
     53 See insert commands <<keys#insert-mode,`:doc keys insert-mode`>>.
     54 
     55 === Goto mode
     56 
     57 Goto mode provides commands dedicated to jumping either inside a buffer
     58 (such as jumping to buffer start/end, window top/bottom) or to another
     59 (such as jumping to the file whose path is currently selected).
     60 
     61 See goto commands <<keys#goto-commands,`:doc keys goto-commands`>>.
     62 
     63 === View mode
     64 
     65 View mode provides commands dedicated to controlling the window, such
     66 as scrolling or centering the main selection cursor.
     67 
     68 See view commands <<keys#view-commands,`:doc keys view-commands`>>.
     69 
     70 === Prompt mode
     71 
     72 Mode entered with `:`, `/` or the `prompt` command. During prompt mode a
     73 line of text is edited and then validated with `<ret>` or abandoned with
     74 `<esc>`.
     75 
     76 See prompt commands <<keys#prompt-commands,`:doc keys prompt-commands`>>.
     77 
     78 === Object mode
     79 
     80 Mode entered with `<a-i>`, `<a-a>` and various combinations of `[]{}` keys.
     81 It aims at crafting semantic selections, often called *text-objects*.
     82 
     83 See object commands <<keys#object-selection,`:doc keys object-selection`>>.
     84 
     85 === Combine mode
     86 
     87 Mode entered with `<a-z>` or `<a-Z>` keys.
     88 It aims at crafting ways to combine selections with ones in registers.
     89 
     90 See marks commands <<keys#marks,`:doc keys marks`>>.
     91 
     92 === User mode
     93 
     94 Mode entered with `<space>`. The user mode is empty by default and is the
     95 opportunity to store custom mappings with no risk to shadow builtin ones.
     96 The context of execution is always the Normal mode.
     97 
     98 == User modes
     99 
    100 The following two commands are useful in advanced use cases, when the
    101 builtin User mode gets too crowded by mappings competing for the same
    102 key that deserves to be split in more meaningful collections. It's
    103 mostly useful for plugin authors who want to bind their new commands in
    104 extensible menus.
    105 
    106 --------------------------------
    107 declare-user-mode <name>
    108 --------------------------------
    109 
    110 Declare a new custom mode that can later be referred by the *map* command.
    111 For example a `grep` custom mode to attach keys like `n` or `p` to skim
    112 through the output results.
    113 
    114 -------------------------------
    115 enter-user-mode <name>
    116 -------------------------------
    117 
    118 Enable the designated mode for the next key. Docstrings are shown in the
    119 automatic info box to increase discoverability. To keep illustrating
    120 the aforementioned fictional `grep` mode, a normal mapping on `<a-g>`
    121 could be used to enter this mode.