if_perl.txt For Vim version 7.4. Last change: 2013 Oct 05LINK

VIM REFERENCE MANUAL by Sven Verdoolaege

and Matt Gerassimof

Perl and Vim perl PerlLINK

1. Editing Perl files perl-editing

2. Compiling VIM with Perl interface perl-compiling

3. Using the Perl interface perl-using

4. Dynamic loading perl-dynamic

{Vi does not have any of these commands}

The Perl interface only works when Vim was compiled with the +perl feature.

==============================================================================

1. Editing Perl files perl-editingLINK

Vim syntax highlighting supports Perl and POD files. Vim assumes a file is

Perl code if the filename has a .pl or .pm suffix. Vim also examines the first

line of a file, regardless of the filename suffix, to check if a file is a

Perl script (see scripts.vim in Vim's syntax directory). Vim assumes a file

is POD text if the filename has a .POD suffix.

To use tags with Perl, you need a recent version of Exuberant ctags. Look

here:

http://ctags.sourceforge.net

Alternatively, you can use the Perl script pltags.pl, which is shipped with

Vim in the $VIMRUNTIME/tools directory. This script has currently more

features than Exuberant ctags' Perl support.

==============================================================================

2. Compiling VIM with Perl interface perl-compilingLINK

To compile Vim with Perl interface, you need Perl 5.004 (or later). Perl must

be installed before you compile Vim. Vim's Perl interface does NOT work with

the 5.003 version that has been officially released! It will probably work

with Perl 5.003_05 and later.

The Perl patches for Vim were made by:

Sven Verdoolaege <skimo@breughel.ufsia.ac.be>

Matt Gerassimof

Perl for MS-Windows can be found at: http://www.perl.com/

The ActiveState one should work.

==============================================================================

3. Using the Perl interface perl-usingLINK

:perl :peLINK

:pe[rl] {cmd} Execute Perl command {cmd}. The current package

is "main". Simple example to test if :perl is

working:

:perl VIM::Msg("Hello")

:pe[rl] << {endpattern}

{script}

{endpattern}

Execute Perl script {script}.

{endpattern} must NOT be preceded by any white space.

If {endpattern} is omitted, it defaults to a dot '.'

like for the :append and :insert commands. Using

'.' helps when inside a function, because "$i;" looks

like the start of an :insert command to Vim.

This form of the :perl command is mainly useful for

including perl code in vim scripts.

Note: This command doesn't work when the Perl feature

wasn't compiled in. To avoid errors, see

script-here.

Example vim script:

function! WhitePearl()

perl << EOF

VIM::Msg("pearls are nice for necklaces");

VIM::Msg("rubys for rings");

VIM::Msg("pythons for bags");

VIM::Msg("tcls????");

EOF

endfunction

:perldo :perldLINK

:[range]perld[o] {cmd} Execute Perl command {cmd} for each line in the

[range], with $_ being set to the text of each line in

turn, without a trailing <EOL>. 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,$".

Here are some things you can try:

:perl $a=1

:perldo $_ = reverse($_);1

:perl VIM::Msg("hello")

:perl $line = $curbuf->Get(42)

E299LINK

Executing Perl commands in the sandbox is limited. ":perldo" will not be

possible at all. ":perl" will be evaluated in the Safe environment, if

possible.

perl-overviewLINK

Here is an overview of the functions that are available to Perl:

:perl VIM::Msg("Text") # displays a message

:perl VIM::Msg("Error", "ErrorMsg") # displays an error message

:perl VIM::Msg("remark", "Comment") # displays a highlighted message

:perl VIM::SetOption("ai") # sets a vim option

:perl $nbuf = VIM::Buffers() # returns the number of buffers

:perl @buflist = VIM::Buffers() # returns array of all buffers

:perl $mybuf = (VIM::Buffers('qq.c'))[0] # returns buffer object for 'qq.c'

:perl @winlist = VIM::Windows() # returns array of all windows

:perl $nwin = VIM::Windows() # returns the number of windows

:perl ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1

:perl ($success, $v) = VIM::Eval('&xyz') # $v: '' and $success: 0

:perl $v = VIM::Eval('expand("<cfile>")') # expands <cfile>

:perl $curwin->SetHeight(10) # sets the window height

:perl @pos = $curwin->Cursor() # returns (row, col) array

:perl @pos = (10, 10)

:perl $curwin->Cursor(@pos) # sets cursor to @pos

:perl $curwin->Cursor(10,10) # sets cursor to row 10 col 10

:perl $mybuf = $curwin->Buffer() # returns the buffer object for window

:perl $curbuf->Name() # returns buffer name

:perl $curbuf->Number() # returns buffer number

:perl $curbuf->Count() # returns the number of lines

:perl $l = $curbuf->Get(10) # returns line 10

:perl @l = $curbuf->Get(1 .. 5) # returns lines 1 through 5

:perl $curbuf->Delete(10) # deletes line 10

:perl $curbuf->Delete(10, 20) # delete lines 10 through 20

:perl $curbuf->Append(10, "Line") # appends a line

:perl $curbuf->Append(10, "Line1", "Line2", "Line3") # appends 3 lines

:perl @l = ("L1", "L2", "L3")

:perl $curbuf->Append(10, @l) # appends L1, L2 and L3

:perl $curbuf->Set(10, "Line") # replaces line 10

:perl $curbuf->Set(10, "Line1", "Line2") # replaces lines 10 and 11

:perl $curbuf->Set(10, @l) # replaces 3 lines

perl-MsgLINK

VIM::Msg({msg}, {group}?)

Displays the message {msg}. The optional {group}

argument specifies a highlight group for Vim to use

for the message.

perl-SetOptionLINK

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-BuffersLINK

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. Using it anyway may crash Vim.

perl-WindowsLINK

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. Using it anyway may crash Vim.

perl-DoCommandLINK

VIM::DoCommand({cmd}) Executes Ex command {cmd}.

perl-EvalLINK

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.

perl-SetHeightLINK

Window->SetHeight({height})

Sets the Window height to {height}, within screen

limits.

perl-GetCursorLINK

Window->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.

Window->Buffer() perl-BufferLINK

Returns the Buffer object corresponding to the given

Window.

perl-NameLINK

Buffer->Name() Returns the filename for the Buffer.

perl-NumberLINK

Buffer->Number() Returns the number of the Buffer.

perl-CountLINK

Buffer->Count() Returns the number of lines in the Buffer.

perl-GetLINK

Buffer->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-DeleteLINK

Buffer->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-AppendLINK

Buffer->Append({lnum}, {line}, {line}?, ...)

Appends each {line} string after Buffer line {lnum}.

The list of {line}s can be an array.

perl-SetLINK

Buffer->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.

$main::curwin

The current window object.

$main::curbuf

The current buffer object.

script-hereLINK

When using a script language in-line, you might want to skip this when the

language isn't supported. But this mechanism doesn't work:

if has('perl')

perl << EOF

this will NOT work!

EOF

endif

Instead, put the Perl/Python/Ruby/etc. command in a function and call that

function:

if has('perl')

function DefPerl()

perl << EOF

this works

EOF

endfunction

call DefPerl()

endif

Note that "EOF" must be at the start of the line.

==============================================================================

4. Dynamic loading perl-dynamicLINK

On MS-Windows and Unix the Perl library can be loaded dynamically. The

:version output then includes +perl/dyn.

This means that Vim will search for the Perl DLL or shared library file only

when needed. When you don't use the Perl interface you don't need it, thus

you can use Vim without this file.

MS-Windows

You can download Perl from http://www.perl.org. The one from ActiveState was

used for building Vim.

To use the Perl interface the Perl DLL must be in your search path.

If Vim reports it cannot find the perl512.dll, make sure your $PATH includes

the directory where it is located. The Perl installer normally does that.

In a console window type "path" to see what directories are used.

The name of the DLL must match the Perl version Vim was compiled with.

Currently the name is "perl512.dll". That is for Perl 5.12. To know for

sure edit "gvim.exe" and search for "perl\d*.dll\c".

==============================================================================

vim:tw=78:ts=8:ft=help:norl: