Hi Bram
On 2015-07-22 Wednesday at 02:01 +0200 Roland Eggner wrote:
> On 2015-07-22 Wednesday at 00:25 +0200 Roland Eggner wrote:
> > On 2015-07-21 Tuesday at 14:04 +0200 Bram Moolenaar wrote:
> > > Roland Eggner wrote:
> > > > Despite having used vim, “:help …” and “:helpgrep …” almost daily for 9
> > > > years
> > > > I was not aware of the special effect of the equal sign in `= … ` until
> > > > a recent bugreport from Pavol Juhas regarding this feature.
> > > > Surprisingly
> > > > “:help improvements-6” hints, that this feature has been there since
> > > > early
> > > > days of the vim-6 period.
> > > >
> > > > My patch provided below should
> > > > • improve accessibility of “:help `=” by adding references at useful
> > > > points
> > > > in “runtime/doc/cmdline.txt” -- currently there are no such
> > > > references at all
> > > > • improve “:help `=” by adding a hint, under which condition this
> > > > feature can
> > > > be used
> > >
> > > Thanks!
> >
> > v2:
> > • “:help `-expansion”:
> > Improved example and added a 2nd one.
> > • “:help `=”:
> > Added a 2nd example showing how to refer environment variables using
> > “expand( … )”.
> > Added a 3rd example showing what interesting, only in rare cases desired
> > effects are possible when the “expand( … )” call is missing and the
> > value --
> > not only the name -- of an environment variable is evaluated (inspired
> > by
> > issue 385 “expansion of environment variables fails in Vim backtick
> > expression”).
> > • Fixed a few typos spotted nearby.
>
> v3:
> Updated for vim-7.4.794.
> Previous versions accidentally where based on 7.4.529, sorry.
v4:
Further improvements based on imput from Pavol Juhas (mail thread “Issue 385 in
vim: expansion of environment variables fails in Vim backtick expression”).
For easier review 6 lines of context instead of the usual 3.
I am unsure if the added tag is a proper solution: There is already a tag
“E15”, thus I chose the tag name “E15_`”. It should help if someone uses the
`=
syntax, gets “E15”, and types “:h E15<TAB>”. Is there a better solution to
guide users getting „E15” to |`=| ?
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -747,19 +747,19 @@ output.
Note: These are special characters in the executed command line. If you want
to insert special things while typing you can use the CTRL-R command. For
example, "%" stands for the current file name, while CTRL-R % inserts the
current file name right away. See |c_CTRL-R|.
-Note: If you want to avoid the special characters in a Vim script you may want
-to use |fnameescape()|. Also see |`=|.
+Note: If you want to avoid the effects of special characters in a Vim script
+you may want to use |fnameescape()|. Also see |`=|.
In Ex commands, at places where a file name can be used, the following
characters have a special meaning. These can also be used in the expression
-function expand() |expand()|.
+function |expand()|.
% Is replaced with the current file name. *:_%* *c_%*
# Is replaced with the alternate file name. *:_#* *c_#*
This is remembered for every window.
#n (where n is a number) is replaced with *:_#0* *:_#n*
the file name of buffer n. "#0" is the same as "#". *c_#n*
## Is replaced with all names in the argument list *:_##* *c_##*
@@ -789,12 +789,13 @@ Detail: The special meaning is always escaped when there
is a backslash before
it, no matter how many backslashes.
you type: result ~
# alternate.file
\# #
\\# \#
Also see |`=|.
+
*:<cword>* *:<cWORD>* *:<cfile>* *<cfile>*
*:<sfile>* *<sfile>* *:<afile>* *<afile>*
*:<abuf>* *<abuf>* *:<amatch>* *<amatch>*
*<slnum>* *E495* *E496* *E497* *E499* *E500*
Note: these are typed literally, they are not special keys!
<cword> is replaced with the word under the cursor (like |star|)
@@ -809,13 +810,13 @@ Note: these are typed literally, they are not special
keys!
buffer).
<amatch> When executing autocommands, is replaced with the match for
which this autocommand was executed. It differs from
<afile> only when the file name isn't used to match with
(for FileType, Syntax and SpellFileMissing events).
<sfile> When executing a ":source" command, is replaced with the
- file name of the sourced file. *E498*
+ file name of the sourced file. *E498*
When executing a function, is replaced with
"function {function-name}"; function call nesting is
indicated like this:
"function {function-name1}..{function-name2}". Note that
filename-modifiers are useless when <sfile> is used inside
a function.
@@ -931,15 +932,14 @@ name). This is included for backwards compatibility with
version 3.0, the
<cWORD> WORD under the cursor (see |WORD|)
<cfile> path name under the cursor
<cfile>< idem, without extension
Note: Where a file name is expected wildcards expansion is done. On Unix the
shell is used for this, unless it can be done internally (for speed).
-Backticks also work, like in >
+Unless in |restricted-mode|, backticks work also, like in >
:n `echo *.c`
-(backtick expansion is not possible in |restricted-mode|)
But expansion is only done if there are any wildcards before expanding the
'%', '#', etc.. This avoids expanding wildcards inside a file name. If you
want to expand the result of <cfile>, add a wildcard character to it.
Examples: (alternate file name is "?readme?")
command expands to ~
:e # :e ?readme?
@@ -964,13 +964,12 @@ special meaning. Therefore "\file\foo" is a valid file
name, you don't have
to type the backslash twice.
An exception is the '$' sign. It is a valid character in a file name. But
to avoid a file name like "$home" to be interpreted as an environment variable,
it needs to be preceded by a backslash. Therefore you need to use "/\$home"
for the file "$home" in the root directory. A few examples:
-
FILE NAME INTERPRETED AS ~
$home expanded to value of environment var $home
\$home file "$home" in current directory
/\$home file "$home" in root directory
\\$home file "\\", followed by expanded $home
Also see |`=|.
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -409,33 +409,50 @@ directory. Example: >
:n /usr/inc**/*.h
Finds files:
/usr/include/types.h
/usr/include/sys/types.h
/usr/inc_old/types.h
*backtick-expansion* *`-expansion*
-On Unix and a few other systems you can also use backticks in the file name,
-for example: >
- :e `find . -name ver\\*.c -print`
-The backslashes before the star are required to prevent "ver*.c" to be
-expanded by the shell before executing the find program.
-This also works for most other systems, with the restriction that the
-backticks must be around the whole item. It is not possible to have text
+On Unix and a few other systems you can also use backticks in the file name
+argument. E.g. add to the argument list all *.c files in and below the
+current directory modified within 1 hour, and view the youngest *.patch file
+in the current directory: >
+ :argadd `find . -name \\*.c -mmin -60 -print`
+ :view `ls -t *.patch \| head -n1`
+The backslashes before the star are required to prevent the shell from
+expanding "*.c" prior to execution of the find program. The backslash before
+the shell pipe symbol "|" prevents Vim from parsing it as command termination.
+This also works for most other systems, with the restriction that the
+backticks must be around the whole item. It is not possible to have text
directly before the first or just after the last backtick.
- *`=*
-You can have the backticks expanded as a Vim expression, instead of an
-external command, by using the syntax `={expr}` e.g.: >
- :e `=tempname()`
-The expression can contain just about anything, thus this can also be used to
-avoid the special meaning of '"', '|', '%' and '#'. However, 'wildignore'
-does apply like to other wildcards.
-If the expression returns a string then names are to be separated with line
-breaks. When the result is a |List| then each item is used as a name. Line
-breaks also separate names.
-Note that such expressions are only supported in places where a filename is
-expected as an argument to an Ex-command.
+ *`=* *E15_`*
+You can have the backticks expanded as a Vim expression, instead of as an
+external command, by using the syntax ``={expr}``. The expression can contain
+just about anything, thus this can also be used to save the escaping of spaces
+and characters with otherwise special meaning '"', '|', '%' and '#' (5th and
+6th example below). However, 'wildignore' does apply like to other wildcards.
+If the expression contains an unquoted environment variable reference without
+call to |expand()|, the value of this variable -- not only its name -- is
+evaluated as a Vim expression (3rd and 4th example below). Single or double
+quotes can be used to avoid this effect (5th and 6th example below). See also
+|expr-env-expand|.
+Some examples illustrate possible usages:
+ :edit ``=tempname()``
+ :edit `=expand('$HOME') . '/.vimrc'`
+ :let home = 2
+ :let user = 3 " assuming $HOME == '/home/user'
+ :edit `=36 $HOME . '/.vimrc'` " creates a buffer '6/.vimrc'
+ :edit `=$Hquoted . '/.vimrc'` " assuming $Hquoted == '"/home/user"'
+ :edit `='$HOME/filename with spaces + "ugly" % | # characters'`
+ :edit `="$HOME/filename with spaces + 'ugly' % | # characters"`
+If the expression returns a string then names are to be terminated by line
+terminators. When the result is a |List| then each item is used as a name.
+Line terminators also terminate names.
+Note that such expressions are only supported at places where a filename is
+expected as an argument to an Ex command.
*++opt* *[++opt]*
The [++opt] argument can be used to force the value of 'fileformat',
'fileencoding' or 'binary' to a value for one command, and to specify the
behavior for bad characters. The form is: >
++{optname}
@@ -1362,13 +1379,13 @@ There are a few things to remember when editing binary
files:
- Make sure the 'binary' option is set BEFORE loading the
file. Otherwise both <CR> <NL> and <NL> are considered to end a line
and when the file is written the <NL> will be replaced with <CR> <NL>.
- <Nul> characters are shown on the screen as ^@. You can enter them with
"CTRL-V CTRL-@" or "CTRL-V 000" {Vi cannot handle <Nul> characters in the
file}
-- To insert a <NL> character in the file split up a line. When writing the
+- To insert a <NL> character in the file split a line. When writing the
buffer to a file a <NL> will be written for the <EOL>.
- Vim normally appends an <EOL> at the end of the file if there is none.
Setting the 'binary' option prevents this. If you want to add the final
<EOL>, set the 'endofline' option. You can also read the value of this
option to see if there was an <EOL> for the last line (you cannot see this
in the text).
@@ -1392,13 +1409,14 @@ to see your text while you are editing it. When
filtering text with
":!filter" or using ":w !command" the text is also not encrypted, this may
reveal it to others. The 'viminfo' file is not encrypted.
You could do this to edit very secret text: >
:set noundofile viminfo=
:noswapfile edit secrets.txt
-Keep in mind that without a swap file you risk losing your work in a crash.
+Keep in mind that without a swap file you risk loosing your work in the event
+of a crash or a power failure.
WARNING: If you make a typo when entering the key and then write the file and
exit, the text will be lost!
The normal way to work with encryption, is to use the ":X" command, which will
ask you to enter a key. A following write command will use that key to
diff --git a/runtime/doc/tags b/runtime/doc/tags
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -3548,12 +3548,13 @@ E153 helphelp.txt /*E153*
E154 helphelp.txt /*E154*
E155 sign.txt /*E155*
E156 sign.txt /*E156*
E157 sign.txt /*E157*
E158 sign.txt /*E158*
E159 sign.txt /*E159*
+E15_` editing.txt /*E15_`*
E16 cmdline.txt /*E16*
E160 sign.txt /*E160*
E161 repeat.txt /*E161*
E162 message.txt /*E162*
E163 editing.txt /*E163*
E164 editing.txt /*E164*
--
Best regards,
Roland Eggner
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
pgpB9MSpfGHcF.pgp
Description: PGP signature
