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

1 files changed, 113 insertions, 0 deletions

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: