Merge remote-tracking branch 'Screwtapello/rewrite-expansions-doc'

This commit is contained in:
Maxime Coste 2018-10-01 11:06:38 +10:00
commit 97800b3c61
5 changed files with 274 additions and 152 deletions

View File

@ -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.

View File

@ -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

View File

@ -1,199 +1,299 @@
= 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
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 %-strings or 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 %{%val{session}}"` echoes the the literal text `%val{session}`
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 Like "variable expansion" and "command substitution" in shell programming,
character. They will be written *%<type>\{<content>\}*. They will be Kakoune expansions can expand to multiple "words" - that is, separate
expanded according to the given *<type>* using *<content>* as its arguments on the resulting command-line. However, unlike shell programming,
parameter: Kakoune expansions cannot _accidentally_ expand to multiple words, even if
the expansion contains whitespace or other special characters. While in
shell-programming it's good practice to always wrap expansions in
double-quotes, in Kakoune it's perfectly safe to leave expansions unquoted.
*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, as individual words
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 theres 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 by name
in a comment, even though it wasn't directly used.
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` give access to Kakoune internal data that is
not stored in an option or a register. Some value expansions can only be used
in certain contexts, like `%val{hook_param}` that expands to the parameter
string of the currently-executing hook, and is not available outside a hook.
The following expansions are supported (with required context _in italics_):
*%val{buffile}*::
_in buffer, window scope_ +
full path of the file or same as `%val{bufname}` when theres no
associated file associated file
*kak_buflist*:: *%val{buf_line_count}*::
quoted list of the currently opened buffer names _in buffer, window 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, window 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, window 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, window 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, window 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.
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 ('\\').

View File

@ -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
(`\\`).

View File

@ -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}}`*:::