From 5a4ba0b35ff80a8de44adda4f7c7235b93b852d4 Mon Sep 17 00:00:00 2001 From: lePerdu Date: Wed, 30 Jan 2019 15:46:40 -0500 Subject: [PATCH] Update and clarify expansion/quoting docs --- doc/pages/expansions.asciidoc | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index a14877a5..56bda28a 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -6,11 +6,33 @@ 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. +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