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

10 files changed, 205 insertions, 6 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*
 
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index be16ddd7f6..372c950825 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -256,6 +256,7 @@ return {
     py3eval={args=1},
     pyeval={args=1},
     pyxeval={args=1},
+    perleval={args=1},
     range={args={1, 3}},
     readdir={args={1, 2}},
     readfile={args={1, 3}},
diff --git a/src/nvim/eval/funcs.c b/src/nvim/eval/funcs.c
index ac560124bf..f4d9db53c4 100644
--- a/src/nvim/eval/funcs.c
+++ b/src/nvim/eval/funcs.c
@@ -6374,6 +6374,14 @@ static void f_pyxeval(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
+///
+/// "perleval()" function
+///
+static void f_perleval(typval_T *argvars, typval_T *rettv, FunPtr fptr)
+{
+  script_host_eval("perl", argvars, rettv);
+}
+
 /*
  * "range()" function
  */
diff --git a/src/nvim/ex_cmds.lua b/src/nvim/ex_cmds.lua
index 252af409c0..a01f92df27 100644
--- a/src/nvim/ex_cmds.lua
+++ b/src/nvim/ex_cmds.lua
@@ -1927,13 +1927,19 @@ return {
     command='perl',
     flags=bit.bor(RANGE, EXTRA, DFLALL, NEEDARG, SBOXOK, CMDWIN, RESTRICT),
     addr_type=ADDR_LINES,
-    func='ex_script_ni',
+    func='ex_perl',
   },
   {
     command='perldo',
     flags=bit.bor(RANGE, EXTRA, DFLALL, NEEDARG, CMDWIN, RESTRICT),
     addr_type=ADDR_LINES,
-    func='ex_ni',
+    func='ex_perldo',
+  },
+  {
+    command='perlfile',
+    flags=bit.bor(RANGE, FILE1, NEEDARG, CMDWIN, RESTRICT),
+    addr_type=ADDR_LINES,
+    func='ex_perlfile',
   },
   {
     command='pedit',
diff --git a/src/nvim/ex_cmds2.c b/src/nvim/ex_cmds2.c
index 7a06cb7ca6..0603bd4148 100644
--- a/src/nvim/ex_cmds2.c
+++ b/src/nvim/ex_cmds2.c
@@ -935,6 +935,21 @@ void ex_pydo3(exarg_T *eap)
   script_host_do_range("python3", eap);
 }
 
+void ex_perl(exarg_T *eap)
+{
+  script_host_execute("perl", eap);
+}
+
+void ex_perlfile(exarg_T *eap)
+{
+  script_host_execute_file("perl", eap);
+}
+
+void ex_perldo(exarg_T *eap)
+{
+  script_host_do_range("perl", eap);
+}
+
 // Command line expansion for :profile.
 static enum {
   PEXP_SUBCMD,          ///< expand :profile sub-commands
diff --git a/test/functional/provider/perl_spec.lua b/test/functional/provider/perl_spec.lua
index 7b446e4ab3..125674660b 100644
--- a/test/functional/provider/perl_spec.lua
+++ b/test/functional/provider/perl_spec.lua
@@ -5,6 +5,10 @@ local command = helpers.command
 local write_file = helpers.write_file
 local eval = helpers.eval
 local retry = helpers.retry
+local curbufmeths = helpers.curbufmeths
+local insert = helpers.insert
+local expect = helpers.expect
+local feed = helpers.feed
 
 do
   clear()
@@ -19,7 +23,51 @@ before_each(function()
   clear()
 end)
 
-describe('perl host', function()
+describe('legacy perl provider', function()
+  if helpers.pending_win32(pending) then return end
+
+  it('feature test', function()
+    eq(1, eval('has("perl")'))
+  end)
+
+  it(':perl command', function()
+    command('perl $vim->vars->{set_by_perl} = [100, 0];')
+    eq({100, 0}, eval('g:set_by_perl'))
+  end)
+
+  it(':perlfile command', function()
+    local fname = 'perlfile.pl'
+    write_file(fname, '$vim->command("let set_by_perlfile = 123")')
+    command('perlfile perlfile.pl')
+    eq(123, eval('g:set_by_perlfile'))
+    os.remove(fname)
+  end)
+
+  it(':perldo command', function()
+    -- :perldo 1; doesn't change $_,
+    -- the buffer should not be changed
+    command('normal :perldo 1;')
+    eq(false, curbufmeths.get_option('modified'))
+    -- insert some text
+    insert('abc\ndef\nghi')
+    expect([[
+      abc
+      def
+      ghi]])
+    -- go to top and select and replace the first two lines
+    feed('ggvj:perldo $_ = reverse ($_)."$linenr"<CR>')
+    expect([[
+      cba1
+      fed2
+      ghi]])
+  end)
+
+  it('perleval()', function()
+    eq({1, 2, {['key'] = 'val'}}, eval([[perleval('[1, 2, {"key" => "val"}]')]]))
+  end)
+end)
+
+describe('perl provider', function()
   if helpers.pending_win32(pending) then return end
   teardown(function ()
     os.remove('Xtest-perl-hello.pl')