From 95da8cbc8fc1b7d87e89291bf40c0855d41e3108 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Sat, 22 Jun 2019 17:22:21 +1000 Subject: [PATCH] Document $kak_quoted_... --- doc/pages/changelog.asciidoc | 3 +++ doc/pages/expansions.asciidoc | 19 +++++++++---------- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/doc/pages/changelog.asciidoc b/doc/pages/changelog.asciidoc index 156e6472..182b962e 100644 --- a/doc/pages/changelog.asciidoc +++ b/doc/pages/changelog.asciidoc @@ -31,6 +31,9 @@ released versions. * Added a new hook `ModuleLoad` which is run when a module is loaded, allowing for module specific configuration. +* Shell quoting of lists is not automatic anymore, `$kak_quoted_...` + makes it opt-in, and works for all option types. + == Kakoune 2019.01.20 * `auto_complete` has been renamed to `autocomplete` for more diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index 9f3f5f95..63980b8e 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -128,24 +128,23 @@ Here's how expansion patterns map to variable names: *%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: +Values can be quoted with a shell compatible quoting by using `$kak_quoted_` +as a prefix, this is mostly useful for list-type options and registers, as +it allows to correctly work with lists where elements might contains +whitespaces: ---- -eval set -- "$kak_selections" +eval set -- "$kak_quoted_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. +The `eval` command will take the expanded `$kak_quoted_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: