1f02a1f7e2
Except for the FAQ, it could be fixed, but it does not have to be as formal as the rest of the docs.
137 lines
4.8 KiB
Plaintext
137 lines
4.8 KiB
Plaintext
= Expansions
|
||
|
||
== Strings
|
||
|
||
\'strings'::
|
||
uninterpreted strings, use a backslash (\') to escape the separator
|
||
"strings"::
|
||
expanded strings, % strings (c.f. next section) contained are expended,
|
||
use a backslash (\\%) to escape the separator
|
||
%\{strings\}::
|
||
these strings are very useful when entering commands
|
||
+
|
||
* the '{' and '}' delimiters are configurable, any non alphanumeric
|
||
character can be used
|
||
+
|
||
----------------------------------------------------------
|
||
e.g. %[string], %<string>, %(string), %~string~, %!string!
|
||
----------------------------------------------------------
|
||
* if the character following '%' is one of '{[(<', then the closing
|
||
one is the matching '}])>' and the delimiters are not escapable but
|
||
are nestable
|
||
+
|
||
-----------------------------------------------------------
|
||
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 expand to the content of the register named
|
||
by *<content>*.
|
||
*opt*::
|
||
option expansion, will expand to the value of the option named by
|
||
*<content>*
|
||
*val*::
|
||
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, expand to the arguments of the current
|
||
command, *<content>* can be a number, or @ for all arguments
|
||
|
||
== Shell expansions
|
||
|
||
The '%sh{...}' expansion replaces its content with the output of the
|
||
shell commands in it. The following environment variables are used to pass
|
||
informations about Kakoune's state:
|
||
|
||
*kak_selection*::
|
||
content of the main selection
|
||
*kak_selections*::
|
||
content of the selection separated by colons, colons 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*::
|
||
process id of the current client
|
||
*kak_client_list*::
|
||
list of clients connected to the current session
|
||
*kak_source*::
|
||
path of the file currently getting executed (through the source
|
||
command)
|
||
*kak_modified*::
|
||
buffer has modifications not saved
|
||
*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 bytes).
|
||
*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
|
||
(e.g. *$kak_client_env_SHELL* is the SHELL variable)
|
||
|
||
Note that in order for Kakoune to pass a value in the environment, the
|
||
variable has to be spelled out within the body of the expansion
|
||
|
||
== Markup strings
|
||
|
||
In certain contexts, Kakoune can take a markup string, which is a string
|
||
containing formatting informations. In these strings, the {facename}
|
||
syntax will enable the face facename until another face gets activated,
|
||
or the end of the string is reached.
|
||
|
||
Literal '{' characters shall be written '\{', and a literal backslash ('\')
|
||
that precedes a '{' character shall be escaped as well ('\\').
|