vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 1661:5bbc2d6658ad v7.2a.013

updated for version 7.2a-013

author	vimboss
date	Fri, 04 Jul 2008 09:44:11 +0000
parents	82b5078be2dd
children	0b796e045c42

comparison

equal deleted inserted replaced

-:a0c70314350f
+:5bbc2d6658ad
 setqflist( {list}[, {action}])	Number	modify quickfix list using {list}
 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}
 sort( {list} [, {func}])	List	sort {list}, using {func} to compare
 soundfold( {word})		String	sound-fold {word}
 		Not available on all systems.  To check use: >
 			:if exists("*mkdir")
 <
 							*mode()*
 mode([expr])	Return a string that indicates the current mode.
-		If [expr] is supplied and it evaluates to a non-zero number or
+		If [expr] is supplied and it evaluates to a non-zero Number or
-		a non-empty string, then the full mode is returned, otherwise
+		a non-empty String (|non-zero-arg|), then the full mode is
-		only the first letter is returned.  Note that " " and "0" are
+		returned, otherwise only the first letter is returned.  Note
-		also non-empty strings.
+		that " " and "0" are also non-empty strings.
 			n	Normal
 			no	Operator-pending
 			v	Visual by character
 			V	Visual by line
 		Like |settabwinvar()| for the current tab page.
 		Examples: >
 			: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: >
+		When the {special} argument is present and it's a non-zero
-			:echo shellescape('c:\program files\vim')
+		Number or a non-empty String (|non-zero-arg|), then special
-<		results in:
+		items such as "%", "#" and "<cword>" will be preceded by a
-			"c:\program files\vim" ~
+		backslash.  This backslash will be removed again by the |:!|
-		Example usage: >
+		command.
-			:call system("chmod +x -- " . shellescape(expand("%")))
+		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()*
 		Simplify the file name as much as possible without changing
 		the meaning.  Shortcuts (on MS-Windows) or symbolic links (on
 		Get the output of the shell command {expr}.
 		When {input} is given, this string is written to a file and
 		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
+		Note: Use |shellescape()| to escape special characters in a
-		characters in 'shellquote' and 'shellxquote' may also cause
+		command argument.  Newlines in {expr} may cause the command to
-		trouble.
+		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 " .  shellescape(expand('%:h')))
-			:let files = system("ls")
 <		To make the result more system-independent, the shell output
 		is filtered to replace <CR> with <NL> for Macintosh, and
 		<CR><NL> with <NL> for DOS-like systems.
 		The command executed is constructed using several options:
 <		This enters the same Visual mode as before.  It is also useful
 		in scripts if you wish to act differently depending on the
 		Visual mode that was used.
 		If Visual mode is active, use |mode()| to get the Visual mode
 		(e.g., in a |:vmap|).
+							*non-zero-arg*
-		If [expr] is supplied and it evaluates to a non-zero number or
+		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
+		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
 		associated with window {nr}.  When {nr} is zero, the number of
 		the buffer in the current window is returned.  When window
 		:execute "normal ixxx\<Esc>"
 <			This has an <Esc> character, see |expr-string|.
 			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"
 			command.  Thus this is illegal: >
 		:execute 'while i > 5'

Mercurial > vim

comparison runtime/doc/eval.txt @ 1661:5bbc2d6658ad v7.2a.013