<commit_before>= Expansions

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.

Every expansion consists of a `%`, followed by the expansion _type_ (one
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.

Expansions are processed when unquoted and anywhere inside double-quoted
strings, but not inside unquoted words, inside single-quoted strings, or
inside %-strings or other expansions. So:

* `echo %val{session}` echoes the current session ID

* `echo x%val{session}x` echoes the literal text `x%val{session}x`

* `echo '%val{session}'` echoes the literal text `%val{session}`

* `echo "x%val{session}x"` echoes the current session ID, surrounded by `x`

* `echo %{%val{session}}"` echoes the the literal text `%val{session}`

* `echo %sh{ echo %val{session} }"` echoes the literal text `%val{session}`

Like "variable expansion" and "command substitution" in shell programming,
Kakoune expansions can expand to multiple "words" - that is, separate
arguments on the resulting command-line. However, unlike shell programming,
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<commit_msg>Update and clarify expansion/quoting docs<commit_after>= Expansions

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.

Every expansion consists of a `%`, followed by the expansion _type_ (one
or more alphabetic characters), a quoting character, and then all the text
up to and including its matching character.

If an openning brace (`(`, `[`, `{`, or `<`) is used as the openning quoting
character, the expansion will end at the character's matching brace (`)`, `]`,
`}`, or `>`). Nested pairs of the braces used in the expansion are allowed, but
they must be balanced. Braces other than the ones used in the expansion need
not be balanced, however. For example, `%{nest{ed} non[nested}` is valid and
expands to `nest{ed} non[nested`.

If any other character is used, the expansion will end at the next occurance of
that character. The quoting character can be escpaed inside the expansion if it
is doubled-up. For example, `%|abc||def|` expands to the text `abc|def`.

It doesn't matter which character is used, but `{}` are most common.

There are 2 types of quoting which can be used to group together words separated
by whitespace into a single argument or prevent expansions from expanding:

"double quoted strings"::
    Double quoted strings are mainly for grouping multiple `%` expansions or
    `%` expansions and regular text as a single argument. `%` and `"` can be
    escaped by doubling the characters (i.e. `%%` and `""`).

'single quoted strings'::
    Expansions are not processed inside single quoted strings. Single quotes can
    be escaped by doubling up (i.e. `''`).

Expansions are processed when unquoted and anywhere inside double-quoted
strings, but not inside unquoted words, inside single-quoted strings, or
inside %-strings or other expansions. So:

* `echo %val{session}` echoes the current session ID

* `echo x%val{session}x` echoes the literal text `x%val{session}x`

* `echo '%val{session}'` echoes the literal text `%val{session}`

* `echo "x%val{session}x"` echoes the current session ID, surrounded by `x`

* `echo %{%val{session}}"` echoes the the literal text `%val{session}`

* `echo %sh{ echo %val{session} }"` echoes the literal text `%val{session}`

Like "variable expansion" and "command substitution" in shell programming,
Kakoune expansions can expand to multiple "words" - that is, separate
arguments on the resulting command-line. However, unlike shell programming,
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
{'fraction_non_alphanumeric': 0.09379827852571176, 'fraction_numerical': 0.00022070183182520416, 'mean_word_length': 5.1409214092140925, 'pattern_counts': {'":': 1, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3370359', 'n_tokens_mistral': 1265, 'n_tokens_neox': 1206, 'n_words': 603}