The perl Interface to Vim if_perl perl

See provider-perl for more information.

1. Commands perl-commands

Execute perl statement {stmt}. The current package is "main". A simple check if the :perl command is working:

:perl print "Hello"

:[range]perl << [trim] [{endmarker}] {script} {endmarker} Execute perl script {script}. The {endmarker} after {script} must NOT be preceded by any white space.

If [endmarker] is omitted, it defaults to a dot '.' like for the :append and :insert commands.

Useful for including perl code in Vim scripts. Requires perl, see script-here.

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

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($_)

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

Perl code gets all of its access to Nvim 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:

Displays the message {msg}.

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.

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.

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.

Executes Ex command {cmd}.

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.

Return Blob literal string 0zXXXX from scalar value.

3. VIM::Buffer objects perl-buffer

Methods:

Returns the filename for the Buffer.

Returns the number of the Buffer.

Returns the number of lines in the Buffer.

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.

Deletes line {lnum} in the Buffer. With the second {lnum}, deletes the range of lines from the first {lnum} to the second {lnum}.

Appends each {line} string after Buffer line {lnum}. The list of {line}s can be an array.

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: Sets the Window height to {height}, within screen limits.

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.

Returns the Buffer object corresponding to the given Window.

5. Lexical variables perl-globals

There are multiple lexical variables.

These are also available via the "main" package: