forked from aniani/vim
6c2b7b8055
Problem: Heredoc for interfaces does not support "trim".
Solution: Update the script heredoc support to be same as the :let command.
(Yegappan Lakshmanan, closes #5916)
312 lines
11 KiB
Plaintext
312 lines
11 KiB
Plaintext
*if_perl.txt* For Vim version 8.2. Last change: 2019 Dec 07
|
|
|
|
|
|
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 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-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
|
|
<
|
|
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*
|
|
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-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. 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-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.
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|