*vimproc.txt*	Asynchronous execution plugin for Vim

Version: 7.1
Author : Shougo <Shougo.Matsu at gmail.com>
Original Author : Yukihiro Nakadaira <yukihiro.nakadaira at gmail.com>
License: MIT license  {{{
    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:
    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
    OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}}}

CONTENTS					*vimproc-contents*

Introduction		|vimproc-introduction|
Install			|vimproc-install|
Interface		|vimproc-interface|
  Commands		  |vimproc-commands|
  Functions		  |vimproc-functions|
  Variables		  |vimproc-variables|
Tips			|vimproc-tips|
Examples		|vimproc-examples|
FAQ			|vimproc-faq|

==============================================================================
INTRODUCTION					*vimproc-introduction*

|vimproc| is great asynchronous execution library for Vim.  Original vimproc is
created by Yukihiro Nakadaira.  But I'm maintaining it now.
Instead of external shell(example: 'shell'), |vimproc| uses external dll file.

==============================================================================
INSTALL						*vimproc-install*

In first, you get vimproc from git repository.

http://github.com/Shougo/vimproc

Next, make external dll "vimproc_xxx.so(or vimproc_win32.dll,
vimproc_cygwin.dll)".  Because vimproc depends on "vimproc_xxx.so(or
vimproc_win32.dll, vimproc_cygwin.dll)"'s function, vimproc echo error message
when "vimproc_xxx.so(vimproc_xxx.dll)" don't exist.

Note: The vimproc_cygwin.dll compiled in Cygwin won't work with Windows Vim.

Supported platforms:
* Windows 32/64bit (Compiled by MinGW or Visual Studio)
* Mac OS X (10.5 or later)
* Linux
* Cygwin
* Solaris
* BSD (but cannot check)
* Android (experimental)

Note: You must use GNU make to build vimproc.

Note: In Windows, using MinGW is recommended.

Note: In Windows, to build it by Visual Studio, you must install Windows SDK.

Not supported platforms:
* Other UNIX platforms

Build Steps:

Note: You must use GNU make to build vimproc.

Linux and Mac OS X

	$ make

Windows

Note: In Windows, using MinGW is recommended.

Windows using Mingw (32bit Vim):

	$ make -f make_mingw32.mak

Windows using Mingw (64bit Vim):

	$ make -f make_mingw64.mak

Windows using newer version of Visual Studio(32bit/64bit Vim):
	$ nmake -f make_msvc.mak nodebug=1

Windows using old version of Visual Studio for 32bit Vim (Ex: Visual Studio 2005):
	$ SET INCLUDE=%INCLUDE%;C:\Program Files\Microsoft SDKs\Windows\v7.1\Include
	$ SET LIB=%LIB%;C:\Program Files\Microsoft SDKs\Windows\v7.1\Lib
	$ nmake -f make_msvc32.mak

Note: To build with Visual Studio, you must install Windows SDK.

* Cygwin:

	$ make -f make_cygwin.mak

Note: The `vimproc_cygwin.dll` compiled in Cygwin won't work with Windows Vim.


If you use |neobundle.vim|, you can update and build vimproc automatically.
http://github.com/Shougo/neobundle.vim

Example for neobundle:
>
	NeoBundle 'Shougo/vimproc', {
	      \ 'build' : {
	      \     'windows' : 'make -f make_mingw32.mak',
	      \     'cygwin' : 'make -f make_cygwin.mak',
	      \     'mac' : 'make -f make_mac.mak',
	      \     'unix' : 'make -f make_unix.mak',
	      \    },
	      \ }
<

==============================================================================
INTERFACE					*vimproc-interface*

------------------------------------------------------------------------------
COMMANDS 					*vimproc-commands*

:VimProcBang {path}					*:VimProcBang*
			Executes {path} command and echo result.  This
			command replaces |:!|.

:VimProcRead {path}					*:VimProcRead*
			Executes {path} command and paste result in current
			buffer.  This command replaces |:read|.

------------------------------------------------------------------------------
FUNCTIONS 					*vimproc-functions*

vimproc#version()				*vimproc#version()*
		Returns vimproc version number as string.  Version 5.0 is
		"500".  Version 5.1 (5.01) is "501" same as |v:version|.

vimproc#dll_version()				*vimproc#dll_version()*
		Same to |vimproc#version()|, but it returns vimproc dll
		version.

vimproc#open({filename})			*vimproc#open()*
		Opens {filename} with a system associated command.

vimproc#get_command_name({command} [, {path} [, {count}]])	*vimproc#get_command_name()*
		Searches {command} from {path} and returns command name.  If you
		omit {path}, uses $PATH instead.  If you set {count}, returns
		{count} candidate.  If you set {count} is a negative Number,
		returns as a list.  If {count} is omitted, then 1 is used.

vimproc#system({expr} [, {input} [, {timeout}]])	*vimproc#system()*
		It replaces |system()|.  If you call |system()| in Windows
		environment, DOS window will appear.  But, |vimproc#system()|
		is not.
		Note: It does not execute a shell.  So a shell internal command is
		invalid.  Ex: pwd, cd, ...
		
		The {expr} are same to |vimproc#plineopen3()|.  The type is
		string or arguments list.  If {expr} is string, it parsed
		automatically.
		If the end of {expr} is "&", executes a command in the background.
>
		call vimproc#system('ls &')
<
		If you set {timeout}, vimproc will kill the process after
		{timeout} and throw "vimproc: vimproc#system(): Timeout."
		exception.
		The unit is millisecond.
		Note: |+reltime| and Vim 7.2 is required.
		If you set {input}, inputs the string to the command.

vimproc#system2({expr} [, {input}, {timeout}])	*vimproc#system2()*
		Same as |vimproc#system()|.  But it converts encoding
		automatically.

vimproc#system_passwd({expr} [, {input}, {timeout}])
						*vimproc#system_passwd()*
		Same as |vimproc#system()|.  But it supports password input.

vimproc#system_bg({expr})			*vimproc#system_bg()*
		Same as |vimproc#parser#system()|.  But it executes a command in
		the background.
		Note: It disables user input.
		Note: This function is not supported statements(";", "&&",
		"||").

vimproc#system_gui({expr})			*vimproc#system_gui()*
		Same as |vimproc#system_bg()|.  But it executes a GUI command in
		the background.

vimproc#cmd#system({expr})			*vimproc#cmd#system()*
		Similar to |vimproc#system()|.  But it executes "cmd.exe" by
		background.
		Note: It is available in Windows only.

vimproc#get_last_status()			*vimproc#get_last_status()*
		Gets last |vimproc#system()| status value.

vimproc#get_last_errmsg()			*vimproc#get_last_errmsg()*
		Gets last |vimproc#system()| error messages.

vimproc#shellescape({string})			*vimproc#shellescape()*
		Escapes {string} for vimproc function arguments.

vimproc#fopen({path}, {flags} [, {mode}])	*vimproc#fopen()*
		Opens {path} file.
		The {flags} is same flags to open() in the C language as string.

vimproc#socket_open({host}, {port})		*vimproc#socket_open()*
		Opens the {host}:{port} socket and returns a socket object.
		The {host} is a String.  The {port} is a Number.

vimproc#host_exists({host})			*vimproc#host_exists()*
		Checks to see if {host} exists.
		Note: Protocol name and path are ignored.

vimproc#popen2({args})				*vimproc#popen2()*
		Executes {args} command and returns a process object.
		If {args} is a String, {args} is parsed automatically.
		
		The {args} is split by arguments list.

vimproc#popen3({args})				*vimproc#popen3()*
		Same as |vimproc#popen2()|, but this function splits
		stderr output.

vimproc#plineopen2({commands})			*vimproc#plineopen2()*
		Executes {commands} command and returns a process object.
		If {commands} is a String, {commands} is parsed automatically.
		Note: You can use pipes.
		
		The {commands} is a list of dictionaries.
		The keys are follows:
		args			The arguments list.
		fd			The output filename.  If it is empty, the
					output is sent to the next process.

vimproc#plineopen3({commands})			*vimproc#plineopen3()*
		Same as |vimproc#plineopen2()|, but this function splits
		stderr output.

vimproc#pgroup_open({commands}, [{is-pty}])	*vimproc#pgroup_open()*
		Executes {commands} command and returns a process object.
		If {commands} is a String, {commands} is parsed automatically.
		Note: You can use pipes and ";","&&","||".
		
		The {statements} is a dictionary list split by commands.
		The keys are follows:
		statement		The execute pipeline information same
					to |vimproc#plineopen2()| args.
		condition		The condition which executes next command.
					"always" : execute always.
					"true"   : execute if previous command
					is succeed.
					"false"  : execute if previous command
					is failed.
		If {is-pty} is 1, vimproc will use pty.

vimproc#ptyopen({args}, [{npipe}])		*vimproc#ptyopen()*
		Executes {args} command and returns a process object.
		If {args} is a String, {args} is parsed automatically.
		The {npipe} is 2 or 3.  If it is 2, combines stdout and
		stderr.
		Note: You can use pipes.
		
		The {args} is split by arguments list.

vimproc#kill({pid}, {sig})			*vimproc#kill()*
		Sends {sig} signal to {pid} process.
		If an error is occurred, it returns 1 for error and sets
		|vimproc#get_last_errmsg()|.
		If {sig} is 0, it checks whether {pid} exists.

vimproc#write({filename}, {string}, [{mode}])		*vimproc#write()*
		Writes {string} to {filename} file.
		The {mode} is a write mode. "w" or "b" or "a" is valid.
				"w" : normal mode.
				"b" : binary mode.
				"a" : append mode.
		If you omit {mode}, use "w".
		But {filename} head is ">", "a" is used.

vimproc#readdir({dirname})				*vimproc#readdir()*
		Returns files in {dirname}.  If {dirname} is not found, returns
		an empty list.
		Note: Filename encoding is converted to 'termencoding'.

vimproc#delete_trash({filename})			*vimproc#delete_trash()*
		Moves a file {filename} to a trashbox directory.
		Note: Windows environment only.
		Note: Filename encoding is converted to 'termencoding'.

------------------------------------------------------------------------------
VARIABLES 					*vimproc-variables*

						*g:vimproc#dll_path*
g:vimproc#dll_path	(default
			Win32: "$VIMRUNTIME/autoload/vimproc_win32.dll"
			Win64: "$VIMRUNTIME/autoload/vimproc_win64.dll"
			Cygwin: "$VIMRUNTIME/autoload/vimproc_cygwin.dll"
			Mac: "$VIMRUNTIME/autoload/vimproc_mac.so"
			others: "$VIMRUNTIME/autoload/vimproc_unix.so")
		This variable is dll name used by vimproc.  You must compile
		this dll file.  If this dll is not exist, vimproc will echo
		error.
						*g:vimproc_dll_path*
		Note: |g:vimproc_dll_path| is obsolete name.

						*g:vimproc#popen2_commands*
g:vimproc#popen2_commands	(default : refer to autoload/vimproc.vim)
		This variable is that vimproc use popen2 commands instead of
		popen3 as dictionary.  The key is command name and the value is
		1 or 0.  If the command does not work in popen3, you can set this
		variable.
						*g:vimproc_popen2_commands*
		Note: |g:vimproc_popen2_commands| is obsolete name.

						*g:vimproc#password_pattern*
g:vimproc#password_pattern	(default : refer to autoload/vimproc.vim)
		The default password pattern.
		Note: This variable is used for vimshell.
						*g:vimproc_password_pattern*
		Note: |g:vimproc_password_pattern| is obsolete name.

						*g:stdinencoding*
g:stdinencoding			(default : "char")
		The default vimproc stdin encoding.

						*g:stdoutencoding*
g:stdoutencoding		(default : "char")
		The default vimproc stdout encoding.

						*g:stderrencoding*
g:stderrencoding		(default : "char")
		The default vimproc stderr encoding.

==============================================================================
TIPS						*vimproc-tips*

Pseudo devices					*vimproc-tips-pseudo-devices*
		vimproc supports pseudo devices:
		
		/dev/null
		Remove all output.
		
		/dev/clip
		Print to clipboard.
		
		/dev/quickfix
		Print to |quickfix|.

==============================================================================
EXAMPLES					*vimproc-examples*
>
	" File open test.
	let file = vimproc#fopen("./test1.vim", "O_RDONLY", 0)
	let res = file.read()
	call file.close()
	new
	call append(0, split(res, '\r\n\|\r\|\n'))
	
	" Pipe open test.
	let sub = vimproc#popen2('ls')
	let res = ''
	while !sub.stdout.eof
	let res .= sub.stdout.read()
	endwhile
	let [cond, status] = sub.waitpid()
	new
	call append(0, split(res, '\r\n\|\r\|\n') + [string([cond, status])])
	
	" Socket open test.
	let sock = vimproc#socket_open('www.yahoo.com', 80)
	call sock.write("GET / HTTP/1.0\r\n\r\n")
	let res = ''
	while !sock.eof
	let res .= sock.read()
	endwhile
	call sock.close()
	new
	call append(0, split(res, '\r\n\|\r\|\n'))
<
==============================================================================
FAQ						*vimproc-faq*

Q: I want to check a process is a zombie process.

A: You can use vimproc#kill({pid}, 0) or {process}.kill(0).

==============================================================================
vim:tw=78:ts=8:ft=help:norl:noet:fen:
