kakoune/doc/pages/expansions.asciidoc

192 lines
5.6 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

= 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>*. See <<registers#,`:doc registers`>>
*opt*::
option expansion, will expand to the value of the option named by
*<content>*. See <<options#,`:doc options`>>
*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*::
quoted list of the contents of the selections.
*kak_selection_desc*::
range of the main selection, represented as anchor,cursor; anchor
and cursor are in this format: line.column
*kak_selections_desc*::
unquoted list range of the selections.
*kak_bufname*::
name of the current buffer
*kak_buffile*::
full path of the file or same as kak_bufname when theres no
associated file
*kak_buflist*::
quoted list of the currently opened buffer names
*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 support files, determined from kakoune's
binary location.
*kak_config*::
directory containing the user configuration
*kak_version*::
version of the current Kakoune server (git hash or release name)
*kak_count*::
count parameter passed to the command
*kak_register*::
register 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*::
unquoted list of the names 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)
*kak_user_modes*::
unquoted list of user modes.
Quoted lists are separated by spaces, and each element is surrounded by
`'` with contained `'` doubled. Unquoted lists are simply separated by
spaces and is used for values that will not contain whitespaces.
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.
Those environment variables are available in every context where
Kakoune use a shell command, such as the `|`, `!` or `$` normal
mode commands (See <<keys#,`:doc keys`>>).
== 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 ('\\').