expansions.asciidoc: Rewrite to make Kakoune syntax the primary reference.
Also, moved the "Markup strings" section to faces.asciidoc, since it wasn't anything to do with expansions, and updated various hyperlinks to point at the new location.
This commit is contained in:
Tim Allen
parent
cb8b882878
commit
e493eba46d
|
|
@ -91,7 +91,8 @@ line.column[+len]@timestamp candidate1|desc1|menu1 candidate2|desc2|menu2 ...
|
||||||
the first element of this string list specify where and when this completion
|
the first element of this string list specify where and when this completion
|
||||||
applies, the others are a triplet `<completion text>|<docstring>|<menu text>`
|
applies, the others are a triplet `<completion text>|<docstring>|<menu text>`
|
||||||
|
|
||||||
The menu text is a markup string, so it can contain `{face}` directives.
|
The menu text is a markup string (see <<faces#markup-strings,`:doc faces
|
||||||
|
markup-strings`>>), so it can contain `{face}` directives.
|
||||||
|
|
||||||
To effectively use that completion option, it should get added to the completers
|
To effectively use that completion option, it should get added to the completers
|
||||||
option.
|
option.
|
||||||
|
|
|
||||||
|
|
@ -166,7 +166,7 @@ of the file onto the filesystem
|
||||||
|
|
||||||
*-markup*:::
|
*-markup*:::
|
||||||
expand the markup strings in *text* (See
|
expand the markup strings in *text* (See
|
||||||
<<expansions#markup-strings,`:doc expansions markup-strings`>>)
|
<<faces#markup-strings,`:doc faces markup-strings`>>)
|
||||||
|
|
||||||
*-debug*:::
|
*-debug*:::
|
||||||
print the given text to the *\*debug** buffer
|
print the given text to the *\*debug** buffer
|
||||||
|
|
|
||||||
|
|
@ -1,199 +1,294 @@
|
||||||
= Expansions
|
= Expansions
|
||||||
|
|
||||||
== Strings
|
While parsing a command (see <<command-parsing#,`:doc command-parsing`>>),
|
||||||
|
Kakoune recognises certain patterns and will replace them with their
|
||||||
|
associated value before executing the command. These patterns are called
|
||||||
|
expansions.
|
||||||
|
|
||||||
\'strings'::
|
Every expansion consists of a `%`, followed by the expansion _type_ (one
|
||||||
uninterpreted strings, use a backslash (\') to escape the separator
|
or more alphabetic characters), a nestable punctuation character (`(`, `[`,
|
||||||
|
`{`, or `<`), and then all the text up to and including its matching opposite
|
||||||
|
(`)`, `]`, `}`, or `>`). It doesn't matter which character is used, but
|
||||||
|
`{}` are most common. For example, the command `echo %val{session}` will
|
||||||
|
echo the ID of the current Kakoune session.
|
||||||
|
|
||||||
"strings"::
|
Expansions are processed when unquoted and anywhere inside double-quoted or
|
||||||
expanded strings, % strings (c.f. next section) contained are expended,
|
%-strings, but not inside unquoted words, inside single-quoted strings, or
|
||||||
use a backslash (\\%) to escape the separator
|
inside other expansions. So:
|
||||||
|
|
||||||
%\{strings\}::
|
* `echo %val{session}` echoes the current session ID
|
||||||
these strings are very useful when entering commands
|
|
||||||
|
|
||||||
* the '{' and '}' delimiters are configurable, any non alphanumeric
|
* `echo x%val{session}x` echoes the literal text `x%val{session}x`
|
||||||
character can be used
|
|
||||||
|
|
||||||
----------------------------------------------------------
|
* `echo '%val{session}'` echoes the literal text `%val{session}`
|
||||||
e.g. %[string], %<string>, %(string), %~string~, %!string!
|
|
||||||
----------------------------------------------------------
|
|
||||||
|
|
||||||
* if the character following '%' is one of '{[(<', then the closing
|
* `echo "x%val{session}x"` echoes the current session ID, surrounded by `x`
|
||||||
one is the matching '}])>' and the delimiters are not escapable but
|
|
||||||
are nestable
|
|
||||||
|
|
||||||
-----------------------------------------------------------
|
* `echo %{x%val{session}x}"` echoes the current session ID, surrounded by `x`
|
||||||
e.g. %{ roger {}; } is a valid string, %{ marcel \} as well
|
|
||||||
-----------------------------------------------------------
|
|
||||||
|
|
||||||
== Typed expansions
|
* `echo %sh{ echo %val{session} }"` echoes the literal text `%val{session}`
|
||||||
|
|
||||||
%\{strings\} can have an expansion type between the *%* and the opening
|
When processing an expansion, Kakoune ensures the result is properly quoted so
|
||||||
character. They will be written *%<type>\{<content>\}*. They will be
|
that any special characters do not interfere with the rest of the command. If
|
||||||
expanded according to the given *<type>* using *<content>* as its
|
an expansion expands to multiple values, each value is individually quoted.
|
||||||
parameter:
|
|
||||||
|
|
||||||
*sh*::
|
== Argument expansions
|
||||||
shell expansion, similar to posix shell '$(...)' construct (c.f. next
|
|
||||||
section)
|
|
||||||
|
|
||||||
*reg*::
|
Expansions with the type `arg` can only be used inside the "commands" parameter
|
||||||
register expansion, will expand to the strings stored in the register
|
of the `define-command` command (See <<commands#declaring-new-commands,`:doc
|
||||||
named by *<content>*. See <<registers#,`:doc registers`>>
|
commands declaring-new-commands`>>).
|
||||||
|
|
||||||
*opt*::
|
The following expansions are available:
|
||||||
option expansion, will expand to the value of the option named by
|
|
||||||
*<content>*. See <<options#,`:doc options`>>
|
|
||||||
|
|
||||||
*val*::
|
*%arg{n}*::
|
||||||
value expansion, will expand to the value of the environment variables
|
(where _n_ is a decimal number) +
|
||||||
available to shell expansion. *<content>* shall be the name of that
|
expands to argument number _n_ of the current command
|
||||||
variable without the *kak_* prefix.
|
|
||||||
|
|
||||||
*arg*::
|
*%arg{@}*::
|
||||||
argument expansion, expand to the arguments of the current
|
expands to all the arguments of the current command, individually quoted
|
||||||
command, *<content>* can be a number, or @ for all arguments
|
|
||||||
|
== Option expansions
|
||||||
|
|
||||||
|
Expansions with the type `opt` expand to the value associated with the named
|
||||||
|
option in the current scope (See <<options#,`:doc options`>>).
|
||||||
|
|
||||||
|
For example, `%opt{BOM}` expands to `utf8` or to `none`, according to the
|
||||||
|
current state of the `BOM` option.
|
||||||
|
|
||||||
|
== Register expansions
|
||||||
|
|
||||||
|
Expansions with the type `reg` expand to the contents of the named
|
||||||
|
register. For registers named after symbols (like the search register
|
||||||
|
`/`), the expansion can use either the symbol or the alphabetic name (See
|
||||||
|
<<registers#,`:doc registers`>>).
|
||||||
|
|
||||||
|
For example, `%reg{/}` expands to the content of the `/` register, and so does
|
||||||
|
`%reg{slash}`.
|
||||||
|
|
||||||
== Shell expansions
|
== Shell expansions
|
||||||
|
|
||||||
The '%sh{...}' expansion replaces its content with the output of the
|
Expansions with the type `sh` are executed as shell-scripts, and whatever
|
||||||
shell commands in it. The following environment variables are used to pass
|
the script prints to standard output replaces the expansion. For example,
|
||||||
informations about Kakoune's state:
|
the command `echo %sh{date}` will echo the output of the `date` command.
|
||||||
|
|
||||||
*kak_selection*::
|
TIP: If a shell expansion writes to standard error, that output is appended to
|
||||||
content of the main selection
|
Kakoune's `\*debug*` buffer. If you're trying to debug a shell expansion,
|
||||||
|
check the debug buffer with `:buffer \*debug*` to see if anything shows up.
|
||||||
|
|
||||||
*kak_selections*::
|
Because Kakoune does not expand expansions inside the text of an expansion,
|
||||||
quoted list of the contents of the selections.
|
you can't use normal expansions inside `%sh{}`. Instead, Kakoune can export
|
||||||
|
expansions as environment variables to make them available to the shell.
|
||||||
|
Here's how expansion patterns map to variable names:
|
||||||
|
|
||||||
*kak_selection_desc*::
|
*%arg{n}*::
|
||||||
range of the main selection, represented as anchor,cursor; anchor
|
(where _n_ is a decimal number) +
|
||||||
and cursor are in this format: line.column
|
becomes `$_n_`. For example, `%arg{3}` becomes `$3`.
|
||||||
|
|
||||||
*kak_selections_desc*::
|
*%arg{@}*::
|
||||||
unquoted list range of the selections.
|
becomes `$@`
|
||||||
|
|
||||||
*kak_bufname*::
|
*%opt{x}*::
|
||||||
name of the current buffer
|
becomes `$kak_opt_x`
|
||||||
|
|
||||||
*kak_buffile*::
|
*%reg{x}*::
|
||||||
full path of the file or same as kak_bufname when there’s no
|
(where _x_ is the alphabetic name of a register) +
|
||||||
|
`$kak_reg_x` contains all the selections in register _x_ +
|
||||||
|
`$kak_main_reg_x` contains only the main selection
|
||||||
|
|
||||||
|
*%val{x}*::
|
||||||
|
becomes `$kak_x`
|
||||||
|
|
||||||
|
When turned into environment variables, list-type options, `$kak_reg_x`, and
|
||||||
|
"quoted list" values will be shell-quoted so the shell doesn't get confused
|
||||||
|
about how many items the list contains. You will need to apply `eval` to get
|
||||||
|
back the original values. For example, if you want to process the contents
|
||||||
|
of each selection, you can do something like:
|
||||||
|
|
||||||
|
----
|
||||||
|
eval set -- $kak_selections
|
||||||
|
while [ $# -gt 0 ]; do
|
||||||
|
# ...do a thing with $1...
|
||||||
|
shift
|
||||||
|
done
|
||||||
|
----
|
||||||
|
|
||||||
|
The `eval` command will take the expanded `$kak_selections` and unquote them,
|
||||||
|
then execute the resulting `set` command, which sets the shell's argument
|
||||||
|
variables to the items from `$kak_selections`. The `while` loop with `shift`
|
||||||
|
iterates through the arguments one by one.
|
||||||
|
|
||||||
|
Only variables actually mentioned in the body of the shell expansion will
|
||||||
|
be exported into the shell's environment. For example:
|
||||||
|
|
||||||
|
----
|
||||||
|
echo %sh{ env | grep ^kak_ }
|
||||||
|
----
|
||||||
|
|
||||||
|
...will find none of Kakoune's special environment variables, but:
|
||||||
|
|
||||||
|
----
|
||||||
|
echo %sh{ env | grep ^kak_ # $kak_session }
|
||||||
|
----
|
||||||
|
|
||||||
|
...will find the `$kak_session` variable because it was mentioned inside the
|
||||||
|
shell script, even just in a comment.
|
||||||
|
|
||||||
|
TIP: These environment variables are also available in other contexts where
|
||||||
|
Kakoune uses a shell command, such as the `|`, `!` or `$` normal mode commands
|
||||||
|
(See <<keys#,`:doc keys`>>).
|
||||||
|
|
||||||
|
== Value expansions
|
||||||
|
|
||||||
|
Expansions with the type `val` can be used in various places, depending on the
|
||||||
|
specific value.
|
||||||
|
|
||||||
|
The following expansions are supported:
|
||||||
|
|
||||||
|
*%val{buffile}*::
|
||||||
|
_in buffer scope_ +
|
||||||
|
full path of the file or same as `%val{bufname}` when there’s no
|
||||||
associated file
|
associated file
|
||||||
|
|
||||||
*kak_buflist*::
|
*%val{buf_line_count}*::
|
||||||
quoted list of the currently opened buffer names
|
_in buffer scope_ +
|
||||||
|
number of lines in the current buffer
|
||||||
|
|
||||||
*kak_buf_line_count*::
|
*%val{buflist}*::
|
||||||
the current buffer line count
|
quoted list of the names of currently-open buffers (as seen in
|
||||||
|
`%val{bufname}`)
|
||||||
|
|
||||||
*kak_timestamp*::
|
*%val{bufname}*::
|
||||||
timestamp of the current buffer, the timestamp is an integer value
|
_in buffer scope_ +
|
||||||
which is incremented each time the buffer is modified
|
name of the current buffer
|
||||||
|
|
||||||
*kak_history_id*::
|
*%val{client_env_X}*::
|
||||||
history id of the current buffer, the history id is an integer value
|
_in window scope_ +
|
||||||
which is used to reference a specific buffer version in the undo tree
|
value of the `$X` environment variable in the client displaying the current
|
||||||
|
window (e.g. `%val{client_env_SHELL}` is `$SHELL` in the client's
|
||||||
|
environment)
|
||||||
|
|
||||||
*kak_runtime*::
|
*%val{client_list}*::
|
||||||
directory containing the kak support files, determined from kakoune's
|
unquoted list of the names of clients (as seen in `%val{client}`)
|
||||||
binary location.
|
connected to the current session
|
||||||
|
|
||||||
*kak_config*::
|
*%val{client}*::
|
||||||
|
_in window scope_ +
|
||||||
|
name of the client displaying the current window
|
||||||
|
|
||||||
|
*%val{client_pid}*::
|
||||||
|
_in window scope_ +
|
||||||
|
process id of the client displaying the current window
|
||||||
|
|
||||||
|
*%val{config}*::
|
||||||
directory containing the user configuration
|
directory containing the user configuration
|
||||||
|
|
||||||
*kak_version*::
|
*%val{count}*::
|
||||||
version of the current Kakoune server (git hash or release name)
|
_in `map` command <keys> parameter_ +
|
||||||
|
current count when the mapping was triggered, defaults to 0 if no
|
||||||
|
count given
|
||||||
|
|
||||||
*kak_count*::
|
*%val{cursor_byte_offset}*::
|
||||||
count parameter passed to the command, defaults to 0 if no count given
|
_in window scope_ +
|
||||||
|
offset of the main cursor from the beginning of the buffer (in bytes)
|
||||||
|
|
||||||
*kak_register*::
|
*%val{cursor_char_column}*::
|
||||||
register parameter passed to the command
|
_in window scope_ +
|
||||||
|
column of the main cursor (in characters), the fourth component of
|
||||||
|
`%val{selection_desc}`
|
||||||
|
|
||||||
*kak_opt_<name>*::
|
*%val{cursor_char_value}*::
|
||||||
value of option *name*
|
_in window scope_ +
|
||||||
|
unicode value of the codepoint under the main cursor
|
||||||
|
|
||||||
*kak_reg_<r>*::
|
*%val{cursor_column}*::
|
||||||
quoted list of value of register *r*
|
_in window scope_ +
|
||||||
|
column of the main cursor (in bytes)
|
||||||
|
|
||||||
*kak_main_reg_<r>*::
|
*%val{cursor_line}*::
|
||||||
content of register *r* associated with the main selection.
|
_in window scope_ +
|
||||||
|
line of the main cursor, the third component of `%val{selection_desc}`
|
||||||
|
|
||||||
*kak_session*::
|
*%val{history_id}*::
|
||||||
|
_in buffer scope_ +
|
||||||
|
history id of the current buffer, an integer value which refers to a
|
||||||
|
specific buffer version in the undo tree (see also `%val{timestamp}`)
|
||||||
|
|
||||||
|
*%val{hook_param_capture_n}*::
|
||||||
|
_in `hook` command <command> parameter_ +
|
||||||
|
text captured by capture group _n_, if the executing hook's filter regex
|
||||||
|
used capture groups
|
||||||
|
|
||||||
|
*%val{hook_param}*::
|
||||||
|
_in `hook` command <command> parameter_ +
|
||||||
|
the complete parameter string of the executing hook
|
||||||
|
|
||||||
|
*%val{modified}*::
|
||||||
|
_in buffer scope_ +
|
||||||
|
`true` if the buffer has modifications not saved, otherwise `false`
|
||||||
|
|
||||||
|
*%val{register}*::
|
||||||
|
_in `map` command <keys> parameter_ +
|
||||||
|
current register when the mapping was triggered
|
||||||
|
|
||||||
|
*%val{runtime}*::
|
||||||
|
directory containing the kak support files, determined from Kakoune's
|
||||||
|
binary location
|
||||||
|
|
||||||
|
*%val{selection}*::
|
||||||
|
_in window scope_ +
|
||||||
|
content of the main selection
|
||||||
|
|
||||||
|
*%val{selections}*::
|
||||||
|
_in window scope_ +
|
||||||
|
quoted list of the contents of all selections
|
||||||
|
|
||||||
|
*%val{selection_desc}*::
|
||||||
|
_in window scope_ +
|
||||||
|
range of the main selection, represented as `a.b,c.d` where _a_
|
||||||
|
is the anchor line, _b_ is the anchor column, _c_ is the cursor
|
||||||
|
line (like `%val{cursor_line}`), _d_ is the cursor column (like
|
||||||
|
`%val{cursor_char_column}`), and all are 1-based decimal integers
|
||||||
|
|
||||||
|
*%val{selections_desc}*::
|
||||||
|
_in window scope_ +
|
||||||
|
unquoted list of the ranges of all selections, in the same format as
|
||||||
|
`%val{selection_desc}`
|
||||||
|
|
||||||
|
*%val{session}*::
|
||||||
name of the current session
|
name of the current session
|
||||||
|
|
||||||
*kak_client*::
|
*%val{source}*::
|
||||||
name of the current client
|
_in `.kak` file_ +
|
||||||
|
path of the file currently getting executed (through the source command)
|
||||||
|
|
||||||
*kak_client_pid*::
|
*%val{text}*::
|
||||||
process id of the current client
|
_in `prompt` command <command> parameter_ +
|
||||||
|
the text entered by the user in response to the `prompt` command
|
||||||
|
|
||||||
*kak_client_list*::
|
*%val{timestamp}*::
|
||||||
unquoted list of the names of clients connected to the current session
|
_in buffer scope_ +
|
||||||
|
timestamp of the current buffer, an integer that increments each time the
|
||||||
|
buffer is modified, including undoing and redoing previous modifications
|
||||||
|
(see also `%val{history_id}`)
|
||||||
|
|
||||||
*kak_source*::
|
*%val{user_modes}*::
|
||||||
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_text*::
|
|
||||||
the text entered by the user at a `prompt` command, not available in other
|
|
||||||
contexts
|
|
||||||
|
|
||||||
*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.
|
unquoted list of user modes.
|
||||||
|
|
||||||
Quoted lists are separated by spaces, and each element is surrounded by
|
*%val{version}*::
|
||||||
`'` with contained `'` doubled. Unquoted lists are simply separated by
|
version of the current Kakoune server (git hash or release name)
|
||||||
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
|
*%val{window_height}*::
|
||||||
variable has to be spelled out within the body of the expansion.
|
_in window scope_ +
|
||||||
|
height of the current Kakoune window
|
||||||
|
|
||||||
Those environment variables are available in every context where
|
*%val{window_width}*::
|
||||||
Kakoune use a shell command, such as the `|`, `!` or `$` normal
|
_in window scope_ +
|
||||||
mode commands (See <<keys#,`:doc keys`>>).
|
width of the current Kakoune window
|
||||||
|
|
||||||
== Markup strings
|
Values in the above list that do not mention a context are available
|
||||||
|
everywhere. Values that mention "buffer scope" are also available in window
|
||||||
|
scope.
|
||||||
|
|
||||||
In certain contexts, Kakoune can take a markup string, which is a string
|
A value described as a "quoted list" will follow the rules of Kakoune string
|
||||||
containing formatting informations. In these strings, the {facename}
|
quoting (See <<command-parsing#,`:doc command-parsing`>>). An "unquoted list"
|
||||||
syntax will enable the face facename until another face gets activated,
|
cannot contain any special characters that would require quoting.
|
||||||
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 ('\\').
|
|
||||||
|
|
|
||||||
|
|
@ -128,3 +128,21 @@ The following faces are used by builtin highlighters if enabled.
|
||||||
|
|
||||||
*Whitespace*::
|
*Whitespace*::
|
||||||
face used by the `show-whitespaces` highlighter
|
face used by the `show-whitespaces` highlighter
|
||||||
|
|
||||||
|
== 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.
|
||||||
|
|
||||||
|
For example, the following command displays the text "default" in the
|
||||||
|
Default face, and "error" in the Error face:
|
||||||
|
|
||||||
|
----
|
||||||
|
echo -markup 'default {Error}error{Default} default'
|
||||||
|
----
|
||||||
|
|
||||||
|
Inside a markup string, a literal `{` character is written `\{`, and a
|
||||||
|
literal backslash (`\`) that precedes a '{' character is escaped as well
|
||||||
|
(`\\`).
|
||||||
|
|
|
||||||
|
|
@ -108,7 +108,9 @@ are exclusively available to built-in options.
|
||||||
a list of `<text>|<docstring>|<menu text>` candidates,
|
a list of `<text>|<docstring>|<menu text>` candidates,
|
||||||
except for the first element which follows the
|
except for the first element which follows the
|
||||||
`<line>.<column>[+<length>]@<timestamp>` format to define where the
|
`<line>.<column>[+<length>]@<timestamp>` format to define where the
|
||||||
completion apply in the buffer. Markup can be used in the menu text.
|
completion apply in the buffer. Markup (see
|
||||||
|
<<faces#markup-strings,`:doc faces markup-strings`>>) can be used in the
|
||||||
|
menu text.
|
||||||
`set -add` adds a new completion to the list
|
`set -add` adds a new completion to the list
|
||||||
|
|
||||||
*enum(value1|value2|...)*::
|
*enum(value1|value2|...)*::
|
||||||
|
|
@ -248,7 +250,8 @@ are exclusively available to built-in options.
|
||||||
*modelinefmt* `string`::
|
*modelinefmt* `string`::
|
||||||
A format string used to generate the mode line, that string is
|
A format string used to generate the mode line, that string is
|
||||||
first expanded as a command line would be (expanding '%...{...}'
|
first expanded as a command line would be (expanding '%...{...}'
|
||||||
strings), then markup tags are applied (See <<expansions#,`:doc expansions`>>)
|
strings), then markup tags are applied (see
|
||||||
|
<<faces#markup-strings,`:doc faces markup-strings`>>)
|
||||||
Two special atoms are available as markup:
|
Two special atoms are available as markup:
|
||||||
|
|
||||||
*`{{mode_info}}`*:::
|
*`{{mode_info}}`*:::
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user