kakoune/doc/pages/expansions.asciidoc

195 lines
5.7 KiB
Plaintext
Raw Normal View History

= Expansions
== Strings
\'strings'::
2017-11-02 10:37:39 +01:00
uninterpreted strings, use a backslash (\') to escape the separator
"strings"::
2017-11-02 10:37:39 +01:00
expanded strings, % strings (c.f. next section) contained are expended,
use a backslash (\\%) to escape the separator
%\{strings\}::
2017-11-02 10:37:39 +01:00
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!
----------------------------------------------------------
2017-11-02 10:37:39 +01:00
* 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*::
2017-11-02 10:37:39 +01:00
shell expansion, similar to posix shell '$(...)' construct (c.f. next
section)
*reg*::
register expansion, will expand to the strings stored in the register
named by *<content>*. See <<registers#,`:doc registers`>>
*opt*::
2017-11-02 10:37:39 +01:00
option expansion, will expand to the value of the option named by
*<content>*. See <<options#,`:doc options`>>
*val*::
2017-11-02 10:37:39 +01:00
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*::
2017-11-02 10:37:39 +01:00
argument expansion, expand to the arguments of the current
command, *<content>* can be a number, or @ for all arguments
== Shell expansions
2016-02-10 22:03:49 +01:00
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*::
2017-11-02 10:37:39 +01:00
content of the main selection
*kak_selections*::
quoted list of the contents of the selections.
*kak_selection_desc*::
2017-11-02 10:37:39 +01:00
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*::
2017-11-02 10:37:39 +01:00
name of the current buffer
*kak_buffile*::
2017-11-02 10:37:39 +01:00
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
2017-06-06 14:29:06 +02:00
*kak_buf_line_count*::
2017-11-02 10:37:39 +01:00
the current buffer line count
*kak_timestamp*::
2017-11-02 10:37:39 +01:00
timestamp of the current buffer, the timestamp is an integer value
which is incremented each time the buffer is modified
*kak_history_id*::
2017-11-02 10:37:39 +01:00
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*::
2017-11-02 10:37:39 +01:00
count parameter passed to the command
2018-02-22 21:47:34 +01:00
*kak_register*::
register parameter passed to the command
*kak_opt_<name>*::
2017-11-02 10:37:39 +01:00
value of option *name*
*kak_reg_<r>*::
quoted list of value of register *r*
*kak_main_reg_<r>*::
content of register *r* associated with the main selection.
*kak_session*::
2017-11-02 10:37:39 +01:00
name of the current session
*kak_client*::
2017-11-02 10:37:39 +01:00
name of the current client
*kak_client_pid*::
2017-11-02 10:37:39 +01:00
process id of the current client
2017-10-05 16:41:36 +02:00
*kak_client_list*::
unquoted list of the names of clients connected to the current session
*kak_source*::
2017-11-02 10:37:39 +01:00
path of the file currently getting executed (through the source
command)
*kak_modified*::
2017-11-02 10:37:39 +01:00
buffer has modifications not saved
*kak_cursor_line*::
2017-11-02 10:37:39 +01:00
line of the end of the main selection
*kak_cursor_column*::
2017-11-02 10:37:39 +01:00
column of the end of the main selection (in byte)
*kak_cursor_char_value*::
2017-11-02 10:37:39 +01:00
unicode value of the codepoint under the cursor
*kak_cursor_char_column*::
2017-11-02 10:37:39 +01:00
column of the end of the main selection (in character)
2017-06-06 14:29:06 +02:00
*kak_cursor_byte_offset*::
2017-11-02 10:37:39 +01:00
Offset of the main selection from the beginning of the buffer (in bytes).
*kak_window_width*::
2017-11-02 10:37:39 +01:00
width of the current kakoune window
*kak_window_height*::
2017-11-02 10:37:39 +01:00
height of the current kakoune window
*kak_hook_param*::
2017-11-02 10:37:39 +01:00
filtering text passed to the currently executing hook
*kak_hook_param_capture_N*::
2017-11-02 10:37:39 +01:00
text captured by the hook filter regex capture N
*kak_client_env_<name>*::
2017-11-02 10:37:39 +01:00
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.
2016-02-10 22:03:49 +01:00
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
2016-02-10 22:03:49 +01:00
In certain contexts, Kakoune can take a markup string, which is a string
2017-05-11 20:42:09 +02:00
containing formatting informations. In these strings, the {facename}
2016-02-10 22:03:49 +01:00
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 ('\')
2016-04-08 18:00:24 +02:00
that precedes a '{' character shall be escaped as well ('\\').