Remove duplicated documentation from the README
Just point towards the relevant doc page.
This commit is contained in:
Maxime Coste
parent
ed65d86c72
commit
6bc408e9b9
541
README.asciidoc
541
README.asciidoc
|
|
@ -1,4 +1,5 @@
|
||||||
= image:{logo}[K,30,30,link="{website}"] Kakoune image:{travis-img}[link="{travis-url}"] image:{irc-img}[link="{irc-url}"]
|
= image:{logo}[K,30,30,link="{website}"] Kakoune image:{travis-img}[link="{travis-url}"] image:{irc-img}[link="{irc-url}"]
|
||||||
|
ifdef::env-github,env-browser[:outfilesuffix: .asciidoc]
|
||||||
:logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg
|
:logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg
|
||||||
:website: http://kakoune.org
|
:website: http://kakoune.org
|
||||||
:travis-img: https://travis-ci.org/mawww/kakoune.svg?branch=master
|
:travis-img: https://travis-ci.org/mawww/kakoune.svg?branch=master
|
||||||
|
|
@ -733,126 +734,10 @@ Multiple commands can be separated either by new lines or by semicolons,
|
||||||
as such a semicolon must be escaped with `\;` to be considered as a literal
|
as such a semicolon must be escaped with `\;` to be considered as a literal
|
||||||
semicolon argument.
|
semicolon argument.
|
||||||
|
|
||||||
String syntax
|
String syntax and expansions
|
||||||
~~~~~~~~~~~~~
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
When entering a command, parameters are separated by whitespace (shell like),
|
See <<doc/pages/expansions#,`:doc expansions`>>.
|
||||||
if you want to give parameters with spaces, you should quote them.
|
|
||||||
|
|
||||||
Kakoune support three string syntax:
|
|
||||||
|
|
||||||
* `'strings'`: uninterpreted strings, you can use `\'` to escape the separator,
|
|
||||||
every other char is itself.
|
|
||||||
|
|
||||||
* `"strings"`: expanded strings, % strings (see <<Expansions>>) contained
|
|
||||||
are expended. Use \% to escape a % inside them, and \\ to escape a slash.
|
|
||||||
|
|
||||||
* `%{strings}`: these strings are very useful when entering commands
|
|
||||||
|
|
||||||
- the `{` and `}` delimiters are configurable: you can use any non
|
|
||||||
alphanumeric character, e.g. `%[string]`, `%<string>`, `%(string)`,
|
|
||||||
`%\~string~`, `%!string!`.
|
|
||||||
- if the character following the % is one of {[(<, then the closing one is
|
|
||||||
the matching }])> and the delimiters are not escapable but are nestable.
|
|
||||||
For example `%{ roger {}; }` is a valid string, `%{ marcel \}` as well.
|
|
||||||
|
|
||||||
Expansions
|
|
||||||
^^^^^^^^^^
|
|
||||||
|
|
||||||
A special kind of `%{strings}` can be used, with a type between
|
|
||||||
`%` and the opening delimiter (which cannot be alphanumeric). These
|
|
||||||
strings are expanded according to their type.
|
|
||||||
|
|
||||||
For example `%opt{autoinfo}` is of type 'opt'. 'opt' expansions are replaced
|
|
||||||
by the value of the given option (here `autoinfo`).
|
|
||||||
|
|
||||||
Supported types are:
|
|
||||||
|
|
||||||
* `sh`: shell expansion, similar to posix shell $(...) construct, see
|
|
||||||
<<Shell expansion>> for more details.
|
|
||||||
* `reg`: register expansion, will be replaced by the content of the given
|
|
||||||
register.
|
|
||||||
* `opt`: option expansion, will be replaced with the value of the given
|
|
||||||
option
|
|
||||||
* `val`: value expansion, gives access to the environment variable available
|
|
||||||
to the Shell expansion. The `kak_` prefix is not used there.
|
|
||||||
* `arg`: argument expansion, gives access to the arguments of the current
|
|
||||||
command, the content can be a number, or `@` for all arguments.
|
|
||||||
|
|
||||||
For example, you can display last search pattern with
|
|
||||||
|
|
||||||
-------------
|
|
||||||
:echo %reg{/}
|
|
||||||
-------------
|
|
||||||
|
|
||||||
Shell expansion
|
|
||||||
^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The `%sh{...}` expansion replaces its content with the output of the shell
|
|
||||||
commands in it. It is similar to the shell $(...) syntax and is evaluated
|
|
||||||
only when needed.
|
|
||||||
|
|
||||||
For example: `%sh{ ls }` is replaced with the output of the ls command.
|
|
||||||
|
|
||||||
Some of Kakoune state is available through environment variables:
|
|
||||||
|
|
||||||
* `kak_selection`: content of the main selection
|
|
||||||
* `kak_selections`: content of the selection separated by colons, colons and backslashes in
|
|
||||||
the selection contents are escaped with a backslash.
|
|
||||||
* `kak_selection_desc`: range of the main selection, represented as `anchor,cursor`;
|
|
||||||
anchor and cursor are in this format: `line.column`
|
|
||||||
* `kak_selections_desc`: range of the selections separated by colons
|
|
||||||
* `kak_bufname`: name of the current buffer
|
|
||||||
* `kak_buffile`: full path of the file or same as `kak_bufname` when
|
|
||||||
there's no associated file
|
|
||||||
* `kak_buflist`: the current buffer list, each buffer separated by a colon
|
|
||||||
* `kak_buf_line_count`: the current buffer line count
|
|
||||||
* `kak_timestamp`: timestamp of the current buffer, the timestamp is an
|
|
||||||
integer value which is incremented each time the buffer is modified.
|
|
||||||
* `kak_history_id`: history id of the current buffer, the history id is an integer value
|
|
||||||
which is used to reference a specific buffer version in the undo tree
|
|
||||||
* `kak_runtime`: directory containing the kak binary
|
|
||||||
* `kak_count`: count parameter passed to the command
|
|
||||||
* `kak_opt_<name>`: value of option <name>
|
|
||||||
* `kak_reg_<r>`: value of register <r>
|
|
||||||
* `kak_session`: name of the current session
|
|
||||||
* `kak_client`: name of the current client
|
|
||||||
* `kak_client_pid`: pid of the current client
|
|
||||||
* `kak_client_list`: list of clients connected to the current session
|
|
||||||
* `kak_modified`: buffer has modifications not saved
|
|
||||||
* `kak_source`: path of the file currently getting executed (through the source command)
|
|
||||||
* `kak_cursor_line`: line of the end of the main selection
|
|
||||||
* `kak_cursor_column`: column of the end of the main selection (in byte)
|
|
||||||
* `kak_cursor_char_value`: unicode value of the codepoint under the cursor
|
|
||||||
* `kak_cursor_char_column`: column of the end of the main selection (in character)
|
|
||||||
* `kak_cursor_byte_offset`: offset of the main selection from the beginning of the buffer (in byte).
|
|
||||||
* `kak_window_width`: width of the current kakoune window
|
|
||||||
* `kak_window_height`: height of the current kakoune window
|
|
||||||
* `kak_hook_param`: filtering text passed to the currently executing hook
|
|
||||||
* `kak_hook_param_capture_N`: text captured by the hook filter regex capture N
|
|
||||||
* `kak_client_env_<name>`: value of the <name> variable in the client environment.
|
|
||||||
Example: $kak_client_env_SHELL is the SHELL variable
|
|
||||||
|
|
||||||
Note that in order to make only needed information available, Kakoune needs
|
|
||||||
to find the environment variable reference in the shell script executed.
|
|
||||||
Hence, `%sh{ ./script.sh }` with `script.sh` referencing an environment
|
|
||||||
variable will not work.
|
|
||||||
|
|
||||||
For example, you can print informations on the current file in the status
|
|
||||||
line using:
|
|
||||||
|
|
||||||
------------------------------------
|
|
||||||
:echo -- "%sh{ ls -l $kak_bufname }"
|
|
||||||
------------------------------------
|
|
||||||
|
|
||||||
Markup strings
|
|
||||||
^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
In certain context, kakoune can take a markup string, which is a string containing
|
|
||||||
formatting informations. In these strings, syntax `{facename}` will enable the
|
|
||||||
face _facename_ until another face gets activated (or the end of the string.
|
|
||||||
Literal `{` shall be written `\{`, and literal `\` that precede a `{` shall
|
|
||||||
be written `\\`
|
|
||||||
|
|
||||||
Configuration & Autoloading
|
Configuration & Autoloading
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
@ -889,260 +774,21 @@ precedence.
|
||||||
Options
|
Options
|
||||||
-------
|
-------
|
||||||
|
|
||||||
For user configuration, Kakoune supports options.
|
See <<doc/pages/options#,`:doc options`>>.
|
||||||
|
|
||||||
Options are typed, their type can be
|
|
||||||
|
|
||||||
* `int`: an integer number
|
|
||||||
* `bool`: a boolean value, `yes/true` or `no/false`
|
|
||||||
* `str`: a string, some freeform text
|
|
||||||
* `coord`: a line,column pair (separated by comma)
|
|
||||||
* `regex`: as a string but the `set` commands will complain
|
|
||||||
if the entered text is not a valid regex.
|
|
||||||
* `{int,str}-list`: a list, elements are separated by a colon (:)
|
|
||||||
if an element needs to contain a colon, it can be escaped with a
|
|
||||||
backslash.
|
|
||||||
* `range-specs`: a `:` separated list of a pair of a buffer range
|
|
||||||
(`<begin line>.<begin column>,<end line>.<end column>` or
|
|
||||||
`<begin line>.<end line>+<length>`) and a string (separated by `|`),
|
|
||||||
except for the first element which is just the timestamp of the buffer.
|
|
||||||
* `line-flags`: a `:` separated list of a line number and a corresponding
|
|
||||||
flag (`<line>|<flag text>`), except for the first element which is just
|
|
||||||
the timestamp of the buffer.
|
|
||||||
* `completions`: a `:` separated list of `<text>|<docstring>|<menu text>`
|
|
||||||
candidates, except for the first element which follows the
|
|
||||||
`<line>.<column>[+<length>]@<timestamp>` format to define where the
|
|
||||||
completion apply in the buffer. Markup can be used in the menu text.
|
|
||||||
* `enum(value1|value2|...)`: an enum, taking on of the given values
|
|
||||||
* `flags(value1|value2|...)`: a set of flags, taking a combination
|
|
||||||
of the given values joined by `|`.
|
|
||||||
|
|
||||||
Options value can be changed using the `set` commands:
|
|
||||||
|
|
||||||
------------------------------------------------------------------------------
|
|
||||||
:set [global,buffer,window] <option> <value> # buffer, window, or global scope
|
|
||||||
------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
Option values can be different by scope, an option can have a global
|
|
||||||
value, a buffer value and a window value. The effective value of an
|
|
||||||
option depends on the current context. If we have a window in the
|
|
||||||
context (interactive edition for example), then the window value
|
|
||||||
(if any) is used, if not we try the buffer value (if we have a buffer
|
|
||||||
in the context), and if not we use the global value.
|
|
||||||
|
|
||||||
That means that two windows on the same buffer can use different options
|
|
||||||
(like different filetype, or different tabstop). However, some options
|
|
||||||
might end up ignored if their scope is not in the command context:
|
|
||||||
|
|
||||||
Writing a file never uses the window options for example, so any
|
|
||||||
options related to writing won't be taken into account if set in the
|
|
||||||
window scope (`BOM` or `eolformat` for example).
|
|
||||||
|
|
||||||
New options can be declared using the `:decl` command:
|
|
||||||
|
|
||||||
---------------------------------------
|
|
||||||
:decl [-hidden] <type> <name> [<value>]
|
|
||||||
---------------------------------------
|
|
||||||
|
|
||||||
The `-hidden` parameter makes the option invisible in completion, but
|
|
||||||
still modifiable.
|
|
||||||
|
|
||||||
Some options are built in Kakoune, and can be used to control its behaviour:
|
|
||||||
|
|
||||||
* `tabstop` _int_: width of a tab character.
|
|
||||||
* `indentwidth` _int_: width (in spaces) used for indentation.
|
|
||||||
0 means a tab character.
|
|
||||||
* `scrolloff` _coord_: number of lines,columns to keep visible around
|
|
||||||
the cursor when scrolling.
|
|
||||||
* `eolformat` _enum(lf|crlf)_: the format of end of lines when
|
|
||||||
writing a buffer, this is autodetected on load; values of this option
|
|
||||||
assigned to the `window` scope are ignored
|
|
||||||
* `BOM` _enum(none|utf8)_: define if the file should be written
|
|
||||||
with a unicode byte order mark. Values of this option assigned to the
|
|
||||||
`window` scope are ignored
|
|
||||||
* `readonly` _bool_: prevent modifications from being saved to disk, all
|
|
||||||
buffers if set to `true` in the `global` scope, or current buffer if set in
|
|
||||||
the `buffer` scope; values of this option assigned to the `window` scope are
|
|
||||||
ignored
|
|
||||||
* `incsearch` _bool_: execute search as it is typed
|
|
||||||
* `aligntab` _bool_: use tabs for alignment command
|
|
||||||
* `autoinfo` _flags(command|onkey|normal)_: display automatic information
|
|
||||||
box in the enabled contexts.
|
|
||||||
* `autoshowcompl` _bool_: automatically display possible completions when
|
|
||||||
editing a prompt.
|
|
||||||
* `ignored_files` _regex_: filenames matching this regex won't be considered
|
|
||||||
as candidates on filename completion (except if the text being completed
|
|
||||||
already matches it).
|
|
||||||
* `disabled_hooks` _regex_: hooks whose group matches this regex won't be
|
|
||||||
executed. For example indentation hooks can be disabled with '.*-indent'.
|
|
||||||
* `filetype` _str_: arbitrary string defining the type of the file
|
|
||||||
filetype dependant actions should hook on this option changing for
|
|
||||||
activation/deactivation.
|
|
||||||
* `path` _str-list_: directories to search for gf command.
|
|
||||||
* `completers` _str-list_: completion systems to use for insert mode
|
|
||||||
completion. The given completers are tried in order until one generate some
|
|
||||||
completion candidates. Existing completers are:
|
|
||||||
- `word=all` or `word=buffer` which complete using words in all buffers
|
|
||||||
(`word=all`) or only the current one (`word=buffer`)
|
|
||||||
- `filename` which tries to detect when a filename is being entered and
|
|
||||||
provides completion based on local filesystem.
|
|
||||||
- `line` which complete using lines in current buffer
|
|
||||||
- `option=<opt-name>` where <opt-name> is a _completions_ option.
|
|
||||||
* `static_words` _str-list_: list of words that are always added to completion
|
|
||||||
candidates when completing words in insert mode.
|
|
||||||
* `extra_word_chars` _codepoint-list_: list of all additional codepoints
|
|
||||||
that should be considered as word character for the purpose of insert mode
|
|
||||||
completion.
|
|
||||||
* `autoreload` _enum(yes|no|ask)_: auto reload the buffers when an external
|
|
||||||
modification is detected.
|
|
||||||
* `debug` _flags(hooks|shell|profile|keys|commands)_: dump various debug information in
|
|
||||||
the `*debug*` buffer.
|
|
||||||
* `idle_timeout` _int_: timeout, in milliseconds, with no user input that will
|
|
||||||
trigger the `PromptIdle`, `InsertIdle` and `NormalIdle` hooks, and autocompletion.
|
|
||||||
* `fs_checkout_timeout` _int_: timeout, in milliseconds, between checks in
|
|
||||||
normal mode of modifications of the file associated with the current buffer
|
|
||||||
on the filesystem.
|
|
||||||
* `modelinefmt` _string_: A format string used to generate the mode line, that
|
|
||||||
string is first expanded as a command line would be (expanding `%...{...}`
|
|
||||||
strings), then markup tags are applied (see <<Markup strings>>). Two special
|
|
||||||
atom are available as markup: `{{mode_info}}` with information about the current
|
|
||||||
mode (example `insert 3 sel`), and `{{context_info}}` with information such as
|
|
||||||
if the file has been modified (with `[+]`), or if it is new (with `[new file]`).
|
|
||||||
* `ui_options`: colon separated list of key=value pairs that are forwarded to
|
|
||||||
the user interface implementation. The NCurses UI support the following options:
|
|
||||||
- `ncurses_set_title`: if `yes` or `true`, the terminal emulator title will
|
|
||||||
be changed.
|
|
||||||
- `ncurses_status_on_top`: if `yes`, or `true` the status line will be placed
|
|
||||||
at the top of the terminal rather than at the bottom.
|
|
||||||
- `ncurses_assistant`: specify the nice assistant you get in info boxes, can
|
|
||||||
be 'clippy' (the default), 'cat', 'dilbert' or 'none'
|
|
||||||
- `ncurses_enable_mouse`: boolean option that enables mouse support
|
|
||||||
- `ncurses_change_colors`: boolean option that can disable color palette
|
|
||||||
changing if the terminfo enables it but the terminal does not support it.
|
|
||||||
- `ncurses_wheel_down_button` and `ncurses_wheel_up_button`: specify which
|
|
||||||
button send for wheel down/up events.
|
|
||||||
|
|
||||||
Faces
|
|
||||||
-----
|
|
||||||
|
|
||||||
A Face refers how the specified text is displayed. A face has a foreground
|
|
||||||
color, a background color, and some attributes.
|
|
||||||
|
|
||||||
Faces can be defined and modified with the face command:
|
|
||||||
|
|
||||||
-----------------------
|
|
||||||
:face <name> <facespec>
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
Any place requiring a face can take either a face name defined with the `face`
|
|
||||||
command or a direct face description (called _facespec_) with the following
|
|
||||||
syntax:
|
|
||||||
|
|
||||||
--------------------------------
|
|
||||||
fg_color[,bg_color][+attributes]
|
|
||||||
--------------------------------
|
|
||||||
|
|
||||||
fg_color and bg_color can be:
|
|
||||||
|
|
||||||
* A named color: `black, red, green, yellow, blue, magenta, cyan, white`.
|
|
||||||
* A named bright color: `bright-black, bright-red, bright-green, bright-yellow, bright-blue, bright-magenta, bright-cyan, bright-white`.
|
|
||||||
* `default`, which keeps the existing color
|
|
||||||
* An rgb color: `rgb:RRGGBB`, with RRGGBB the hexadecimal value of the color.
|
|
||||||
|
|
||||||
Not specifying bg_color uses `default`
|
|
||||||
|
|
||||||
`attributes` is a string of letters each defining an attribute:
|
|
||||||
|
|
||||||
* `u`: Underline
|
|
||||||
* `r`: Reverse
|
|
||||||
* `b`: Bold
|
|
||||||
* `B`: Blink
|
|
||||||
* `d`: Dim
|
|
||||||
* `i`: Italic
|
|
||||||
* `e`: Exclusive, override previous faces instead of merging with them
|
|
||||||
|
|
||||||
Using named faces instead of facespec permits to change the effective faces
|
|
||||||
afterwards.
|
|
||||||
|
|
||||||
There are some builtins faces used by internal Kakoune functionalities:
|
|
||||||
|
|
||||||
* `Default`: default colors
|
|
||||||
* `PrimarySelection`: main selection face for every selected character except
|
|
||||||
the cursor
|
|
||||||
* `SecondarySelection`: secondary selection face for every selected character
|
|
||||||
except the cursor
|
|
||||||
* `PrimaryCursor`: cursor of the primary selection
|
|
||||||
* `SecondaryCursor`: cursor of the secondary selection
|
|
||||||
* `LineNumbers`: face used by the number_lines highlighter
|
|
||||||
* `LineNumberCursor`: face used to highlight the line number of the main
|
|
||||||
selection
|
|
||||||
* `LineNumbersWrapped`: face used to highlight the line number of wrapped
|
|
||||||
lines
|
|
||||||
* `MenuForeground`: face for the selected element in menus
|
|
||||||
* `MenuBackground`: face for the not selected elements in menus
|
|
||||||
* `Information`: face for the information windows and information messages
|
|
||||||
* `Error`: face of error messages
|
|
||||||
* `StatusLine`: face used for the status line
|
|
||||||
* `StatusCursor`: face used for the status line cursor
|
|
||||||
* `Prompt`: face used prompt displayed on the status line
|
|
||||||
* `MatchingChar`: face used by the show_matching highlighter
|
|
||||||
* `Search`: face used to highlight search results
|
|
||||||
* `BufferPadding`: face applied on the characters that follow the last line of a buffer
|
|
||||||
* `Whitespace`: face used by the show_whitespaces highlighter
|
|
||||||
|
|
||||||
Advanced topics
|
Advanced topics
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
|
Faces
|
||||||
|
-----
|
||||||
|
|
||||||
|
See <<doc/pages/faces#,`:doc faces`>>.
|
||||||
|
|
||||||
Registers
|
Registers
|
||||||
~~~~~~~~~
|
~~~~~~~~~
|
||||||
|
|
||||||
Registers are named lists of text. They are used for various purposes, like
|
See <<doc/pages/registers#,`:doc registers`>>.
|
||||||
storing the last yanked text, or the captured groups associated with the
|
|
||||||
selections.
|
|
||||||
|
|
||||||
Yanking and pasting uses the register `"`, however most commands using a register
|
|
||||||
can have their default register overridden by using the `"` key followed by the
|
|
||||||
register. For example `"sy` will yank (`y` command) in the `s` register. `"sp`
|
|
||||||
will paste from the `s` register.
|
|
||||||
|
|
||||||
While in insert mode or in a prompt, `<c-r>` followed by a register name
|
|
||||||
(one character) inserts it.
|
|
||||||
|
|
||||||
For example, `<c-r>` followed by " will insert the currently yanked text.
|
|
||||||
`<c-r>` followed by 2 will insert the second capture group from the last regex
|
|
||||||
selection.
|
|
||||||
|
|
||||||
Registers are lists, instead of simply text in order to interact well with
|
|
||||||
multiselection. Each selection has its own captures or yank buffer.
|
|
||||||
|
|
||||||
Alternate names
|
|
||||||
^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Non alphanumeric registers have an alternative name that can be used
|
|
||||||
in contexts where only alphanumeric identifiers are possible.
|
|
||||||
|
|
||||||
Special registers
|
|
||||||
^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Some registers are not general purposes, they cannot be written to, but they
|
|
||||||
contain some special data:
|
|
||||||
|
|
||||||
* `%` (`percent`): current buffer name
|
|
||||||
* `.` (`dot`): current selection contents
|
|
||||||
* `#` (`hash`): selection indices (first selection has 1, second has 2, ...)
|
|
||||||
* `_` (`underscore`): null register, always empty
|
|
||||||
* `:` (`colon`): last entered command
|
|
||||||
|
|
||||||
Default registers
|
|
||||||
^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Most commands using a register default to a specific one if not specified:
|
|
||||||
|
|
||||||
* `"` (`dquote`): default yank register, used by yanking and pasting commands like `y`, `p` and `R`
|
|
||||||
* `/` (`slash`): default search register, used by regex based commands like `s`, `*` or `/`
|
|
||||||
* `@` (`arobase`): default macro register, used by `q` and `Q`
|
|
||||||
* `^` (`caret`): default mark register, used by `z` and `Z`
|
|
||||||
* `|` (`pipe`): default shell command register, used by command that spawn a subshell such as `|`, `<a-|>`, `!` or `<a-!>`
|
|
||||||
|
|
||||||
Macros
|
Macros
|
||||||
~~~~~~
|
~~~~~~
|
||||||
|
|
@ -1168,51 +814,12 @@ Kakoune trying to be smart.
|
||||||
Regex syntax
|
Regex syntax
|
||||||
~~~~~~~~~~~~
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
The regex syntax based on the ECMAScript regex syntax, documentation can be
|
See <<doc/pages/regex#,`:doc regex`>>.
|
||||||
accessed through `:doc regex`
|
|
||||||
|
|
||||||
Exec and Eval
|
Exec and Eval
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
The `:exec` and `:eval` commands can be used for running Kakoune commands.
|
See <<doc/pages/execeval#,`:doc execeval`>>.
|
||||||
`:exec` runs keys as if they were pressed, whereas `:eval` executes its given
|
|
||||||
parameters as if they were entered in the command prompt. By default,
|
|
||||||
they do their execution in the context of the current client.
|
|
||||||
|
|
||||||
These two commands also save the following registers, who are then restored
|
|
||||||
when the commands have been executed: `/`, `"`, `|`, `^`, `@`.
|
|
||||||
|
|
||||||
Some parameters provide a way to change the context of execution:
|
|
||||||
|
|
||||||
* `-client <name>`: execute in the context of the client named <name>
|
|
||||||
* `-try-client <name>`: execute in the context of the client named
|
|
||||||
<name> if such client exists, or else in the current context.
|
|
||||||
* `-draft`: execute in a copy of the context of the selected client
|
|
||||||
modifications to the selections or input state will not affect
|
|
||||||
the client. This permits to make some modification to the buffer
|
|
||||||
without modifying the user's selection.
|
|
||||||
* `-itersel`: execute once per selection, in a context with only
|
|
||||||
the considered selection. This permits avoiding cases where
|
|
||||||
the selections may get merged.
|
|
||||||
* `-buffer <names>`: execute in the context of each buffers in the
|
|
||||||
comma separated list <names>, '*' as a name can be used to iterate
|
|
||||||
on all buffers.
|
|
||||||
* `-no-hooks`: disable hook execution while executing the keys/commands
|
|
||||||
* `-with-maps`: use user key mapping in `:exec` instead of built in keys.
|
|
||||||
* `-save-regs <regs>`: regs is a string of registers to be restored after
|
|
||||||
execution (overwrites the list of registers saved by default)
|
|
||||||
* `-collapse-jumps`:
|
|
||||||
collapse all jumps into a single one from initial selection
|
|
||||||
|
|
||||||
The execution stops when the last key/command is reached, or an error
|
|
||||||
is raised.
|
|
||||||
|
|
||||||
Key parameters get concatenated, so the following commands are equivalent:
|
|
||||||
|
|
||||||
----------------------
|
|
||||||
:exec otest<space>1
|
|
||||||
:exec o test <space> 1
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
Insert mode completion
|
Insert mode completion
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
@ -1251,133 +858,17 @@ and entering back insert mode (with which binding ?)
|
||||||
Highlighters
|
Highlighters
|
||||||
~~~~~~~~~~~~
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
See `:doc highlighters`
|
See <<doc/pages/highlighters#,`:doc highlighters`>>.
|
||||||
|
|
||||||
Hooks
|
Hooks
|
||||||
~~~~~
|
~~~~~
|
||||||
|
|
||||||
Commands can be registered to be executed when certain events arise.
|
See <<doc/pages/hooks#,`:doc hooks`>>.
|
||||||
To register a hook use the hook command.
|
|
||||||
|
|
||||||
-----------------------------------------------------------------------
|
|
||||||
:hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
|
|
||||||
-----------------------------------------------------------------------
|
|
||||||
|
|
||||||
`<scope>` can be either global, buffer or window (or any of their prefixes).
|
|
||||||
Scopes are hierarchical, meaning that a Window calling a hook will
|
|
||||||
execute its own, the buffer ones and the global ones.
|
|
||||||
|
|
||||||
`<command>` is a string containing the commands to execute when the hook is
|
|
||||||
called.
|
|
||||||
|
|
||||||
For example to automatically use line numbering with .cc files,
|
|
||||||
use the following command:
|
|
||||||
|
|
||||||
---------------------------------------------------------------
|
|
||||||
:hook global WinCreate .*\.cc %{ add-highlighter number_lines }
|
|
||||||
---------------------------------------------------------------
|
|
||||||
|
|
||||||
If `<group>` is given, make this hook part of the named group. groups
|
|
||||||
are used for removing hooks with the `remove-hooks` command:
|
|
||||||
|
|
||||||
----------------------------
|
|
||||||
remove-hooks <scope> <group>
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
The above remove every hooks in `<scope>` that are part of the given group.
|
|
||||||
|
|
||||||
Existing hooks are:
|
|
||||||
|
|
||||||
* `NormalIdle`: A certain duration has passed since last key was pressed in
|
|
||||||
normal mode.
|
|
||||||
* `NormalBegin`: Entering normal mode
|
|
||||||
* `NormalEnd`: Leaving normal mode
|
|
||||||
* `NormalKey`: A key is received in normal mode, the key is used for filtering
|
|
||||||
* `InsertIdle`: A certain duration has passed since last key was pressed in
|
|
||||||
insert mode.
|
|
||||||
* `InsertBegin`: Entering insert mode
|
|
||||||
* `InsertEnd`: Leaving insert mode
|
|
||||||
* `InsertKey`: A key is received in insert mode, the key is used for filtering
|
|
||||||
* `InsertChar`: A character is inserted in insert mode, the character is used
|
|
||||||
for filtering
|
|
||||||
* `InsertDelete`: A character is deleted in insert mode, the character deleted
|
|
||||||
by the main selection is used for filtering
|
|
||||||
* `InsertMove`: The cursor moved (without inserting) in insert mode, the key
|
|
||||||
that triggered the move is used for filtering
|
|
||||||
* `PromptIdle`: A certain duration has passed since last key was pressed in
|
|
||||||
prompt mode.
|
|
||||||
* `WinCreate`: A window was created, the filtering text is the buffer name
|
|
||||||
* `WinClose`: A window was destroyed, the filtering text is the buffer name
|
|
||||||
* `WinDisplay`: A window was bound a client, the filtering text is the buffer
|
|
||||||
name
|
|
||||||
* `WinResize`: A window resized, the filtering text is '<line>.<column>'
|
|
||||||
* `WinSetOption`: An option was set in a window context, the filtering text
|
|
||||||
is '<option_name>=<new_value>'
|
|
||||||
* `BufSetOption`: An option was set in a buffer context, the filtering text
|
|
||||||
is '<option_name>=<new_value>'
|
|
||||||
* `BufNewFile`: A buffer for a new file has been created, filename is used
|
|
||||||
for filtering
|
|
||||||
* `BufOpenFile`: A buffer for an existing file has been created, filename is
|
|
||||||
used for filtering
|
|
||||||
* `BufCreate`: A buffer has been created, filename is used for filtering
|
|
||||||
* `BufWritePre`: Executed just before a buffer is written, filename is
|
|
||||||
used for filtering.
|
|
||||||
* `BufWritePost`: Executed just after a buffer is written, filename is
|
|
||||||
used for filtering.
|
|
||||||
* `BufClose`: Executed when a buffer is deleted, while it is still valid.
|
|
||||||
* `BufOpenFifo`: Executed when a buffer opens a fifo.
|
|
||||||
* `BufReadFifo`: Executed after some data has been read from a fifo and
|
|
||||||
inserted in the buffer.
|
|
||||||
* `BufCloseFifo`: Executed when a fifo buffer closes its fifo file descriptor
|
|
||||||
either because the buffer is being deleted, or because the writing
|
|
||||||
end has been closed.
|
|
||||||
* `RuntimeError`: an error was encountered while executing a user command
|
|
||||||
the error message is used for filtering
|
|
||||||
* `KakBegin`: Kakoune started, this is called just after reading the user
|
|
||||||
configuration files
|
|
||||||
* `KakEnd`: Kakoune is quitting.
|
|
||||||
* `FocusIn`: On supported clients, triggered when the client gets focused.
|
|
||||||
The filtering text is the client name.
|
|
||||||
* `FocusOut`: On supported clients, triggered when the client gets unfocused.
|
|
||||||
The filtering text is the client name.
|
|
||||||
* `InsertCompletionShow`: Triggered when the insert completion menu gets
|
|
||||||
displayed.
|
|
||||||
* `InsertCompletionHide`: Triggered when the insert completion menu gets
|
|
||||||
hidden.
|
|
||||||
* `RawKey`: Triggered whenever a key is pressed by the user, the key is
|
|
||||||
used for filtering.
|
|
||||||
|
|
||||||
When not specified, the filtering text is an empty string.
|
|
||||||
|
|
||||||
Key Mapping
|
Key Mapping
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
You can redefine a key's meaning using the map command:
|
See <<doc/pages/mapping#,`:doc mapping`>>.
|
||||||
|
|
||||||
--------------------------------
|
|
||||||
:map <scope> <mode> <key> <keys>
|
|
||||||
--------------------------------
|
|
||||||
|
|
||||||
`scope` can be one of `global`, `buffer` or `window` (or any prefix);
|
|
||||||
mode one of `normal`, `insert`, `menu`, `prompt`, `goto`, `view`,
|
|
||||||
`user` or `object` (or any prefix); `key` a single key name and `keys`
|
|
||||||
a list of keys.
|
|
||||||
|
|
||||||
`user` mode allows for user mapping behind the `,` key. Keys will be
|
|
||||||
executed in normal mode.
|
|
||||||
|
|
||||||
An optional *-docstring* switch followed by a string can be used to
|
|
||||||
describe what the mapping does. This docstring will be used in autoinfo
|
|
||||||
boxes.
|
|
||||||
|
|
||||||
Mappings can be removed with the unmap command
|
|
||||||
|
|
||||||
----------------------------------------
|
|
||||||
:unmap <scope> <mode> <key> [<expected>]
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
If `<expected>` is specified, unmapping will only proceed if the current
|
|
||||||
mapping matches the expected keys.
|
|
||||||
|
|
||||||
Defining Commands
|
Defining Commands
|
||||||
~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
|
||||||
|
|
@ -31,20 +31,28 @@ e.g. %{ roger {}; } is a valid string, %{ marcel \} as well
|
||||||
|
|
||||||
Typed expansions
|
Typed expansions
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
|
%\{strings\} can have an expansion type between the *%* and the opening
|
||||||
|
character. They will be written *%<type>\{<content>\}*. They will be
|
||||||
|
expanded according to the given *<type>* using *<content>* as its
|
||||||
|
parameter:
|
||||||
|
|
||||||
*sh*::
|
*sh*::
|
||||||
shell expansion, similar to posix shell '$(...)' construct (c.f. next
|
shell expansion, similar to posix shell '$(...)' construct (c.f. next
|
||||||
section)
|
section)
|
||||||
*reg*::
|
*reg*::
|
||||||
register expansion, will be replaced by the content of the given
|
register expansion, will expand to the content of the register named
|
||||||
register
|
by *<content>*.
|
||||||
*opt*::
|
*opt*::
|
||||||
option expansion, will be replaced with the value of the given option
|
option expansion, will expand to the value of the option named by
|
||||||
|
*<content>*
|
||||||
*val*::
|
*val*::
|
||||||
value expansion, gives access to the environment variable available
|
value expansion, will expand to the value of the environment variables
|
||||||
to the Shell expansion. The 'kak_' prefix is not used there
|
available to shell expansion. *<content>* shall be the name of that
|
||||||
|
variable without the *kak_* prefix.
|
||||||
*arg*::
|
*arg*::
|
||||||
argument expansion, gives access to the arguments of the current
|
argument expansion, expand to the arguments of the current
|
||||||
command, the content can be a number, or @ for all arguments
|
command, *<content>* can be a number, or @ for all arguments
|
||||||
|
|
||||||
Shell expansions
|
Shell expansions
|
||||||
----------------
|
----------------
|
||||||
|
|
|
||||||
|
|
@ -15,8 +15,8 @@ register a hook use the following command:
|
||||||
hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
|
hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
|
||||||
----------------------------------------------------------------------
|
----------------------------------------------------------------------
|
||||||
|
|
||||||
*scope* can be one of *global*, *buffer* or *window* (c.f. the
|
*scope* can be one of *global*, *buffer* or *window* (See
|
||||||
'scopes' documentation page).
|
<<scopes#,`:doc scopes`>>).
|
||||||
|
|
||||||
*command* is a string containing the commands to execute when the hook
|
*command* is a string containing the commands to execute when the hook
|
||||||
is called.
|
is called.
|
||||||
|
|
|
||||||
|
|
@ -5,20 +5,50 @@ NAME
|
||||||
----
|
----
|
||||||
options - a
|
options - a
|
||||||
|
|
||||||
|
Options
|
||||||
|
-------
|
||||||
|
|
||||||
|
Kakoune can store named and typed values that can be used both to customize
|
||||||
|
the core editor behaviour, and to store data used by extension scripts.
|
||||||
|
|
||||||
|
Options can be modified using the *set-option* command:
|
||||||
|
|
||||||
|
---------------------------------
|
||||||
|
set-option <scope> <name> <value>
|
||||||
|
---------------------------------
|
||||||
|
|
||||||
|
<scope> can be *global*, *buffer* or *window* (See <<scopes#,`:doc scopes`>>)
|
||||||
|
|
||||||
|
New options can be declared using the *declare-option* command:
|
||||||
|
|
||||||
|
------------------------------------------------
|
||||||
|
declare-option [-hidden] <type> <name> [<value>]
|
||||||
|
------------------------------------------------
|
||||||
|
|
||||||
|
If `-hidden` is specified, the option will not be displayed in completion
|
||||||
|
suggestions.
|
||||||
|
|
||||||
Types
|
Types
|
||||||
-----
|
-----
|
||||||
|
|
||||||
|
All options have a type, which defines how they are translated to/from text
|
||||||
|
and their set of valid values.
|
||||||
|
|
||||||
|
Some types are usable for user defined options while some other types
|
||||||
|
are exclusively available to built-in options.
|
||||||
|
|
||||||
*int*::
|
*int*::
|
||||||
an integer number
|
an integer number
|
||||||
*bool*::
|
*bool*::
|
||||||
a boolean value, yes/true or no/false
|
a boolean value, yes/true or no/false
|
||||||
*str*::
|
*str*::
|
||||||
a string, some freeform text
|
a string, some freeform text
|
||||||
*coord*::
|
|
||||||
a line, column pair (separated by comma)
|
|
||||||
*regex*::
|
*regex*::
|
||||||
as a string but the set commands will complain if the entered text
|
as a string but the set commands will complain if the entered text
|
||||||
is not a valid regex
|
is not a valid regex
|
||||||
*int-list*, *str-list*, *codepoint-list*::
|
*coord*::
|
||||||
|
a line, column pair (separated by comma)
|
||||||
|
*<type>-list*::
|
||||||
a list, elements are separated by a colon (:) if an element needs
|
a list, elements are separated by a colon (:) if an element needs
|
||||||
to contain a colon, it can be escaped with a backslash
|
to contain a colon, it can be escaped with a backslash
|
||||||
*range-specs*::
|
*range-specs*::
|
||||||
|
|
@ -46,9 +76,6 @@ Types
|
||||||
a set of flags, taking a combination of the given values joined by a
|
a set of flags, taking a combination of the given values joined by a
|
||||||
'|' character
|
'|' character
|
||||||
|
|
||||||
Refer to the 'scopes' documentation page for more information about
|
|
||||||
scopes.
|
|
||||||
|
|
||||||
Builtin options
|
Builtin options
|
||||||
---------------
|
---------------
|
||||||
|
|
||||||
|
|
@ -116,7 +143,7 @@ Builtin options
|
||||||
*default* ./:/usr/include +
|
*default* ./:/usr/include +
|
||||||
directories to search for gf command
|
directories to search for gf command
|
||||||
|
|
||||||
*completers* 'str-list'::
|
*completers* 'completer-list'::
|
||||||
*default* filename:word=all +
|
*default* filename:word=all +
|
||||||
completion engines to use for insert mode completion (they are tried
|
completion engines to use for insert mode completion (they are tried
|
||||||
in order until one generates candidates). Existing completers are:
|
in order until one generates candidates). Existing completers are:
|
||||||
|
|
@ -178,7 +205,7 @@ Builtin options
|
||||||
|
|
||||||
The default value is '%val{bufname} %val{cursor_line}:%val{cursor_char_column} {{context_info}} {{mode_info}} - %val{client}@[%val{session}]'
|
The default value is '%val{bufname} %val{cursor_line}:%val{cursor_char_column} {{context_info}} {{mode_info}} - %val{client}@[%val{session}]'
|
||||||
|
|
||||||
*ui_options*::
|
*ui_options* 'str-to-str-map'::
|
||||||
colon separated list of key=value pairs that are forwarded to the user
|
colon separated list of key=value pairs that are forwarded to the user
|
||||||
interface implementation. The NCurses UI support the following options:
|
interface implementation. The NCurses UI support the following options:
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user