if_perl.txt For Vim version 9.1. Last change: 2023 May 14
VIM REFERENCE MANUAL by Sven Verdoolaege
and Matt Gerassimof
Perl and Vim perl Perl
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
{only available when Vim was compiled with the +perl feature}
==============================================================================
1. Editing Perl files perl-editing
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 Universal/Exuberant Ctags. Look here:
Universal Ctags (preferred): https://ctags.io
Exuberant Ctags: 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-compiling
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 (and other platforms) can be found at:
http://www.perl.org/
The ActiveState one should work, Strawberry Perl is a good alternative.
==============================================================================
3. Using the Perl interface perl-using
:perl :pe
:pe[rl] {cmd} Execute Perl command {cmd}. The current package
is "main". Simple example to test if :perl is
working:
:pe[rl] << [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. 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:
To see what version of Perl you have:
:perldo :perld
:[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:
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-overview
Here is an overview of the functions that are available to Perl:
perl-Msg
VIM::Msg({msg}, {group}?)
Displays the message {msg}. The optional {group}
argument specifies a highlight group for Vim to use
for the message.
perl-SetOption
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-Buffers
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-Windows
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-DoCommand
VIM::DoCommand({cmd}) Executes Ex command {cmd}.
perl-Eval
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-Blob
VIM::Blob({expr}) Return Blob literal string 0zXXXX from scalar value.
perl-SetHeight
Window->SetHeight({height})
Sets the Window height to {height}, within screen
limits.
perl-GetCursor
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-Buffer
Returns the Buffer object corresponding to the given
Window.
perl-Name
Buffer->Name() Returns the filename for the Buffer.
perl-Number
Buffer->Number() Returns the number of the Buffer.
perl-Count
Buffer->Count() Returns the number of lines in the Buffer.
perl-Get
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-Delete
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-Append
Buffer->Append({lnum}, {line}, {line}?, ...)
Appends each {line} string after Buffer line {lnum}.
The list of {line}s can be an array.
perl-Set
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-here
When using a script language in-line, you might want to skip this when the
language isn't supported.
space.
==============================================================================
4. Dynamic loading perl-dynamic
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
'perldll' option can be also used to specify the Perl DLL.
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".
Unix
The 'perldll' option can be used to specify the Perl shared library file
instead of DYNAMIC_PERL_DLL file what was specified at compile time. The
version of the shared library must match the Perl version Vim was compiled
with.
Note: If you are building Perl locally, you have to use a version compiled
with threading support for it for Vim to successfully link against it. You can
use the -Dusethreads flags when configuring Perl, and check that a Perl
binary has it enabled by running perl -V and verify that USE_ITHREADS is
under "Compile-time options".
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:
VIM REFERENCE MANUAL by Sven Verdoolaege
and Matt Gerassimof
Perl and Vim perl Perl
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
{only available when Vim was compiled with the +perl feature}
==============================================================================
1. Editing Perl files perl-editing
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 Universal/Exuberant Ctags. Look here:
Universal Ctags (preferred): https://ctags.io
Exuberant Ctags: 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-compiling
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 (and other platforms) can be found at:
http://www.perl.org/
The ActiveState one should work, Strawberry Perl is a good alternative.
==============================================================================
3. Using the Perl interface perl-using
:perl :pe
: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] << [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. 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
perl << EOF
VIM::Msg("pearls are nice for necklaces");
VIM::Msg("rubys for rings");
VIM::Msg("pythons for bags");
VIM::Msg("tcls????");
EOF
endfunction
To see what version of Perl you have:
:perl print $^V
:perldo :perld
:[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)
E299:perldo $_ = reverse($_);1
:perl VIM::Msg("hello")
:perl $line = $curbuf->Get(42)
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-overview
Here is an overview of the functions that are available to Perl:
:perl VIM::Msg("Text") # displays a message
:perl VIM::Msg("Wrong!", "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 VIM::Msg("Wrong!", "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-Msg
VIM::Msg({msg}, {group}?)
Displays the message {msg}. The optional {group}
argument specifies a highlight group for Vim to use
for the message.
perl-SetOption
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-Buffers
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-Windows
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-DoCommand
VIM::DoCommand({cmd}) Executes Ex command {cmd}.
perl-Eval
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-Blob
VIM::Blob({expr}) Return Blob literal string 0zXXXX from scalar value.
perl-SetHeight
Window->SetHeight({height})
Sets the Window height to {height}, within screen
limits.
perl-GetCursor
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-Buffer
Returns the Buffer object corresponding to the given
Window.
perl-Name
Buffer->Name() Returns the filename for the Buffer.
perl-Number
Buffer->Number() Returns the number of the Buffer.
perl-Count
Buffer->Count() Returns the number of lines in the Buffer.
perl-Get
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-Delete
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-Append
Buffer->Append({lnum}, {line}, {line}?, ...)
Appends each {line} string after Buffer line {lnum}.
The list of {line}s can be an array.
perl-Set
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-here
When using a script language in-line, you might want to skip this when the
language isn't supported.
if has('perl')
perl << EOF
print 'perl works'
EOF
endif
Note that "EOF" must be at the start of the line without preceding whiteperl << EOF
print 'perl works'
EOF
endif
space.
==============================================================================
4. Dynamic loading perl-dynamic
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
'perldll' option can be also used to specify the Perl DLL.
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".
Unix
The 'perldll' option can be used to specify the Perl shared library file
instead of DYNAMIC_PERL_DLL file what was specified at compile time. The
version of the shared library must match the Perl version Vim was compiled
with.
Note: If you are building Perl locally, you have to use a version compiled
with threading support for it for Vim to successfully link against it. You can
use the -Dusethreads flags when configuring Perl, and check that a Perl
binary has it enabled by running perl -V and verify that USE_ITHREADS is
under "Compile-time options".
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl: