mawww/kakoune
1
1
Fork 0
mirror of https://github.com/mawww/kakoune.git synced 2024-12-24 03:56:32 +03:00
Code Issues Projects Releases Wiki Activity

Remove duplicated documentation from the README

Browse Source 
Just point towards the relevant doc page.
This commit is contained in:
Maxime Coste 2017-11-01 19:49:13 +08:00
parent ed65d86c72
commit 6bc408e9b9
4 changed files with 68 additions and 542 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

541
README.asciidoc
View File

@ -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
~~~~~~~~~~~~~~~~~

22
doc/pages/expansions.asciidoc
View File

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

4
doc/pages/hooks.asciidoc
View File

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

43
doc/pages/options.asciidoc
View File

@ -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: