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>@`.