support for :perl, :perlfile, :perldo and perleval()

5 files changed, 124 insertions, 3 deletions

diff --git a/runtime/autoload/provider/perl.vim b/runtime/autoload/provider/perl.vim
index 36ca2bbf14..8f9fae3c41 100644
--- a/runtime/autoload/provider/perl.vim
+++ b/runtime/autoload/provider/perl.vim
@@ -46,7 +46,7 @@ function! provider#perl#Call(method, args) abort
 
   if !exists('s:host')
     try
-      let s:host = remote#host#Require('perl')
+      let s:host = remote#host#Require('legacy-perl-provider')
     catch
       let s:err = v:exception
       echohl WarningMsg
@@ -66,4 +66,9 @@ if g:loaded_perl_provider != 2
   let s:err = 'Cannot find perl or the required perl module'
 endif
 
-call remote#host#RegisterPlugin('perl-provider', 'perl', [])
+
+" The perl provider plugin will run in a separate instance of the perl
+" host.
+call remote#host#RegisterClone('legacy-perl-provider', 'perl')
+call remote#host#RegisterPlugin('legacy-perl-provider', 'ScriptHost.pm', [])
+
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index b31177ce0e..163dc81804 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -556,6 +556,7 @@ followed by another Vim command:
     :lfdo
     :make
     :normal
+    :perlfile
     :promptfind
     :promptrepl
     :pyfile
diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt
new file mode 100644
index 0000000000..aa13df6035
--- /dev/null
+++ b/runtime/doc/if_perl.txt
@@ -0,0 +1,113 @@
+*if_perl.txt*   Nvim
+
+
+		  VIM REFERENCE MANUAL    by Jacques Germishuys
+
+The perl Interface to Vim				*if_perl* *perl*
+
+See |provider-perl| for more information.
+
+                                      Type |gO| to see the table of contents.
+
+==============================================================================
+1. Commands						*perl-commands*
+
+							*:perl*
+:[range]perl {stmt}
+			Execute perl statement {stmt}.  The current package is
+			"main".  A simple check if the `:perl` command is
+			working: >
+				:perl print "Hello"
+
+:[range]perl << [endmarker]
+{script}
+{endmarker}
+			Execute perl script {script}.  Useful for including
+			perl code in Vim scripts.  Requires perl, see
+			|script-here|.
+
+The {endmarker} below the {script} must NOT be preceded by any white space.
+
+If [endmarker] is omitted from after the "<<", a dot '.' must be used after
+{script}, like for the |:append| and |:insert| commands.
+
+Example: >
+	function! MyVimMethod()
+	perl << EOF
+	sub my_vim_method
+	{
+		print "Hello World!\n";
+	}
+	EOF
+	endfunction
+
+To see what version of perl you have: >
+
+	:perl print $^V
+<
+							*:perldo*
+:[range]perldo {cmd}	Execute perl command {cmd} for each line in the[range],
+			with $_ being set to the test of each line in turn,
+			without a trailing <EOL>. In addition to $_, $line and
+			$linenr is also set to the line content and line number
+			respectively. Setting $_ will change the text, but note
+			that it is not possible to add or delete lines using
+			this command.
+			The default for [range] is the whole file: "1,$".
+
+Examples:
+>
+	:perldo $_ = reverse($_);
+	:perldo $_ = "".$linenr." => $line";
+
+One can use `:perldo` in conjunction with `:perl` to filter a range using
+perl. For example: >
+
+	:perl << EOF
+	sub perl_vim_string_replace
+	{
+	    my $line = shift;
+	    my $needle = $vim->eval('@a');
+	    my $replacement = $vim->eval('@b');
+	    $line =~ s/$needle/$replacement/g;
+	    return $line;
+	}
+	EOF
+	:let @a='somevalue'
+	:let @b='newvalue'
+	:'<,'>perldo $_ = perl_vim_string_replace($_)
+<
+							*:perlfile*
+:[range]perlfile {file}
+			Execute the perl script in {file}.  The whole
+			argument is used as a single file name.
+
+Both of these commands do essentially the same thing - they execute a piece of
+perl code, with the "current range" set to the given line range.
+
+In the case of :perl, the code to execute is in the command-line.
+In the case of :perlfile, the code to execute is the contents of the given file.
+
+perl commands cannot be used in the |sandbox|.
+
+To pass arguments you need to set @ARGV explicitly.  Example: >
+
+	:perl @ARGV = ("foo", "bar");
+	:perlfile myscript.pl
+
+Here are some examples					*perl-examples*  >
+
+	:perl print "Hello"
+	:perl $current->line (uc ($current->line))
+	:perl my $str = $current->buffer->[42]; print "Set \$str to: $str"
+
+Note that changes (such as the "use" statements) persist from one command
+to the next.
+
+==============================================================================
+2. The VIM module					*perl-vim*
+
+Note: Perl codes does not currently have access to the legacy "VIM" package.
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index bdab10c0e4..afcacad460 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -1441,6 +1441,9 @@ tag		command		action ~
 |:packloadall|	:packl[oadall]	load all packages under 'packpath'
 |:pclose|	:pc[lose]	close preview window
 |:pedit|	:ped[it]	edit file in the preview window
+|:perl|		:perl		execute perl command
+|:perldo|	:perldo		execute perl command for each line
+|:perfile|	:perlfile	execute perl script file
 |:print|	:p[rint]	print lines
 |:profdel|	:profd[el]	stop profiling a function or script
 |:profile|	:prof[ile]	profiling functions and scripts
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index a7e040bc93..eab4a02e02 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -407,7 +407,6 @@ Some legacy Vim features are not implemented:
 
 - |if_lua|: Nvim Lua API is not compatible with Vim's "if_lua"
 - *if_mzscheme*
-- *if_perl*
 - |if_py|: *python-bindeval* *python-Function* are not supported
 - *if_tcl*