-+=----------------------------------------------------------------------------=+
- _ _
- | | | |
- | | __ __ _ | | __ ___ _ _ _ __ ___
- | |/ / / _` | | |/ / / _ \ | | | | | '_ \ / _ \
- | < | (_| | | < | (_) | | |_| | | | | | | __/
- |_|\_\ \__,_| |_|\_\ \___/ \__,_| |_| |_| \___|
-
- Mawww's experiment for a better code editor
-+=----------------------------------------------------------------------------=+
-
-This walk-through is an introduction to Kakoune's basic editing capabilities
-to help new users transition over easily from another editor, or simply
-learn how to write and edit documents with style.
-
-During the learning period, it is useful to activate an automatically displayed
-contextual help for commands in normal mode: `:set -add global autoinfo normal`
-
-In the first section, you will learn about the primitives of the editing
-language to be able to get to a level of knowledge of the editor that
-guarantees that you can work with it efficiently.
-
-In the second section, for users who've gone through the basics and want to
-move on to more advanced functionalities, we explain other primitives whose
-role has a less dominant place in an everyday editing session, but still
-prove themselves powerful when used on the right occasion.
-
-Finally, as this document is in no way an exhaustive list of features, don't
-hesitate to check out the official documentation to complement your tool-set,
-ask questions to more seasoned users on IRC, and check the documentation
-using the built-in `:doc` command.
-
-+=--------------------------------=+ BASICS +=--------------------------------=+
-
- =[ MODES
-
- Kakoune uses a paradigm called "modal editing" to allow
- .---, users to either have every single key they type inserted
- | i | into the file being edited (called "insert mode"),
- `---' or execute commands that are triggered by the keys hit
- (the "normal mode"). Aside from arrow keys, most keys
- .---, described in this document are "editing primitives" that
- |esc| have to be hit in normal mode, which is the default mode
- `---' when you start the editor. To enter insert mode, hit the
- `i` key, and to leave it and return to normal mode, hit the
- escape key.
-
-
- =[ MOVEMENT
- .---,
- | ↑ | Movement in a buffer (the representation of the contents
- .---'---'---, of a file opened by Kakoune) can be achieved using the arrow
- | ← | ↓ | → | keys, which will move the cursor up one column/row into
- `---'---'---` a given direction.
-
- However, furthering the tradition of mode-based editors,
- .---,---,---,---, the `h`, `j`, `k` and `l` keys can be used for the same
- | h | j | k | l | purpose, and will respectively move the cursor to the
- `---'---'---'---` left, down, up, right by one, when hit. Using those keys
- | | | | is the recommended way of moving around in a buffer.
- .---,---,---,---, If you're not familiar with this concept, the proximity
- | ← | ↓ | ↑ | → | of those four keys with the rest of the lettered keys
- `---'---'---'---` on a `qwerty` layout allows faster interaction with the
- primitives than if the user had to move their hand to
- .---, reach the arrow keys.
- | g |_.
- `---' |`.---, Another way of moving the cursor is the "goto" utility,
- | | g | invoked by hitting the `g` key. A menu will pop up with a
- | `---' summary of all the possible keys that can be hit, along with
- `.---, the location where they will move the cursor to, but the
- | e | most used ones that we are interested in, for now, are `g`
- `---' and `e`. The first one will jump to the beginning of the
- buffer, and the second one to its end.
-
-
- =[ VIEW
-
- .---, Displacing the cursor can sometimes move the view into an
- | v |_. inconvenient configuration, leaving some necessary context
- `---' |`.---, off-screen, or simply feel uncomfortable to type into.
- | | t | Kakoune provides a menu (similar to the `goto` menu
- | `---' mentioned in the previous section) that allows users to
- |`.---, move the current view in relation to the position of the
- | | b | cursor. Upon hitting the `v` key, a short menu appears
- | `---' which allows us to hit a second key according to how the
- `.---, view should be centered vertically: to leave the cursor
- | v | respectively on top, at the bottom or in the middle of the
- `---' current view, hit the `t`, `b` or `v` keys.
-
-
- =[ SEARCH
-
- In order to move the cursor to a specific word, the search
- command is the way to go. This functionality allows
- .---, the user to jump to the next occurrence of a piece of text.
- | / | Upon hitting the `/` key, a prompt reading "search"
- `---' will pop up in the status bar in which you can type
- your text and validate using the `<ret>` (return) key.
- .---, .---, You'll notice that as you type, the cursor changes location
- |alt|+| / | to automatically give you a preview of where the cursor
- `---' `---' would be displaced to if you validated the search. However,
- this behavior is only a preview, exiting prompt mode with
- the `<esc>` (escape) key will leave the current position
- .---, of the cursor unchanged. Note that you can also use a
- | n | regular expression as input. By default the search
- `---' function will look for results forward, starting from
- the current location of the cursor, but you can search
- .---, .---, backwards using `<a-/>` (alt + `/`).
- |alt|+| n |
- `---' `---' Jumping from one match to the other forward can be achieved
- using the `n` key, and backwards using the `<a-n>` (alt +
- `n`) key combination.
-
-
- =[ SELECTIONS
-
- You have certainly noticed that when searching for
- .---, text, the cursor extends to highlight the entire match.
- | ; | In fact, what we know in other editors as a "cursor" is
- `---' actually a single character wide selection in Kakoune,
- and can be expanded using primitives. When "expanded",
- .---, .---, the selection is an area whose beginning is the "anchor"
- |alt|+| ; | and the end the "secondary cursor". To switch anchor and
- `---' `---' cursor, use `<a-;>`, and to collapse the selection onto
- its anchor, use `;`.
-
- Moreover, not only Kakoune expands the principle of
- "cursor" by introducing selections, but it also allows
- .---, multiple selections within the same buffer. This makes
- | % | it very convenient to modify text in multiple locations
- `---' at once, as editing primitives apply to all the currently
- selected text.
- .---,
- | s | Example: to remove all occurrences of the word "foo", one
- `---' would select the entire buffer (`%`), select occurrences of
- the word (`s`, "\bfoo\b", `<ret>`), then remove it (`d`).
-
- ==[ SELECTING OBJECTS
-
- In addition to allowing text selection using regular
- .---, .---, expressions, certain objects are defined by default to
- |alt|+| i | allow easy selection of text. Objects are bits of text
- `---' `---' in the buffer that are identified according to their
- structure, rather than their contents, e.g., a paragraph,
- .---, .---, a sentence, or a word. When the cursor is located within
- |alt|+| a | the boundaries of an object you want to interact with,
- `---' `---' several options are available: selecting the contents of an
- object without its boundaries (`<a-i>`), a part of it (from
- .---, the anchor to its end or its beginning, respectively `]`
- | ] | and `[`), or the entire object (`<a-a>`). Those "selection
- `---' ranges" are the first part of a two stages shortcut,
- as once you've used the key that dictates what part of
- .---, the object is to be selected, a menu with a description
- | [ | of all the object types select-able will be displayed,
- `---' giving a summary of all the keys you can hit to complete
- the selection procedure.
-
- Example: to select the paragraph in which the anchor lies,
- invoke the "inner object selection" shortcut (`<a-i>`),
- locate "paragraph" in the information box that pops up and
- .---, hit the according key (`p`). The entire two steps sequence
- | [ |_. is thus: `<a-i> p`.
- `---' |`.---,
- | | ( | Example: to select everything between the anchor and the
- | `---' beginning of the current parenthesis pair, use the selection
- `.---, sequence: `[ (`. Note that common objects that use
- | r | pairs of opening/closing punctuation signs (brackets,
- `---' braces, quotes etc) have an alternative second key that
- is displayed in the information menu that you can use to
- minimize finger gymnastics. The previous shortcut could
- thus also be written: `[ b`.
-
- ==[ MOVEMENT SELECTIONS
-
- If objects are an easy way to select content-agnostic
- .---, data in a buffer, they can also be seen as a way to move
- | [ |_. about the buffer. As selecting objects will displace the
- `---' `.---, anchor into a given direction, you can wrap or move around
- | p | particular chunks of text without using the conventional
- `---' means (e.g., arrow keys or jumps), turning them partially
- into movement primitives.
- .---,
- | ] |_. Example: one of the most used object selection combination
- `---' `.---, is the "object end/begin paragraph" one: using `[` or
- | p | `]` will displace the anchor into a given direction, and
- `---' applying that to the paragraph object allows "jumping"
- from one newline separated block of text to another.
- The resulting shortcut is thus: `] p` to move forward, or
- `[ p` to move backward.
-
-
- =[ FILTERING A SELECTION
-
- Selecting an entire buffer (`%`) or parts of it (`s`) is a
- natural and basic operation in a typical editing session,
- .---, .---, however, there are some cases where we need to be able to
- |alt|+| k | drop some selections arbitrarily, as opposed to trying
- `---' `---' to select the ones we need directly. This concept becomes
- very useful when coming up with a regular expression for
- .---, .---, the basic selection primitive (`s`) is too tedious (if
- |alt|+| K | even possible), that's why the editor provides us with a
- `---' `---' "keep matching" and a "keep not matching" operations,
- in order to respectively keep exclusively the selections
- who match or do not match a given regular expression.
-
- Example: when parsing a log file whose lines follow the
- usual log pattern (e.g. "[1484383442] ERROR: some data"),
- we want to be able to select all the lines individually
- .---, .---, (`%`, `<a-s>` to split all the lines), keep those that
- |alt|+| s | start with a bracketed time-stamp (`<a-k>^\[`), but
- `---' `---' exclude the debug messages (`<a-K>DEBUG`). Of course,
- it's possible to come up with a regular expression to
- match those simple requirements, but it would take more
- work to write it than to organically apply filters on a
- general selection, individually.
-
-
- =[ SELECTION DUPLICATION
-
- .---, Duplicating content can be achieved using a widely
- | y | implemented concept: yanking and pasting. Yanking the
- `---' current selection (`y`) into the copy register allows the
- .---, user to subsequently insert the copied text in the buffer
- | p | (`p`).
- `---'
- .---, Note that the default "paste" primitive will insert the
- | P | contents of the copy register after the current selection,
- `---' if you want copied text to be inserted before the current
- selection then you can use the `P` key.
-
-
- =[ DELETING / REPLACING SELECTIONS
-
- Text replacement is a two-step process in Kakoune, which
- .---, involves selecting text to be replaced, and then erasing it
- | d | to insert the replacement text. After selections have been
- `---' made, you can simply hit the deletion primitive (`d`), then
- .---, either enter insert mode to write down the replacement text
- | c | (`i`), or stay in command mode to paste the replacement
- `---' text stored in the copy register. As deleting and entering
- .---, insert mode can be redundant, a primitive that implements
- | R | deletion followed by insert mode entrance was implemented:
- `---' `c`. You can also directly replace the current selection
- with the content of the copy register using a primitive
- also implemented for that purpose: `R`.
-
-
- =[ UNDO / REDO
-
- Mistakes or wrong decisions can happen while editing.
- .---, To go back to earlier states of the buffer, you can press
- | u | the `u` key several times. On the contrary, pressing `U`
- `---' allows traveling forward in the history tree.
-
-
-+=-------------------------------=+ ADVANCED +=-------------------------------=+
-
- =[ SPLITTING
-
- The selection primitive (`s`) is a powerful tool to select
- chunks of data, but sometimes the format of said data isn't
- .---, uniform enough to allow creating clear cut selections. In
- | S | order to avoid having to write overly complicated regular
- `---' expressions that select precisely the wanted text, the
- splitting primitive (`S`) allows applying a delimiter to
- the current selection, splitting it into separate chunks.
-
- Example: selecting the items in a CSV-style list (e.g.,
- "1,2,3,4") is as simple as selecting the line, then
- splitting it using the comma separator (`S,`). Note that
- more advanced splitting is possible, since the delimiter
- passed to this primitive is a regular expression.
-
-
- =[ ROTATING
-
- Often used in conjunction with the splitting primitive
- (`S`), the rotation primitive (`<a-)>`) shifts all the
- selections clock-wise. Note that a count (described after)
- allows the rotation to take place in sub-groups whose size
- .---, .---, is given by the count parameter.
- |alt|+| ) |
- `---' `---' Example: in a numbered list where all the numbers are
- selected (e.g., `1 2 3 4 5 6 7 8 9 0`), a rotation using
- this primitive will shift all the numbers by one selection
- forward, while leaving the original multiple selections
- untouched (e.g., `0 1 2 3 4 5 6 7 8 9`).
-
-
- =[ COUNTS
-
- .---, In order to pass a count to a primitive, simply type the
- |0-9|_. number out before hitting the primitive key/combination.
- `---' |`.---, Counts allow primitives to specialize or extend their
- | | g | original functionality by using it as a parameter,
- | `---' acting on their side effect.
- |`.---,
- | | G | Example: in order to respectively jump or select up to a
- | `---' particular line, pass the line number to the `g` or `G`
- |`.---, primitives (e.g., `42g` or `7G`).
- | | o |
- | `---' Example: creating an arbitrary amount of new lines
- `.---, above or below the current line and spawning a new selection
- | O | for each of them is achieved by passing the number of lines
- `---' as a count respectively to the `o` and `O` primitives.
-
-
- =[ REGISTERS
-
- Similarly to counts, registers influence the behavior of
- .---, certain primitives. They are storage structures identified
- | " |_. by a single character, and are populated by primitives as a
- `---' `.---, result of a side effect. Although primitives populate a
- |a-z| specific register by default, it's possible to modify which
- `---' is going to be populated upon execution using the double
- quote (`"`) primitive, and subsequently hitting a key that
- .---, will serve as an identifier.
- | * |
- `---' Example: the smart search primitive (`*`) uses the current
- selection as a search pattern, which will be saved to the
- .---, `/` register. In order to use this primitive to execute a
- | " |_. .---, temporary search, one could make this primitive save the
- `---' `| _ | pattern to a different register, to preserve the default one,
- `---' e.g., `"m*` to save the pattern to the `m` register, or even
- `"_*` to save the pattern to a "null" register, which does
- not store anything written to it.
-
- ==[ CAPTURE GROUPS
-
- Although registers can pass as mere buffer metadata,
- .---, .---, they are an integral part of an editing session. The
- |ctl|+| r | `<c-r>` key combination allows to insert into the buffer
- `---' `---' the value of a register, whose identifier is typed right
- after the combination.
-
-.---, .---, Example: inserting the name of the current buffer in insert
-|ctl|+| r |_. mode can be achieved using the `%` register, which holds
-`---' `---' `.---, this information: `<c-r>%`.
- | % |
- `---' Other registers that are set automatically are
- the numbered registers, which hold the values of the groups
- matched in the last search or select operation (`/` and
-.---, .---, `s` primitives).
-|ctl|+| r |_.
-`---' `---' `.---, Example: when using the search primitive (`/`) with a
- |0-9| regular expression containing groups to match a list of
- `---' first and last names (e.g., `(\w+) (\w+)` on `John Doe`),
- issuing `<c-r>1` would insert the first name (`John`),
- and `<c-r>2` the last name (`Doe`).
-
-
- =[ CUSTOM SELECTIONS
-
- Despite the ability to select bits of data using regular
- expressions, there are times when using them isn't enough,
- and additional manual editing of the selections is
- .---, needed. In order to loop through all the selections and
- | ) | remove the current one, two primitives are available:
- `---' respectively the parenthesis (`)`), and the alt/comma
- key combination (`<a-,>`).
- .---, .---,
- |alt|+| , | Example: given a list of three numbers all selected
- `---' `---' individually, (e.g., `1 2 3`), deselecting the second
- selection would be done by hitting the parenthesis primitive
- (`)`) until the according selection is the current one,
- then hitting `<a-,>` to end up with only the first
- and third number selected.
-
- However, being able to trim out some selections out
- .---, of a bigger set isn't always convenient, as it doesn't
- | ^ | allow more advanced constructs such as combining sets of
- `---' multiple-selections that result from different regular
- .---, expressions. To allow that, the save mark (`Z`) and append
- | Z | mark (`<a-z>`) come in handy, as they respectively save
- `---' the current selection to the mark register (`^`), and
- show a menu that allows appending the current selection
-.---, .---, to the mark register upon hitting the `a` key. That way,
-|alt|+| z |_. it becomes possible to chain and save (append) several
-`---' `---' `.---, selections made using completely different methods
- | a | (select, split etc) without being forced to preserve
- `---' them at all times.
- .---,
- | z | Restoring a mark saved to the mark register using those
- `---' primitives can be achieved by using the restore mark
- primitive (`z`).
-
-
- =[ LEVERAGING SHELL COMMANDS
-
- UNIX systems provide with some tools whose purpose is
- to interact with raw data, and being a UNIX compliant
- .---, aspiring tool itself, Kakoune allows leveraging those
- | | | tools to modify a buffer's contents. Upon invoking the pipe
- `---' primitive (`|`), an input field pops up which prompts for
- a shell command, to which the selections will individually
- be sent through the command's standard input.
-
- Example: wrapping a selection can be achieved by invoking
- the `fold` utility, e.g., `|fold -w80`. You could also want
- to see a patch of all the modifications made to the buffer
- since it was last saved: `%|diff -u <c-r>% -`. Note that
- the `<c-r>%` has to be typed interactively, as it will
- insert the name of the buffer into the command.
-
- Another equally useful primitive that doesn't depend on
- .---, the contents of the current selections is the exclamation
- | ! | mark primitive (`!`), which simply insert the output of
- `---' the given shell command before each selection.
-
- Example: in order to insert the date of the day at the
- beginning of the current buffer, one could use `gg`
- followed with `!date`.
-
- But not all shell-related primitives insert data into
- the current buffer, the `$` key is in fact a way to
- .---, apply a predicate to all selections, in order to filter
- | $ | them out. The command passed to this primitive will be
- `---' executed in a new shell using each individual selection for
- context, which will either be kept if the command returned
- a successful exit code (zero) or dropped otherwise (any
- non-zero value).
-
- Example: after selecting all the lines in a buffer and
- splitting them individually (`%`, `<a-s>`), keeping every
- odd-numbered line can be achieved with the following
- sequence: `$` `[ $((kak_reg_hash)) -ne 0 ]`.
-
-
- =[ REPEATING ACTIONS
-
- ==[ PUNCTUAL INTERACTIONS
-
- In order to modify text efficiently or insert redundant
- bits of data, two primitives are available. The dot `.`
- .---, primitive repeats the last change that was made in insert
- | . | mode (e.g., writing down text after hitting the insert
- `---' primitive `i`). Similarly, repeating the last selection
- (e.g., make with the find primitive `f`) can be achieved
- using the `<a-.>` primitive.
-
- Example: to select a paragraph to append a newline
- .---, .---, character to it and cycle through the following paragraphs
- |alt|+| . | to repeat the same insertion an arbitrary amount of times,
- `---' `---' one would first select the paragraph with `]p`, append a
- newline to it `a<ret><esc>`, then repeat both operations
- as needed with `<a-.>` and `.` respectively.
-
- ==[ COMPLEX CHANGES
-
- Transforming successive chunks of formatted data can
- .---, be cumbersome when done manually, and lack hindsight
- | q | when writing a script for that particular purpose
- `---' non-interactively. The middle ground between the two
- .---, solutions is to record the modifications made to one
- | Q | chunk interactively, and replay the sequence of keys
- `---' at will. The sequence in question is a macro: the `Q`
- primitive will create a new one (i.e., record all the keys
-.---, .---, hit henceforth until the escape key `<esc>` is hit), and
-|ctl|+| r |_. the `q` primitive will replay the keys saved in the macro.
-`---' `---' `.---,
- | @ | Notes: macros can easily be translated into a proper
- `---' script, as they are saved in the `@` register, which you
- can insert into a buffer using `<c-r>@`.
+# Kakoune
+
+set verbose mode (good for learning)
+`:set -add global autoinfo normal`
+
+## Movement
+
+### Goto
+
+`10g` - go to line 10
+
+`g` +
+
+`g` - buffer start
+
+`e` - buffer end
+
+`j` - buffer bottom
+
+`t` - window top
+
+`c` - window center
+
+`b` - window bottom
+
+
+`l` - line end
+
+`h` - line begin
+
+`i` - line non blank start
+
+### Align screen relative to cursor (Vim z+)
+
+`v` +
+
+`v` - center vertically
+
+`m` - center horizontally
+
+`t` - top
+
+`b` - bottom
+
+`h`, `j`, `k`, `l` - scroll one char
+
+### Search
+
+`/ <a-/>` - start search forward (backward)
+
+`n <a-n>` - search next search pattern forward (backward)
+
+`N <a-N>` - extend next search pattern forward (backward)
+
+### Selections
+
+`%` - select whole buffer
+
+`s` - select (find) regex in selected text
+
+`<a-S>` - select first and last char of selection(s)
+
+`<a-s>` - split selection on line ends
+
+`S` - split selection on given regex
+
+`x` - select line (`X` - next line below)
+
+`<a-x>` - extend selections to whole lines
+
+`<a-X>` - crop selections to whole lines
+
+`<a-;>` - switch anchor and cursor
+
+`;` - collapse selection to its anchor (one char, effectively reduce selection to one char)
+
+`<a-i>` - select inner object
+
+`<a-a>` - select all object (paragraph, sentence, etc)
+
+`[` - select to beginning of an object; `<a-[` - inner object
+
+`{` - extend to beginning of an object; `<a-{` - inner object
+
+`]` - select to the end of an object; `<a-]` - inner object
+
+`}` - extend to beginning of an object; `<a-}` - inner object
+
+`<a-s>` - split selected text on line ends
+
+`<a-k>` - select lines matching regexp inside selection
+
+`<a-K>` - select lines NOT matching regexp inside selection
+
+`7G` - select to line 7
+
+`<a-h>` - select until beginning of; line like Vim `0`
+
+`<a-l>` - select until end of line; like Vim `$`
+
+`m` - match paranthesis; like Vim's `%`, select parans and content inside
+
+`<a-m>` - match parens backwards (direction)
+
+`M` - get a selection from current cursor to next block end or rather extend to next parans included
+
+`<a-M>` - extend to prev parens
+
+`f` - select to next char included (`<a-f>` - prev char)
+
+`C` - copy selection on next lines (`<a-C>` - previus lines)
+
+`<a-&>` - copy identation
+
+`Z` - save selection in mark register `^`
+
+`z` - restore selections stored in register `^`
+
+`<a-z>` - combine selection from register, confirm by hitting `a` for example
+
+`<a-Z>` - combine selections to register
+
+`<space>` - remove all selections except main
+
+`<a-space>` - remove main selection
+
+`_` - trim selections
+
+### Text manipulation
+
+`y` - yank
+
+`p` - paste after (`P` before)
+
+`<a-p>` - paste every yanked selection after selected text, keep new (pasted) selection (`<a-P>` before)
+
+`d` - delete
+
+`i` - instert
+
+`c` - delete and inserst
+
+`R` - replace selection with the content of the register
+
+`<a-R>` - replace selected text with yanked text
+
+`u` - undo
+
+`U` - redo
+
+`<a-j>` - join with next line (`<a-J>` include spaces)
+
+`backtick` - convert to lower-case (`<a-backtick>` - swap case)
+
+`~` - convert to upper-case
+
+`o` - insert on new line below (`O` above)
+
+`<a-o>` - add new line below (`<a-O>` above)
+
+## Advanced
+
+`)` - loop through selections (`(` backward)
+
+`<a-)>` - rotate splitted selection clock-wise (`<a-(>` counter clock-wise)
+
+`"m*` - save smart search (*) pattern to register `m` (`_` is a null register)
+
+`<c-r>` - instert into the buffer value stored in the register (`%` - buffer name, etc.); numbers correspond to submatches, like `(\w+)`
+
+`.` - repeat last insert session
+
+`<a-.>` - repeat last selection (for example `]p`); like Vim' `;`
+
+`Q` - start recording macro until `Esc` is hit
+
+`q` - replay the macro (saved in the `@` register)
+
+### Shell
+
+`|` - modify selections by passind to the shell command which will transform them and write back (`<a-|>` will ignore results)
+
+`!` - insert a result of the shell cmd before selections (`<a-!>` - append result)
+
+`$` - apply predicate to selections (0 return value is considered a success); filiter them
+
+### Tips
+
+`|fold -w80` - wrap selection
+
+`!date` - insert date before selection
+
+`$xsel -bi` - copy selection to clipboard. `-bi` stands for `--clipboard --input`
+
+`%|diff -u <c-r>% -` - compare current buffer contents with the version saved to disk
+
+`<a-;>` insert mode -> normal mode (for one cmd) -> back, preseving selections/bindings, modes can be deeply nested (hit Esc more than once if needed)
+
+The couple `u` and `U` lets you move backward and forward in the last branch while their alternative versions `<a-u>` `<a-U>` follow absolute history id which may be located somewhere else in the history tree.
+
projects / dotfiles.git / commitdiff