document that the perl legacy interface is now also supported

2 files changed, 160 insertions, 4 deletions

diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt
index aa13df6035..f1d07ddb20 100644
--- a/runtime/doc/if_perl.txt
+++ b/runtime/doc/if_perl.txt
@@ -107,7 +107,162 @@ to the next.
 ==============================================================================
 2. The VIM module					*perl-vim*
 
-Note: Perl codes does not currently have access to the legacy "VIM" package.
+Perl code gets all of its access to Neovim via the "VIM" module.
+
+Overview >
+	print "Hello"				# displays a message
+	VIM::Msg("Hello")			# displays a message
+	VIM::SetOption("ai")			# sets a vim option
+	$nbuf = VIM::Buffers()			# returns the number of buffers
+	@buflist = VIM::Buffers()		# returns array of all buffers
+	$mybuf = (VIM::Buffers('a.c'))[0] 	# returns buffer object for 'a.c'
+	@winlist = VIM::Windows()		# returns array of all windows
+	$nwin = VIM::Windows()			# returns the number of windows
+	($success, $v) = VIM::Eval('&path')	# $v: option 'path', $success: 1
+	($success, $v) = VIM::Eval('&xyz')	# $v: '' and $success: 0
+	$v = VIM::Eval('expand("<cfile>")')	# expands <cfile>
+	$curwin->SetHeight(10)			# sets the window height
+	@pos = $curwin->Cursor()		# returns (row, col) array
+	@pos = (10, 10)
+	$curwin->Cursor(@pos)			# sets cursor to @pos
+	$curwin->Cursor(10,10)			# sets cursor to row 10 col 10
+	$mybuf = $curwin->Buffer()		# returns the buffer object for window
+	$curbuf->Name()				# returns buffer name
+	$curbuf->Number()			# returns buffer number
+	$curbuf->Count()			# returns the number of lines
+	$l = $curbuf->Get(10)			# returns line 10
+	@l = $curbuf->Get(1 .. 5)		# returns lines 1 through 5
+	$curbuf->Delete(10)			# deletes line 10
+	$curbuf->Delete(10, 20)			# delete lines 10 through 20
+	$curbuf->Append(10, "Line")		# appends a line
+	$curbuf->Append(10, "L1", "L2", "L3")	# appends 3 lines
+	@l = ("L1", "L2", "L3")
+	$curbuf->Append(10, @l)			# appends L1, L2 and L3
+	$curbuf->Set(10, "Line")		# replaces line 10
+	$curbuf->Set(10, "Line1", "Line2")	# replaces lines 10 and 11
+	$curbuf->Set(10, @l)			# replaces 3 lines
+
+Module Functions:
+
+							*perl-Msg*
+VIM::Msg({msg})
+			Displays the message {msg}.
+
+							*perl-SetOption*
+VIM::SetOption({arg})	Sets a vim option.  {arg} can be any argument that the
+			":set" command accepts.  Note that this means that no
+			spaces are allowed in the argument!  See |:set|.
+
+							*perl-Buffers*
+VIM::Buffers([{bn}...])	With no arguments, returns a list of all the buffers
+			in an array context or returns the number of buffers
+			in a scalar context.  For a list of buffer names or
+			numbers {bn}, returns a list of the buffers matching
+			{bn}, using the same rules as Vim's internal
+			|bufname()| function.
+			WARNING: the list becomes invalid when |:bwipe| is
+			used.
+
+							*perl-Windows*
+VIM::Windows([{wn}...])	With no arguments, returns a list of all the windows
+			in an array context or returns the number of windows
+			in a scalar context.  For a list of window numbers
+			{wn}, returns a list of the windows with those
+			numbers.
+			WARNING: the list becomes invalid when a window is
+			closed.
+
+							*perl-DoCommand*
+VIM::DoCommand({cmd})	Executes Ex command {cmd}.
+
+							*perl-Eval*
+VIM::Eval({expr})	Evaluates {expr} and returns (success, value) in list
+			context or just value in scalar context.
+			success=1 indicates that val contains the value of
+			{expr}; success=0 indicates a failure to evaluate
+			the expression.  '@x' returns the contents of register
+			x, '&x' returns the value of option x, 'x' returns the
+			value of internal |variables| x, and '$x' is equivalent
+			to perl's $ENV{x}.  All |functions| accessible from
+			the command-line are valid for {expr}.
+			A |List| is turned into a string by joining the items
+			and inserting line breaks.
+
+==============================================================================
+3. VIM::Buffer objects					*perl-buffer*
+
+Methods:
+
+							*perl-Buffer-Name*
+Name()		Returns the filename for the Buffer.
+
+							*perl-Buffer-Number*
+Number()	Returns the number of the Buffer.
+
+							*perl-Buffer-Count*
+Count()		Returns the number of lines in the Buffer.
+
+							*perl-Buffer-Get*
+Get({lnum}, {lnum}?, ...)
+			Returns a text string of line {lnum} in the Buffer
+			for each {lnum} specified.  An array can be passed
+			with a list of {lnum}'s specified.
+
+							*perl-Buffer-Delete*
+Delete({lnum}, {lnum}?)
+			Deletes line {lnum} in the Buffer.  With the second
+			{lnum}, deletes the range of lines from the first
+			{lnum} to the second {lnum}.
+
+							*perl-Buffer-Append*
+Append({lnum}, {line}, {line}?, ...)
+			Appends each {line} string after Buffer line {lnum}.
+			The list of {line}s can be an array.
+
+							*perl-Buffer-Set*
+Set({lnum}, {line}, {line}?, ...)
+			Replaces one or more Buffer lines with specified
+			{lines}s, starting at Buffer line {lnum}.  The list of
+			{line}s can be an array.  If the arguments are
+			invalid, replacement does not occur.
+
+==============================================================================
+4. VIM::Window objects					*perl-window*
+
+Methods:
+							*perl-Window-SetHeight*
+SetHeight({height})
+			Sets the Window height to {height}, within screen
+			limits.
+
+							*perl-Window-GetCursor*
+Cursor({row}?, {col}?)
+			With no arguments, returns a (row, col) array for the
+			current cursor position in the Window.  With {row} and
+			{col} arguments, sets the Window's cursor position to
+			{row} and {col}.  Note that {col} is numbered from 0,
+			Perl-fashion, and thus is one less than the value in
+			Vim's ruler.
+
+Buffer()						*perl-Window-Buffer*
+			Returns the Buffer object corresponding to the given
+			Window.
+
+==============================================================================
+5. Lexical variables					*perl-globals*
+
+There are multiple lexical variables.
+
+$curwin			The current Window object.
+$curbuf			The current Buffer object.
+$vim			A Neovim::Ext object.
+$nvim			The same as $nvim.
+$current		A Neovim::Ext::Current object.
+
+These are also available via the "main" package:
+
+$main::curwin		The current Window object.
+$main::curbuf		The current Buffer object.
 
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 553294e014..c9efd6038e 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -129,9 +129,10 @@ To use the RVM "system" Ruby installation: >
 ==============================================================================
 Perl integration				*provider-perl*
 
-Nvim supports Perl |remote-plugin|s on non-Windows platforms. Support for
-polling STDIN on Windows in lacking from all known event loop implementations
-currently.
+Nvim supports Perl |remote-plugin|s on Unix platforms. Support for polling STDIN
+on MS-Windows is currently lacking from all known event loop implementations.
+The Vim legacy |perl-vim| interface is also supported (which is itself
+implemented as a Nvim remote-plugin).
 https://github.com/jacquesg/p5-Neovim-Ext