kakoune/doc/manpages/expansions.asciidoc
2017-05-18 17:39:30 +02:00

124 lines
4.1 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.

KAKOUNE(1)
==========
NAME
----
expansions - a
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, you can use any non
alphanumeric character
+
----------------------------------------------------------
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
----------------
*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
*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
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 theres no
associated file
*kak_buflist*::
the current buffer list, each buffer separated by a colon
*kak_timestamp*::
timestamp of the current buffer, the timestamp is an integer value
which is incremented each time the buffer is modified
*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 current client
*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_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 ('\\').