diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 56 |
1 files changed, 33 insertions, 23 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 349df2f251..6fd0ae1715 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1856,7 +1856,8 @@ setreg( {n}, {v}[, {opt}]) Number set register to value and type settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window {winnr} in tab page {tabnr} to {val} setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val} -shellescape( {string}) String escape {string} for use as shell +shellescape( {string} [, {special}]) + String escape {string} for use as shell command argument simplify( {filename}) String simplify filename as much as possible sin( {expr}) Float sine of {expr} @@ -4018,10 +4019,10 @@ mkdir({name} [, {path} [, {prot}]]) < *mode()* mode([expr]) Return a string that indicates the current mode. - If [expr] is supplied and it evaluates to a non-zero number or - a non-empty string, then the full mode is returned, otherwise - only the first letter is returned. Note that " " and "0" are - also non-empty strings. + If [expr] is supplied and it evaluates to a non-zero Number or + a non-empty String (|non-zero-arg|), then the full mode is + returned, otherwise only the first letter is returned. Note + that " " and "0" are also non-empty strings. n Normal no Operator-pending @@ -4941,19 +4942,23 @@ setwinvar({nr}, {varname}, {val}) *setwinvar()* :call setwinvar(1, "&list", 0) :call setwinvar(2, "myvar", "foobar") -shellescape({string}) *shellescape()* +shellescape({string} [, {special}]) *shellescape()* Escape {string} for use as shell command argument. On MS-Windows and MS-DOS, when 'shellslash' is not set, it - will enclose {string} double quotes and double all double + will enclose {string} in double quotes and double all double quotes within {string}. For other systems, it will enclose {string} in single quotes and replace all "'" with "'\''". - Example: > - :echo shellescape('c:\program files\vim') -< results in: - "c:\program files\vim" ~ - Example usage: > - :call system("chmod +x -- " . shellescape(expand("%"))) + When the {special} argument is present and it's a non-zero + Number or a non-empty String (|non-zero-arg|), then special + items such as "%", "#" and "<cword>" will be preceded by a + backslash. This backslash will be removed again by the |:!| + command. + Example of use with a |:!| command: > + :exe '!dir ' . shellescape(expand('<cfile>'), 1) +< This results in a directory listing for the file under the + cursor. Example of use with |system()|: > + :call system("chmod +w -- " . shellescape(expand("%"))) simplify({filename}) *simplify()* @@ -5333,13 +5338,14 @@ system({expr} [, {input}]) *system()* *E677* passed as stdin to the command. The string is written as-is, you need to take care of using the correct line separators yourself. Pipes are not used. - Note: newlines in {expr} may cause the command to fail. The - characters in 'shellquote' and 'shellxquote' may also cause - trouble. + Note: Use |shellescape()| to escape special characters in a + command argument. Newlines in {expr} may cause the command to + fail. The characters in 'shellquote' and 'shellxquote' may + also cause trouble. This is not to be used for interactive commands. - The result is a String. Example: > - :let files = system("ls") + The result is a String. Example: > + :let files = system("ls " . shellescape(expand('%:h'))) < To make the result more system-independent, the shell output is filtered to replace <CR> with <NL> for Macintosh, and @@ -5559,11 +5565,13 @@ visualmode([expr]) *visualmode()* Visual mode that was used. If Visual mode is active, use |mode()| to get the Visual mode (e.g., in a |:vmap|). - - If [expr] is supplied and it evaluates to a non-zero number or - a non-empty string, then the Visual mode will be cleared and + *non-zero-arg* + If [expr] is supplied and it evaluates to a non-zero Number or + a non-empty String, then the Visual mode will be cleared and the old value is returned. Note that " " and "0" are also - non-empty strings, thus cause the mode to be cleared. + non-empty strings, thus cause the mode to be cleared. A List, + Dictionary or Float is not a Number or String, thus does not + cause the mode to be cleared. *winbufnr()* winbufnr({nr}) The result is a Number, which is the number of the buffer @@ -6738,8 +6746,10 @@ This would call the function "my_func_whizz(parameter)". Be careful to correctly escape special characters in file names. The |fnameescape()| function can be used - for this. Example: > + for Vim commands, |shellescape()| for |:!| commands. + Examples: > :execute "e " . fnameescape(filename) + :execute "!ls " . shellescape(expand('%:h'), 1) < Note: The executed string may be any command-line, but you cannot start or end a "while", "for" or "if" |