kakoune

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

autoedit.asciidoc (3871B)


      1 Edition auto insertion in Kakoune
      2 =================================
      3 
      4 It is a quite common feature for a code editor to help the programmer
      5 by automatically inserting some text in certain contexts. This document
      6 goal is to explain how this is done in Kakoune.
      7 
      8 There is no special support in Kakoune for this task, hooks are
      9 expected to be used in order to manage that, and the normal Kakoune
     10 editing command are expected to be expressive enough so that relatively
     11 complex indentation can be written concisely.
     12 
     13 The main hook is *InsertChar*, which gets called immediately _after_ a
     14 character has been inserted in insertion mode due to the user pressing
     15 the corresponding key.
     16 
     17 Previous line indentation
     18 -------------------------
     19 
     20 Let's see a simple indent hook: preserving the previous line indentation.
     21 
     22 Here is the Kakoune normal mode key list in order to do that: 
     23 
     24 ----------------------------------------------------------------
     25 k<a-x>      # 1. go to previous line and select it
     26 s^\h+<ret>y # 2. select the leading spaces and copy them
     27 j<a-h>P     # 3. go back to next line start and paste the spaces
     28 ----------------------------------------------------------------
     29 
     30 Note that if nothing gets selected on phase *2.*, an error will be raised.
     31 
     32 We want to do that each time the user jumps a line, just after the new line
     33 is inserted. So the hook would be:
     34 
     35 --------------------------------------------------------
     36 :hook InsertChar \n %{ exec k<a-x> s^\h+<ret>y j<a-h>P }
     37 --------------------------------------------------------
     38 
     39 (exec concatenates the keys for all argument, so the spaces will be ignored,
     40 allowing for clearer separation. either use <space> or quote the argument to
     41 use a space key)
     42 
     43 That works, however if the phase *2.* raises an error, the +:exec+ will stop
     44 and the user will get its selections on the previous line. The solution
     45 is to use a *draft* context, instead of the one the user is interacting with.
     46 
     47 ---------------------------------------------------------------
     48 :hook InsertChar \n %{ exec -draft k<a-x> s^\h+<ret>y j<a-h>P }
     49 ---------------------------------------------------------------
     50 
     51 That way, exec is executed in a *copy* of the user's context, which means it
     52 manipulates a *copy* of the user's selections.
     53 
     54 Increasing indentation
     55 ----------------------
     56 
     57 A little bit more complicated is to increase indentation whenever we insert a 
     58 new line after a +{+ or a +(+.
     59 
     60 The complexity arises from the presence of a condition. We want to increase 
     61 the indentation *only* if the previous line ends with +{+ or +(+.
     62 
     63 Fortunately, Kakoune provides us with a command for that: the +<a-k>+ command,
     64 which keeps selections where a certain regex can be found.
     65 
     66 Here is how we can do that:
     67 
     68 -------------------------------------------------------------------------------
     69 k<a-x>             # 1. select the previous line
     70 <a-k>[{(]\h*$<ret> # 2. keep selections that end with { or ( followed by blanks
     71 j<a-gt>            # 3. go back to next line and indent it even if it is empty
     72 -------------------------------------------------------------------------------
     73 
     74 Note that if no previous line ends with a +{+ or +(+, the +<a-k>+ command will
     75 raise an error, and stop the execution. This is what we want: it is similar to
     76 what would happen if we would continue with no selections; the following 
     77 commands would have no effects.
     78 
     79 However, the error would end up being caught by the hook execution code, and
     80 it will write information about it in the debug buffer, which we do not want,
     81 as this is actually expected. In order to prevent that, the exec should be
     82 wrapped in a try command. So we would have:
     83 
     84 -------------------------------------------------------------------------------
     85 :hook InsertChar \n %[ try %[ exec -draft k<a-x> <a-k>[{(]\h*$<ret> j<a-gt> ] ]
     86 -------------------------------------------------------------------------------
     87