if_perl.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Sven Verdoolaege and Matt GerassimofPerl and VimperlPerl1. EditingPerl filesperl-editing2. Compiling Vim withPerlinterfaceperl-compiling3. Using thePerlinterfaceperl-using4. Dynamic loadingperl-dynamic{only available when Vim was compiled with the |+perl| feature}==============================================================================1. EditingPerl filesperl-editingVimsyntax highlighting supportsPerl and POD files. Vim assumesa fileisPerl code if the filename hasa .pl or .pm suffix. Vim also examines theshebang line ofa file, if nofiletype has been detected, to check ifa fileisaPerl script. Vim assumesa fileis POD text if the filename hasa .PODsuffix.To usetags with Perl, you need Universal/Exuberant Ctags. Look here:Universal Ctags (preferred):https://ctags.ioExuberant Ctags:http://ctags.sourceforge.netAlternatively, you can use thePerlscript pltags.pl, whichis shipped withVim in the $VIMRUNTIME/tools directory. Thisscript has currently morefeatures than Exuberant ctags'Perl support.==============================================================================2. Compiling Vim withPerlinterfaceperl-compilingTo compile Vim with thePerl interface, you needa recentPerl version.Perlmust be installed before you compile Vim.ThePerl patches for Vim were made by:Sven Verdoolaege <skimo@breughel.ufsia.ac.be>Matt GerassimofPerl forMS-Windows (and other platforms) can be found at:http://www.perl.org/The ActiveState one should work, StrawberryPerlisa good alternative.==============================================================================3. Using thePerlinterfaceperl-using:perl:pe:pe[rl]{cmd}ExecutePerl command{cmd}. The current packageis "main". Simple example to test if:perlisworking::perl VIM::Msg("Hello"):pe[rl]<<[trim] [{endmarker}]{script}{endmarker}ExecutePerlscript{script}.The{endmarker} after{script}must NOT be preceded byany white space.If[endmarker]is omitted,it defaults toa dot '.'like for the:append and:insert commands. Using'.' helps when insidea function, because "$i;" lookslike the start of an:insert command to Vim.This form of the:perl commandis mainly useful forincludingperl code in vim scripts.Note: This command doesn't work when thePerl featurewasn't compiled in. To avoid errors, seescript-here.Example Vim script:function! WhitePearl()perl << EOFVIM::Msg("pearls are nice for necklaces");VIM::Msg("rubys for rings");VIM::Msg("pythons for bags");VIM::Msg("tcls????");EOFendfunctionTo see what version ofPerl you have::perl print $^V:perldo:perld:[range]perld[o]{cmd}ExecutePerl command{cmd} for each line in the[range], with $_ being set to the text of each line inturn, withouta trailing<EOL>. Setting $_ willchange the text, butnote thatitis not possible toadd 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)E299ExecutingPerl commands in thesandboxis limited. ":perldo" will not bepossibleat all. ":perl" will be evaluated in the Safe environment, ifpossible.perl-overviewHereis an overview of thefunctions 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 linesperl-MsgVIM::Msg({msg},{group}?)Displays the message{msg}. The optional{group}argumentspecifiesa highlight group for Vim to usefor the message.perl-SetOptionVIM::SetOption({arg})Setsa vim option.{arg} can be any argument that the":set" command accepts.Note that this means that nospaces are allowed in the argument! See:set.perl-BuffersVIM::Buffers([{bn}...])With no arguments, returnsalist of all thebuffersin an array context or returns the number ofbuffersina scalar context. Foralist of buffer names ornumbers{bn}, returnsalist of thebuffers matching{bn}, using the same rulesas Vim's internalbufname() function.WARNING: thelist becomes invalid when:bwipeisused. Usingit anyway may crash Vim.perl-WindowsVIM::Windows([{wn}...])With no arguments, returnsalist of all thewindowsin an array context or returns the number ofwindowsina scalar context. Foralist ofwindow numbers{wn}, returnsalist of thewindows with thosenumbers.WARNING: thelist becomes invalid whenawindowisclosed. Usingit anyway may crash Vim.perl-DoCommandVIM::DoCommand({cmd})ExecutesEx command{cmd}.perl-EvalVIM::Eval({expr})Evaluates{expr} and returns (success, value) inlistcontext or just value in scalar context.success=1 indicates that val contains the value of{expr}; success=0 indicatesa failure to evaluatethe expression. '@x' returns the contents of registerx, '&x' returns the value of option x, 'x' returns thevalue of internalvariables x, and '$x'is equivalentto perl's $ENV{x}. Allfunctions accessible fromthe command-line are valid for{expr}.AListis turned intoastring by joining the itemsandinserting line breaks.perl-BlobVIM::Blob({expr})ReturnBlob literalstring 0zXXXX from scalar value.perl-SetHeightWindow->SetHeight({height})Sets the Window height to{height}, within screenlimits.perl-GetCursorWindow->Cursor({row}?,{col}?)With no arguments, returnsa (row, col) array for thecurrent 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 thusis oneless than the value inVim's ruler.Window->Buffer()perl-BufferReturns the Bufferobject corresponding to the givenWindow.perl-NameBuffer->Name()Returns the filename for the Buffer.perl-NumberBuffer->Number()Returns the number of the Buffer.perl-CountBuffer->Count()Returns the number of lines in the Buffer.perl-GetBuffer->Get({lnum},{lnum}?, ...)Returnsa textstring of line{lnum} in the Bufferfor each{lnum} specified. An array can be passedwithalist of{lnum}'s specified.perl-DeleteBuffer->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-AppendBuffer->Append({lnum},{line},{line}?, ...)Appends each{line}string after Buffer line{lnum}.Thelist of{line}s can be an array.perl-SetBuffer->Set({lnum},{line},{line}?, ...)Replaces one or more Buffer lines with specified{lines}s,startingat Buffer line{lnum}. Thelist of{line}s can be an array. If the arguments areinvalid, replacement does not occur.$main::curwinThe currentwindow object.$main::curbufThe current buffer object.script-hereWhen usingascript language in-line, you might want to skip this when thelanguage isn't supported. if has('perl') perl << EOF print 'perl works' EOF endifNote that "EOF"must beat the start of the line without preceding whitespace.==============================================================================4. Dynamic loadingperl-dynamicOnMS-Windows andUnix thePerl library can be loaded dynamically. The:version output then includes+perl/dyn.This means that Vim will search for thePerl DLL or shared library file onlywhen needed. When you don't use thePerlinterface you don't need it, thusyou can use Vim without this file.MS-WindowsYou candownloadPerl fromhttp://www.perl.org. The one from ActiveState wasused for building Vim.To use thePerlinterface thePerl DLLmust be in your search path.If Vim reportsit cannot find the perl512.dll, make sure your $PATH includesthe directory whereitis located. ThePerl installer normally does that.Ina consolewindow type "path" to see what directories are used. The'perldll' option can be also used to specify thePerl DLL.The name of the DLLmust match thePerl version Vim was compiled with.Currently the nameis "perl512.dll". Thatis forPerl 5.12. To know forsure edit "gvim.exe" and search for "perl\d*.dll\c".UnixThe'perldll' option can be used to specify thePerl shared library fileinstead of DYNAMIC_PERL_DLL file what was specifiedat compile time. Theversion of the shared librarymust match thePerl version Vim was compiledwith.Note: If you are buildingPerl locally, you have to usea version compiledwith threading support forit for Vim to successfully link against it. Youcan use the-Dusethreads flags when configuring Perl, and check thataPerlbinary hasit enabled by running `perl -V` and verify thatUSE_ITHREADSisunder "Compile-timeoptions".============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: