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}"]
|
||||
ifdef::env-github,env-browser[:outfilesuffix: .asciidoc]
|
||||
:logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg
|
||||
:website: http://kakoune.org
|
||||
: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
|
||||
semicolon argument.
|
||||
|
||||
String syntax
|
||||
~~~~~~~~~~~~~
|
||||
String syntax and expansions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When entering a command, parameters are separated by whitespace (shell like),
|
||||
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 `\\`
|
||||
See <<doc/pages/expansions#,`:doc expansions`>>.
|
||||
|
||||
Configuration & Autoloading
|
||||
---------------------------
|
||||
|
|
@ -889,260 +774,21 @@ precedence.
|
|||
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
|
||||
---------------
|
||||
|
||||
Faces
|
||||
-----
|
||||
|
||||
See <<doc/pages/faces#,`:doc faces`>>.
|
||||
|
||||
Registers
|
||||
~~~~~~~~~
|
||||
|
||||
Registers are named lists of text. They are used for various purposes, like
|
||||
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-!>`
|
||||
See <<doc/pages/registers#,`:doc registers`>>.
|
||||
|
||||
Macros
|
||||
~~~~~~
|
||||
|
|
@ -1168,51 +814,12 @@ Kakoune trying to be smart.
|
|||
Regex syntax
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The regex syntax based on the ECMAScript regex syntax, documentation can be
|
||||
accessed through `:doc regex`
|
||||
See <<doc/pages/regex#,`:doc regex`>>.
|
||||
|
||||
Exec and Eval
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The `:exec` and `:eval` commands can be used for running Kakoune commands.
|
||||
`: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
|
||||
----------------------
|
||||
See <<doc/pages/execeval#,`:doc execeval`>>.
|
||||
|
||||
Insert mode completion
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -1251,133 +858,17 @@ and entering back insert mode (with which binding ?)
|
|||
Highlighters
|
||||
~~~~~~~~~~~~
|
||||
|
||||
See `:doc highlighters`
|
||||
See <<doc/pages/highlighters#,`:doc highlighters`>>.
|
||||
|
||||
Hooks
|
||||
~~~~~
|
||||
|
||||
Commands can be registered to be executed when certain events arise.
|
||||
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.
|
||||
See <<doc/pages/hooks#,`:doc hooks`>>.
|
||||
|
||||
Key Mapping
|
||||
~~~~~~~~~~~
|
||||
|
||||
You can redefine a key's meaning using the map command:
|
||||
|
||||
--------------------------------
|
||||
: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.
|
||||
See <<doc/pages/mapping#,`:doc mapping`>>.
|
||||
|
||||
Defining Commands
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
|
|
|||
|
|
@ -31,20 +31,28 @@ e.g. %{ roger {}; } is a valid string, %{ marcel \} as well
|
|||
|
||||
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*::
|
||||
shell expansion, similar to posix shell '$(...)' construct (c.f. next
|
||||
section)
|
||||
*reg*::
|
||||
register expansion, will be replaced by the content of the given
|
||||
register
|
||||
register expansion, will expand to the content of the register named
|
||||
by *<content>*.
|
||||
*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*::
|
||||
value expansion, gives access to the environment variable available
|
||||
to the Shell expansion. The 'kak_' prefix is not used there
|
||||
value expansion, will expand to the value of the environment variables
|
||||
available to shell expansion. *<content>* shall be the name of that
|
||||
variable without the *kak_* prefix.
|
||||
*arg*::
|
||||
argument expansion, gives access to the arguments of the current
|
||||
command, the content can be a number, or @ for all arguments
|
||||
argument expansion, expand to the arguments of the current
|
||||
command, *<content>* can be a number, or @ for all arguments
|
||||
|
||||
Shell expansions
|
||||
----------------
|
||||
|
|
|
|||
|
|
@ -15,8 +15,8 @@ register a hook use the following command:
|
|||
hook [-group <group>] <scope> <hook_name> <filtering_regex> <commands>
|
||||
----------------------------------------------------------------------
|
||||
|
||||
*scope* can be one of *global*, *buffer* or *window* (c.f. the
|
||||
'scopes' documentation page).
|
||||
*scope* can be one of *global*, *buffer* or *window* (See
|
||||
<<scopes#,`:doc scopes`>>).
|
||||
|
||||
*command* is a string containing the commands to execute when the hook
|
||||
is called.
|
||||
|
|
|
|||
|
|
@ -5,20 +5,50 @@ NAME
|
|||
----
|
||||
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
|
||||
-----
|
||||
|
||||
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*::
|
||||
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-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
|
||||
to contain a colon, it can be escaped with a backslash
|
||||
*range-specs*::
|
||||
|
|
@ -46,9 +76,6 @@ Types
|
|||
a set of flags, taking a combination of the given values joined by a
|
||||
'|' character
|
||||
|
||||
Refer to the 'scopes' documentation page for more information about
|
||||
scopes.
|
||||
|
||||
Builtin options
|
||||
---------------
|
||||
|
||||
|
|
@ -116,7 +143,7 @@ Builtin options
|
|||
*default* ./:/usr/include +
|
||||
directories to search for gf command
|
||||
|
||||
*completers* 'str-list'::
|
||||
*completers* 'completer-list'::
|
||||
*default* filename:word=all +
|
||||
completion engines to use for insert mode completion (they are tried
|
||||
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}]'
|
||||
|
||||
*ui_options*::
|
||||
*ui_options* 'str-to-str-map'::
|
||||
colon separated list of key=value pairs that are forwarded to the user
|
||||
interface implementation. The NCurses UI support the following options:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user