# Vim documentation: if_perl

main help file

    *if_perl.txt*	For Vim version 9.2.  Last change: 2026 Feb 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
    shebang line of a file, if no filetype has been detected, to check if a file
    is a Perl script.  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 the Perl interface, you need a recent Perl version.  Perl
    must be installed before you compile Vim.

    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.
       if has('perl')
         perl << EOF
           print 'perl works'
       EOF
       endif
    Note that "EOF" must be at the start of the line without preceding white
    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".

    ==============================================================================
    top - main help file