kakoune

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

TRAMPOLINE (26483B)


      1 +=----------------------------------------------------------------------------=+
      2               _              _
      3              | |            | |
      4              | | __   __ _  | | __   ___    _   _   _ __     ___
      5              | |/ /  / _` | | |/ /  / _ \  | | | | | '_ \   / _ \
      6              |   <  | (_| | |   <  | (_) | | |_| | | | | | |  __/
      7              |_|\_\  \__,_| |_|\_\  \___/   \__,_| |_| |_|  \___|
      8 
      9                   Mawww's experiment for a better code editor
     10 +=----------------------------------------------------------------------------=+
     11 
     12 This walk-through is an introduction to Kakoune's basic editing capabilities
     13 to help new users transition over easily from another editor, or simply
     14 learn how to write and edit documents with style.
     15 
     16 During the learning period, it is useful to activate an automatically displayed
     17 contextual help for commands in normal mode: `:set -add global autoinfo normal`
     18 
     19 In the first section, you will learn about the primitives of the editing
     20 language to be able to get to a level of knowledge of the editor that
     21 guarantees that you can work with it efficiently.
     22 
     23 In the second section, for users who've gone through the basics and want to
     24 move on to more advanced functionalities, we explain other primitives whose
     25 role has a less dominant place in an everyday editing session, but still
     26 prove themselves powerful when used on the right occasion.
     27 
     28 Finally, as this document is in no way an exhaustive list of features, don't
     29 hesitate to check out the official documentation to complement your tool-set,
     30 ask questions to more seasoned users on IRC, and check the documentation
     31 using the built-in `:doc` command.
     32 
     33 +=--------------------------------=+ BASICS +=--------------------------------=+
     34 
     35                     =[ MODES
     36 
     37                     Kakoune uses a paradigm called "modal editing" to allow
     38        .---,        users to either have every single key they type inserted
     39        | i |        into the file being edited (called "insert mode"),
     40        `---'        or execute commands that are triggered by the keys hit
     41                     (the "normal mode").  Aside from arrow keys, most keys
     42        .---,        described in this document are "editing primitives" that
     43        |esc|        have to be hit in normal mode, which is the default mode
     44        `---'        when you start the editor. To enter insert mode, hit the
     45                     `i` key, and to leave it and return to normal mode, hit the 
     46                     escape key.
     47 
     48 
     49                     =[ MOVEMENT
     50        .---,
     51        | ↑ |        Movement in a buffer (the representation of the contents
     52    .---'---'---,    of a file opened by Kakoune) can be achieved using the arrow
     53    | ← | ↓ | → |    keys, which will move the cursor up one column/row into
     54    `---'---'---`    a given direction.
     55 
     56                     However, furthering the tradition of mode-based editors,
     57  .---,---,---,---,  the `h`, `j`, `k` and `l` keys can be used for the same
     58  | h | j | k | l |  purpose, and will respectively move the cursor to the
     59  `---'---'---'---`  left, down, up, right by one, when hit. Using those keys
     60    |   |   |   |    is the recommended way of moving around in a buffer.
     61  .---,---,---,---,  If you're not familiar with this concept, the proximity
     62  | ← | ↓ | ↑ | → |  of those four keys with the rest of the lettered keys
     63  `---'---'---'---`  on a `qwerty` layout allows faster interaction with the
     64                     primitives than if the user had to move their hand to
     65    .---,            reach the arrow keys.
     66    | g |_.
     67    `---' |`.---,    Another way of moving the cursor is the "goto" utility,
     68          | | g |    invoked by hitting the `g` key. A menu will pop up with a
     69          | `---'    summary of all the possible keys that can be hit, along with
     70           `.---,    the location where they will move the cursor to, but the
     71            | e |    most used ones that we are interested in, for now, are `g`
     72            `---'    and `e`. The first one will jump to the beginning of the
     73                     buffer, and the second one to its end.
     74 
     75 
     76                     =[ VIEW
     77 
     78    .---,            Displacing the cursor can sometimes move the view into an
     79    | v |_.          inconvenient configuration, leaving some necessary context
     80    `---' |`.---,    off-screen, or simply feel uncomfortable to type into.
     81          | | t |    Kakoune provides a menu (similar to the `goto` menu
     82          | `---'    mentioned in the previous section) that allows users to
     83          |`.---,    move the current view in relation to the position of the
     84          | | b |    cursor. Upon hitting the `v` key, a short menu appears
     85          | `---'    which allows us to hit a second key according to how the
     86           `.---,    view should be centered vertically: to leave the cursor
     87            | v |    respectively on top, at the bottom or in the middle of the
     88            `---'    current view, hit the `t`, `b` or `v` keys.
     89 
     90 
     91                     =[ SEARCH
     92 
     93                     In order to move the cursor to a specific word, the search
     94                     command is the way to go. This functionality allows
     95         .---,       the user to jump to the next occurrence of a piece of text.
     96         | / |       Upon hitting the `/` key, a prompt reading "search"
     97         `---'       will pop up in the status bar in which you can type
     98                     your text and validate using the `<ret>` (return) key.
     99      .---, .---,    You'll notice that as you type, the cursor changes location
    100      |alt|+| / |    to automatically give you a preview of where the cursor
    101      `---' `---'    would be displaced to if you validated the search. However,
    102                     this behavior is only a preview, exiting prompt mode with
    103                     the `<esc>` (escape) key will leave the current position
    104         .---,       of the cursor unchanged. Note that you can also use a
    105         | n |       regular expression as input.  By default the search
    106         `---'       function will look for results forward, starting from
    107                     the current location of the cursor, but you can search
    108      .---, .---,    backwards using `<a-/>` (alt + `/`).
    109      |alt|+| n |
    110      `---' `---'    Jumping from one match to the other forward can be achieved
    111                     using the `n` key, and backwards using the `<a-n>` (alt +
    112                     `n`) key combination.
    113 
    114 
    115                     =[ SELECTIONS
    116 
    117                     You have certainly noticed that when searching for
    118         .---,       text, the cursor extends to highlight the entire match.
    119         | ; |       In fact, what we know in other editors as a "cursor" is
    120         `---'       actually a single character wide selection in Kakoune,
    121                     and can be expanded using primitives. When "expanded",
    122      .---, .---,    the selection is an area whose beginning is the "anchor"
    123      |alt|+| ; |    and the end the "secondary cursor". To switch anchor and
    124      `---' `---'    cursor, use `<a-;>`, and to collapse the selection onto
    125                     its anchor, use `;`.
    126 
    127                     Moreover, not only does Kakoune expand the principle of
    128                     "cursor" by introducing selections, but it also allows
    129         .---,       multiple selections within the same buffer. This makes
    130         | % |       it very convenient to modify text in multiple locations
    131         `---'       at once, as editing primitives apply to all the currently
    132                     selected text.
    133         .---,
    134         | s |       Example: to remove all occurrences of the word "foo", one
    135         `---'       would select the entire buffer (`%`), select occurrences of
    136                     the word (`s`, "\bfoo\b", `<ret>`), then remove it (`d`).
    137 
    138                     ==[ SELECTING OBJECTS
    139 
    140                     In addition to allowing text selection using regular
    141      .---, .---,    expressions, certain objects are defined by default to
    142      |alt|+| i |    allow easy selection of text. Objects are bits of text
    143      `---' `---'    in the buffer that are identified according to their
    144                     structure, rather than their contents, e.g., a paragraph,
    145      .---, .---,    a sentence, or a word. When the cursor is located within
    146      |alt|+| a |    the boundaries of an object you want to interact with,
    147      `---' `---'    several options are available: selecting the contents of an
    148                     object without its boundaries (`<a-i>`), a part of it (from
    149         .---,       the anchor to its end or its beginning, respectively `]`
    150         | ] |       and `[`), or the entire object (`<a-a>`). Those "selection
    151         `---'       ranges" are the first part of a two stages shortcut,
    152                     as once you've used the key that dictates what part of
    153         .---,       the object is to be selected, a menu with a description
    154         | [ |       of all the object types select-able will be displayed,
    155         `---'       giving a summary of all the keys you can hit to complete
    156                     the selection procedure.
    157 
    158                     Example: to select the paragraph in which the anchor lies,
    159                     invoke the "inner object selection" shortcut (`<a-i>`),
    160                     locate "paragraph" in the information box that pops up and
    161     .---,           hit the according key (`p`). The entire two steps sequence
    162     | [ |_.         is thus: `<a-i> p`.
    163     `---' |`.---,
    164           | | ( |   Example: to select everything between the anchor and the
    165           | `---'   beginning of the current parenthesis pair, use the selection
    166            `.---,   sequence: `[ (`. Note that common objects that use
    167             | r |   pairs of opening/closing punctuation signs (brackets,
    168             `---'   braces, quotes etc) have an alternative second key that
    169                     is displayed in the information menu that you can use to
    170                     minimize finger gymnastics. The previous shortcut could
    171                     thus also be written: `[ b`.
    172 
    173                     ==[ MOVEMENT SELECTIONS
    174 
    175                     If objects are an easy way to select content-agnostic
    176     .---,           data in a buffer, they can also be seen as a way to move
    177     | [ |_.         about the buffer. As selecting objects will displace the
    178     `---'  `.---,   anchor into a given direction, you can wrap or move around
    179             | p |   particular chunks of text without using the conventional
    180             `---'   means (e.g., arrow keys or jumps), turning them partially
    181                     into movement primitives.
    182     .---,
    183     | ] |_.         Example: one of the most used object selection combination
    184     `---'  `.---,   is the "object end/begin paragraph" one: using `[` or
    185             | p |   `]` will displace the anchor into a given direction, and
    186             `---'   applying that to the paragraph object allows "jumping"
    187                     from one newline separated block of text to another.
    188                     The resulting shortcut is thus: `] p` to move forward, or
    189                     `[ p` to move backward.
    190 
    191 
    192                     =[ FILTERING A SELECTION
    193 
    194                     Selecting an entire buffer (`%`) or parts of it (`s`) is a
    195                     natural and basic operation in a typical editing session,
    196      .---, .---,    however, there are some cases where we need to be able to
    197      |alt|+| k |    drop some selections arbitrarily, as opposed to trying
    198      `---' `---'    to select the ones we need directly. This concept becomes
    199                     very useful when coming up with a regular expression for
    200      .---, .---,    the basic selection primitive (`s`) is too tedious (if
    201      |alt|+| K |    even possible), that's why the editor provides us with a
    202      `---' `---'    "keep matching" and a "keep not matching" operations,
    203                     in order to respectively keep exclusively the selections
    204                     who match or do not match a given regular expression.
    205 
    206                     Example: when parsing a log file whose lines follow the
    207                     usual log pattern (e.g. "[1484383442] ERROR: some data"),
    208                     we want to be able to select all the lines individually
    209      .---, .---,    (`%`, `<a-s>` to split all the lines), keep those that
    210      |alt|+| s |    start with a bracketed time-stamp (`<a-k>^\[`), but
    211      `---' `---'    exclude the debug messages (`<a-K>DEBUG`). Of course,
    212                     it's possible to come up with a regular expression to
    213                     match those simple requirements, but it would take more
    214                     work to write it than to organically apply filters on a
    215                     general selection, individually.
    216 
    217 
    218                     =[ SELECTION DUPLICATION
    219 
    220         .---,       Duplicating content can be achieved using a widely
    221         | y |       implemented concept: yanking and pasting. Yanking the
    222         `---'       current selection (`y`) into the copy register allows the
    223         .---,       user to subsequently insert the copied text in the buffer
    224         | p |       (`p`).
    225         `---'
    226         .---,       Note that the default "paste" primitive will insert the
    227         | P |       contents of the copy register after the current selection,
    228         `---'       if you want copied text to be inserted before the current
    229                     selection then you can use the `P` key.
    230 
    231 
    232                     =[ DELETING / REPLACING SELECTIONS
    233 
    234                     Text replacement is a two-step process in Kakoune, which
    235         .---,       involves selecting text to be replaced, and then erasing it
    236         | d |       to insert the replacement text. After selections have been
    237         `---'       made, you can simply hit the deletion primitive (`d`), then
    238         .---,       either enter insert mode to write down the replacement text
    239         | c |       (`i`), or stay in command mode to paste the replacement
    240         `---'       text stored in the copy register. As deleting and entering
    241         .---,       insert mode can be redundant, a primitive that implements
    242         | R |       deletion followed by insert mode entrance was implemented:
    243         `---'       `c`. You can also directly replace the current selection
    244                     with the content of the copy register using a primitive
    245                     also implemented for that purpose: `R`.
    246 
    247 
    248                     =[ UNDO / REDO
    249 
    250                     Mistakes or wrong decisions can happen while editing.
    251         .---,       To go back to earlier states of the buffer, you can press
    252         | u |       the `u` key several times. On the contrary, pressing `U`
    253         `---'       allows traveling forward in the history tree.
    254 
    255 
    256 +=-------------------------------=+ ADVANCED +=-------------------------------=+
    257 
    258                     =[ SPLITTING
    259 
    260                     The selection primitive (`s`) is a powerful tool to select
    261                     chunks of data, but sometimes the format of said data isn't
    262         .---,       uniform enough to allow creating clear cut selections. In
    263         | S |       order to avoid having to write overly complicated regular
    264         `---'       expressions that select precisely the wanted text, the
    265                     splitting primitive (`S`) allows applying a delimiter to
    266                     the current selection, splitting it into separate chunks.
    267 
    268                     Example: selecting the items in a CSV-style list (e.g.,
    269                     "1,2,3,4") is as simple as selecting the line, then
    270                     splitting it using the comma separator (`S,`). Note that
    271                     more advanced splitting is possible, since the delimiter
    272                     passed to this primitive is a regular expression.
    273 
    274 
    275                     =[ ROTATING
    276 
    277                     Often used in conjunction with the splitting primitive
    278                     (`S`), the rotation primitive (`<a-)>`) shifts all the
    279                     selections clock-wise. Note that a count (described after)
    280                     allows the rotation to take place in sub-groups whose size
    281      .---, .---,    is given by the count parameter.
    282      |alt|+| ) |
    283      `---' `---'    Example: in a numbered list where all the numbers are
    284                     selected (e.g., `1 2 3 4 5 6 7 8 9 0`), a rotation using
    285                     this primitive will shift all the numbers by one selection
    286                     forward, while leaving the original multiple selections
    287                     untouched (e.g., `0 1 2 3 4 5 6 7 8 9`).
    288 
    289 
    290                     =[ COUNTS
    291 
    292    .---,            In order to pass a count to a primitive, simply type the
    293    |0-9|_.          number out before hitting the primitive key/combination.
    294    `---' |`.---,    Counts allow primitives to specialize or extend their
    295          | | g |    original functionality by using it as a parameter,
    296          | `---'    acting on their side effect.
    297          |`.---,
    298          | | G |    Example: in order to respectively jump or select up to a
    299          | `---'    particular line, pass the line number to the `g` or `G`
    300          |`.---,    primitives (e.g., `42g` or `7G`).
    301          | | o |
    302          | `---'    Example: creating an arbitrary amount of new lines
    303           `.---,    above or below the current line and spawning a new selection
    304            | O |    for each of them is achieved by passing the number of lines
    305            `---'    as a count respectively to the `o` and `O` primitives.
    306 
    307 
    308                     =[ REGISTERS
    309 
    310                     Similarly to counts, registers influence the behavior of
    311    .---,            certain primitives. They are storage structures identified
    312    | " |_.          by a single character, and are populated by primitives as a
    313    `---'  `.---,    result of a side effect. Although primitives populate a
    314            |a-z|    specific register by default, it's possible to modify which
    315            `---'    is going to be populated upon execution using the double
    316                     quote (`"`) primitive, and subsequently hitting a key that
    317         .---,       will serve as an identifier.
    318         | * |
    319         `---'       Example: the smart search primitive (`*`) uses the current
    320                     selection as a search pattern, which will be saved to the
    321    .---,            `/` register. In order to use this primitive to execute a
    322    | " |_. .---,    temporary search, one could make this primitive save the
    323    `---'  `| _ |    pattern to a different register, to preserve the default one,
    324            `---'    e.g., `"m*` to save the pattern to the `m` register, or even
    325                     `"_*` to save the pattern to a "null" register, which does 
    326                     not store anything written to it.
    327 
    328                     ==[ CAPTURE GROUPS
    329 
    330                     Although registers can pass as mere buffer metadata,
    331      .---, .---,    they are an integral part of an editing session. The
    332      |ctl|+| r |    `<c-r>` key combination allows to insert into the buffer
    333      `---' `---'    the value of a register, whose identifier is typed right
    334                     after the combination.
    335 
    336 .---, .---,         Example: inserting the name of the current buffer in insert
    337 |ctl|+| r |_.       mode can be achieved using the `%` register, which holds
    338 `---' `---'  `.---, this information: `<c-r>%`.
    339               | % |
    340               `---' Other registers that are set automatically are
    341                     the numbered registers, which hold the values of the groups
    342                     matched in the last search or select operation (`/` and
    343 .---, .---,         `s` primitives).
    344 |ctl|+| r |_.
    345 `---' `---'  `.---, Example: when using the search primitive (`/`) with a
    346               |0-9| regular expression containing groups to match a list of
    347               `---' first and last names (e.g., `(\w+) (\w+)` on `John Doe`),
    348                     issuing `<c-r>1` would insert the first name (`John`),
    349                     and `<c-r>2` the last name (`Doe`).
    350 
    351 
    352                     =[ CUSTOM SELECTIONS
    353 
    354                     Despite the ability to select bits of data using regular
    355                     expressions, there are times when using them isn't enough,
    356                     and additional manual editing of the selections is
    357         .---,       needed. In order to loop through all the selections and
    358         | ) |       remove the current one, two primitives are available:
    359         `---'       respectively the parenthesis (`)`), and the alt/comma
    360                     key combination (`<a-,>`).
    361      .---, .---,
    362      |alt|+| , |    Example: given a list of three numbers all selected
    363      `---' `---'    individually, (e.g., `1 2 3`), deselecting the second
    364                     selection would be done by hitting the parenthesis primitive
    365                     (`)`) until the according selection is the current one,
    366                     then hitting `<a-,>` to end up with only the first
    367                     and third number selected.
    368 
    369                     However, being able to trim out some selections out
    370         .---,       of a bigger set isn't always convenient, as it doesn't
    371         | ^ |       allow more advanced constructs such as combining sets of
    372         `---'       multiple-selections that result from different regular
    373         .---,       expressions. To allow that, the save mark (`Z`) and append
    374         | Z |       mark (`<a-z>`) come in handy, as they respectively save
    375         `---'       the current selection to the mark register (`^`), and
    376                     show a menu that allows appending the current selection
    377 .---, .---,         to the mark register upon hitting the `a` key. That way,
    378 |alt|+| z |_.       it becomes possible to chain and save (append) several
    379 `---' `---'  `.---, selections made using completely different methods
    380               | a | (select, split etc) without being forced to preserve
    381               `---' them at all times.
    382         .---,
    383         | z |       Restoring a mark saved to the mark register using those
    384         `---'       primitives can be achieved by using the restore mark
    385                     primitive (`z`).
    386 
    387 
    388                     =[ LEVERAGING SHELL COMMANDS
    389 
    390                     UNIX systems provide with some tools whose purpose is
    391                     to interact with raw data, and being a UNIX compliant
    392         .---,       aspiring tool itself, Kakoune allows leveraging those
    393         | | |       tools to modify a buffer's contents. Upon invoking the pipe
    394         `---'       primitive (`|`), an input field pops up which prompts for
    395                     a shell command, to which the selections will individually
    396                     be sent through the command's standard input.
    397 
    398                     Example: wrapping a selection can be achieved by invoking
    399                     the `fold` utility, e.g., `|fold -w80`. You could also want
    400                     to see a patch of all the modifications made to the buffer
    401                     since it was last saved: `%|diff -u <c-r>% -`. Note that
    402                     the `<c-r>%` has to be typed interactively, as it will
    403                     insert the name of the buffer into the command.
    404 
    405                     Another equally useful primitive that doesn't depend on
    406         .---,       the contents of the current selections is the exclamation
    407         | ! |       mark primitive (`!`), which simply insert the output of
    408         `---'       the given shell command before each selection.
    409 
    410                     Example: in order to insert the date of the day at the
    411                     beginning of the current buffer, one could use `gg`
    412                     followed with `!date`.
    413 
    414                     But not all shell-related primitives insert data into
    415                     the current buffer, the `$` key is in fact a way to
    416         .---,       apply a predicate to all selections, in order to filter
    417         | $ |       them out. The command passed to this primitive will be
    418         `---'       executed in a new shell using each individual selection for
    419                     context, which will either be kept if the command returned
    420                     a successful exit code (zero) or dropped otherwise (any
    421                     non-zero value).
    422 
    423                     Example: after selecting all the lines in a buffer and
    424                     splitting them individually (`%`, `<a-s>`), keeping every
    425                     odd-numbered line can be achieved with the following
    426                     sequence: `$` `[ $((kak_reg_hash)) -ne 0 ]`.
    427 
    428 
    429                     =[ REPEATING ACTIONS
    430 
    431                     ==[ PUNCTUAL INTERACTIONS
    432 
    433                     In order to modify text efficiently or insert redundant
    434                     bits of data, two primitives are available. The dot `.`
    435         .---,       primitive repeats the last change that was made in insert
    436         | . |       mode (e.g., writing down text after hitting the insert
    437         `---'       primitive `i`). Similarly, repeating the last selection
    438                     (e.g., make with the find primitive `f`) can be achieved
    439                     using the `<a-.>` primitive.
    440 
    441                     Example: to select a paragraph to append a newline
    442      .---, .---,    character to it and cycle through the following paragraphs
    443      |alt|+| . |    to repeat the same insertion an arbitrary amount of times,
    444      `---' `---'    one would first select the paragraph with `]p`, append a
    445                     newline to it `a<ret><esc>`, then repeat both operations
    446                     as needed with `<a-.>` and `.` respectively.
    447 
    448                     ==[ COMPLEX CHANGES
    449 
    450                     Transforming successive chunks of formatted data can
    451         .---,       be cumbersome when done manually, and lack hindsight
    452         | q |       when writing a script for that particular purpose
    453         `---'       non-interactively. The middle ground between the two
    454         .---,       solutions is to record the modifications made to one
    455         | Q |       chunk interactively, and replay the sequence of keys
    456         `---'       at will. The sequence in question is a macro: the `Q`
    457                     primitive will create a new one (i.e., record all the keys
    458 .---, .---,         hit henceforth until the escape key `<esc>` is hit), and
    459 |ctl|+| r |_.       the `q` primitive will replay the keys saved in the macro.
    460 `---' `---'  `.---,
    461               | @ | Notes: macros can easily be translated into a proper
    462               `---' script, as they are saved in the `@` register, which you
    463                     can insert into a buffer using `<c-r>@`.