*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 can't work for 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

Below is Make command:

* 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

* Mac OS X: >
 $ make -f make_mac.mak

* Linux/BSD: >
 $ make -f make_unix.mak

* Cygwin: >
 $ make -f make_cygwin.mak

* Solaris/SunOS: >
	$ gmake -f make_sunos.mak

* Android: >
	$ make -f make_android.mak

After compile, you copy autoload/* and plugin/* files to your
'runtimepath' directory.

I compiled vimproc_win**.dll in 32/64 bit Windows, and distributed it below
URL.
Note: I DON'T recommend to use it. You should build dll files manually.
https://github.com/Shougo/vimproc/downloads
Note: Github downloads feature is deprecated. It may be deleted.

You can use Kaoriya Vim in Windows. It includes vimproc dll file.
(http://www.kaoriya.net/news/2012/20121213)

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*
			Execute {path} command and echo result.  This
			command replaces |:!|.

:VimProcRead {path}					*:VimProcRead*
			Execute {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 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}, use $PATH instead.  If you set {count}, returns
		{count} candidate. If you set {count} is -1, returns as list.

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

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 execute command in
		background.
		Note: It disables user input.

vimproc#system_gui({expr})			*vimproc#system_gui()*
		Same as |vimproc#system_bg()|. But it executes GUI command in
		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()*
		Get last |vimproc#system()| status value.

vimproc#get_last_errmsg()			*vimproc#get_last_errmsg()*
		Get last |vimproc#system()| error message.

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

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

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

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

vimproc#popen2({args})				*vimproc#popen2()*
		Executes {args} command and returns the process object.
		If {args} is 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 the process object.
		If {commands} is string, {commands} is parsed automatically.
		Note: You can use pipes.
		
		The {commands} is dictionary list.
		The keys are follows:
		args			The arguments list.
		fd			The output filename. If it empty, the
					output is sent to 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 the process object.
		If {commands} is string, {commands} is parsed automatically.
		Note: You can use pipes and ";","&&","||".
		
		The {statements} is 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 the process object.
		If {args} is string, {args} is parsed automatically.
		The {npipe} is 2 or 3. If it is 2, will combine stdout and
		stderr.
		Note: You can use pipes.
		
		The {args} is split by arguments list.

vimproc#kill({pid}, {sig})			*vimproc#kill()*
		Send {sig} signal to {pid} process.
		If error is occurred, it will return 1 for error and set
		|vimproc#get_last_errmsg()|.
		If {sig} is 0, it check whether {pid} is exists.

vimproc#write({filename}, {string}, [{mode}])		*vimproc#write()*
		Writes {string} to {filename} file.
		The {mode} is 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
		empty list.
		Note: Filename encoding is converted to 'termencoding'.

vimproc#delete_trash({filename})			*vimproc#delete_trash()*
		Move file to 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 do 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 process is zombie.

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

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