vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

if_perl.txt (11265B)


      1 *if_perl.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Sven Verdoolaege
      5 					  and Matt Gerassimof
      6 
      7 
      8 Perl and Vim				*perl* *Perl*
      9 
     10 1. Editing Perl files			|perl-editing|
     11 2. Compiling Vim with Perl interface	|perl-compiling|
     12 3. Using the Perl interface		|perl-using|
     13 4. Dynamic loading			|perl-dynamic|
     14 
     15 {only available when Vim was compiled with the |+perl| feature}
     16 
     17 ==============================================================================
     18 1. Editing Perl files					*perl-editing*
     19 
     20 Vim syntax highlighting supports Perl and POD files.  Vim assumes a file is
     21 Perl code if the filename has a .pl or .pm suffix.  Vim also examines the
     22 shebang line of a file, if no filetype has been detected, to check if a file
     23 is a Perl script.  Vim assumes a file is POD text if the filename has a .POD
     24 suffix.
     25 
     26 To use tags with Perl, you need Universal/Exuberant Ctags.  Look here:
     27 	Universal Ctags (preferred): https://ctags.io
     28 	Exuberant Ctags: http://ctags.sourceforge.net
     29 
     30 Alternatively, you can use the Perl script pltags.pl, which is shipped with
     31 Vim in the $VIMRUNTIME/tools directory.  This script has currently more
     32 features than Exuberant ctags' Perl support.
     33 
     34 ==============================================================================
     35 2. Compiling Vim with Perl interface			*perl-compiling*
     36 
     37 To compile Vim with the Perl interface, you need a recent Perl version.  Perl
     38 must be installed before you compile Vim.
     39 
     40 The Perl patches for Vim were made by:
     41 	Sven Verdoolaege <skimo@breughel.ufsia.ac.be>
     42 	Matt Gerassimof
     43 
     44 Perl for MS-Windows (and other platforms) can be found at:
     45 	http://www.perl.org/
     46 The ActiveState one should work, Strawberry Perl is a good alternative.
     47 
     48 ==============================================================================
     49 3. Using the Perl interface				*perl-using*
     50 
     51 							*:perl* *:pe*
     52 :pe[rl] {cmd}		Execute Perl command {cmd}.  The current package
     53 			is "main".  Simple example to test if `:perl` is
     54 			working: >
     55 				:perl VIM::Msg("Hello")
     56 
     57 :pe[rl] << [trim] [{endmarker}]
     58 {script}
     59 {endmarker}
     60 			Execute Perl script {script}.
     61 			The {endmarker} after {script} must NOT be preceded by
     62 			any white space.
     63 
     64 			If [endmarker] is omitted, it defaults to a dot '.'
     65 			like for the |:append| and |:insert| commands.  Using
     66 			'.' helps when inside a function, because "$i;" looks
     67 			like the start of an |:insert| command to Vim.
     68 
     69 			This form of the |:perl| command is mainly useful for
     70 			including perl code in vim scripts.
     71 			Note: This command doesn't work when the Perl feature
     72 			wasn't compiled in.  To avoid errors, see
     73 			|script-here|.
     74 
     75 
     76 Example Vim script: >
     77 
     78 	function! WhitePearl()
     79 	perl << EOF
     80 		VIM::Msg("pearls are nice for necklaces");
     81 		VIM::Msg("rubys for rings");
     82 		VIM::Msg("pythons for bags");
     83 		VIM::Msg("tcls????");
     84 	EOF
     85 	endfunction
     86 <
     87 To see what version of Perl you have: >
     88 	:perl print $^V
     89 <
     90 
     91 							*:perldo* *:perld*
     92 :[range]perld[o] {cmd}	Execute Perl command {cmd} for each line in the
     93 			[range], with $_ being set to the text of each line in
     94 			turn, without a trailing <EOL>.  Setting $_ will
     95 			change the text, but note that it is not possible to
     96 			add or delete lines using this command.
     97 			The default for [range] is the whole file: "1,$".
     98 
     99 Here are some things you can try: >
    100 
    101   :perl $a=1
    102   :perldo $_ = reverse($_);1
    103   :perl VIM::Msg("hello")
    104   :perl $line = $curbuf->Get(42)
    105 <							*E299*
    106 Executing Perl commands in the |sandbox| is limited.  ":perldo" will not be
    107 possible at all.  ":perl" will be evaluated in the Safe environment, if
    108 possible.
    109 
    110 
    111 							*perl-overview*
    112 Here is an overview of the functions that are available to Perl: >
    113 
    114   :perl VIM::Msg("Text")		# displays a message
    115   :perl VIM::Msg("Wrong!", "ErrorMsg")	# displays an error message
    116   :perl VIM::Msg("remark", "Comment")	# displays a highlighted message
    117   :perl VIM::SetOption("ai")		# sets a vim option
    118   :perl $nbuf = VIM::Buffers()		# returns the number of buffers
    119   :perl @buflist = VIM::Buffers()	# returns array of all buffers
    120   :perl $mybuf = (VIM::Buffers('qq.c'))[0] # returns buffer object for 'qq.c'
    121   :perl @winlist = VIM::Windows()	# returns array of all windows
    122   :perl $nwin = VIM::Windows()		# returns the number of windows
    123   :perl ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1
    124   :perl ($success, $v) = VIM::Eval('&xyz')  # $v: '' and $success: 0
    125   :perl $v = VIM::Eval('expand("<cfile>")') # expands <cfile>
    126   :perl $curwin->SetHeight(10)		# sets the window height
    127   :perl @pos = $curwin->Cursor()	# returns (row, col) array
    128   :perl @pos = (10, 10)
    129   :perl $curwin->Cursor(@pos)		# sets cursor to @pos
    130   :perl $curwin->Cursor(10,10)		# sets cursor to row 10 col 10
    131   :perl $mybuf = $curwin->Buffer()	# returns the buffer object for window
    132   :perl $curbuf->Name()			# returns buffer name
    133   :perl $curbuf->Number()		# returns buffer number
    134   :perl $curbuf->Count()		# returns the number of lines
    135   :perl $l = $curbuf->Get(10)		# returns line 10
    136   :perl @l = $curbuf->Get(1 .. 5)	# returns lines 1 through 5
    137   :perl $curbuf->Delete(10)		# deletes line 10
    138   :perl $curbuf->Delete(10, 20)		# delete lines 10 through 20
    139   :perl $curbuf->Append(10, "Line")	# appends a line
    140   :perl $curbuf->Append(10, "Line1", "Line2", "Line3") # appends 3 lines
    141   :perl @l = ("L1", "L2", "L3")
    142   :perl $curbuf->Append(10, @l)		# appends L1, L2 and L3
    143   :perl $curbuf->Set(10, "Line")	# replaces line 10
    144   :perl $curbuf->Set(10, "Line1", "Line2")	# replaces lines 10 and 11
    145   :perl $curbuf->Set(10, @l)		# replaces 3 lines
    146 <
    147 							*perl-Msg*
    148 VIM::Msg({msg}, {group}?)
    149 			Displays the message {msg}.  The optional {group}
    150 			argument specifies a highlight group for Vim to use
    151 			for the message.
    152 
    153 							*perl-SetOption*
    154 VIM::SetOption({arg})	Sets a vim option.  {arg} can be any argument that the
    155 			":set" command accepts.  Note that this means that no
    156 			spaces are allowed in the argument!  See |:set|.
    157 
    158 							*perl-Buffers*
    159 VIM::Buffers([{bn}...])	With no arguments, returns a list of all the buffers
    160 			in an array context or returns the number of buffers
    161 			in a scalar context.  For a list of buffer names or
    162 			numbers {bn}, returns a list of the buffers matching
    163 			{bn}, using the same rules as Vim's internal
    164 			|bufname()| function.
    165 			WARNING: the list becomes invalid when |:bwipe| is
    166 			used.  Using it anyway may crash Vim.
    167 
    168 							*perl-Windows*
    169 VIM::Windows([{wn}...])	With no arguments, returns a list of all the windows
    170 			in an array context or returns the number of windows
    171 			in a scalar context.  For a list of window numbers
    172 			{wn}, returns a list of the windows with those
    173 			numbers.
    174 			WARNING: the list becomes invalid when a window is
    175 			closed.  Using it anyway may crash Vim.
    176 
    177 							*perl-DoCommand*
    178 VIM::DoCommand({cmd})	Executes Ex command {cmd}.
    179 
    180 							*perl-Eval*
    181 VIM::Eval({expr})	Evaluates {expr} and returns (success, value) in list
    182 			context or just value in scalar context.
    183 			success=1 indicates that val contains the value of
    184 			{expr}; success=0 indicates a failure to evaluate
    185 			the expression.  '@x' returns the contents of register
    186 			x, '&x' returns the value of option x, 'x' returns the
    187 			value of internal |variables| x, and '$x' is equivalent
    188 			to perl's $ENV{x}.  All |functions| accessible from
    189 			the command-line are valid for {expr}.
    190 			A |List| is turned into a string by joining the items
    191 			and inserting line breaks.
    192 
    193 							*perl-Blob*
    194 VIM::Blob({expr})	Return |Blob| literal string 0zXXXX from scalar value.
    195 
    196 							*perl-SetHeight*
    197 Window->SetHeight({height})
    198 			Sets the Window height to {height}, within screen
    199 			limits.
    200 
    201 							*perl-GetCursor*
    202 Window->Cursor({row}?, {col}?)
    203 			With no arguments, returns a (row, col) array for the
    204 			current cursor position in the Window.  With {row} and
    205 			{col} arguments, sets the Window's cursor position to
    206 			{row} and {col}.  Note that {col} is numbered from 0,
    207 			Perl-fashion, and thus is one less than the value in
    208 			Vim's ruler.
    209 
    210 Window->Buffer()					*perl-Buffer*
    211 			Returns the Buffer object corresponding to the given
    212 			Window.
    213 
    214 							*perl-Name*
    215 Buffer->Name()		Returns the filename for the Buffer.
    216 
    217 							*perl-Number*
    218 Buffer->Number()	Returns the number of the Buffer.
    219 
    220 							*perl-Count*
    221 Buffer->Count()		Returns the number of lines in the Buffer.
    222 
    223 							*perl-Get*
    224 Buffer->Get({lnum}, {lnum}?, ...)
    225 			Returns a text string of line {lnum} in the Buffer
    226 			for each {lnum} specified.  An array can be passed
    227 			with a list of {lnum}'s specified.
    228 
    229 							*perl-Delete*
    230 Buffer->Delete({lnum}, {lnum}?)
    231 			Deletes line {lnum} in the Buffer.  With the second
    232 			{lnum}, deletes the range of lines from the first
    233 			{lnum} to the second {lnum}.
    234 
    235 							*perl-Append*
    236 Buffer->Append({lnum}, {line}, {line}?, ...)
    237 			Appends each {line} string after Buffer line {lnum}.
    238 			The list of {line}s can be an array.
    239 
    240 							*perl-Set*
    241 Buffer->Set({lnum}, {line}, {line}?, ...)
    242 			Replaces one or more Buffer lines with specified
    243 			{lines}s, starting at Buffer line {lnum}.  The list of
    244 			{line}s can be an array.  If the arguments are
    245 			invalid, replacement does not occur.
    246 
    247 $main::curwin
    248 			The current window object.
    249 
    250 $main::curbuf
    251 			The current buffer object.
    252 
    253 
    254 							*script-here*
    255 When using a script language in-line, you might want to skip this when the
    256 language isn't supported.  >
    257    if has('perl')
    258      perl << EOF
    259        print 'perl works'
    260    EOF
    261    endif
    262 Note that "EOF" must be at the start of the line without preceding white
    263 space.
    264 
    265 ==============================================================================
    266 4. Dynamic loading					*perl-dynamic*
    267 
    268 On MS-Windows and Unix the Perl library can be loaded dynamically.  The
    269 |:version| output then includes |+perl/dyn|.
    270 
    271 This means that Vim will search for the Perl DLL or shared library file only
    272 when needed.  When you don't use the Perl interface you don't need it, thus
    273 you can use Vim without this file.
    274 
    275 
    276 MS-Windows ~
    277 
    278 You can download Perl from http://www.perl.org.  The one from ActiveState was
    279 used for building Vim.
    280 
    281 To use the Perl interface the Perl DLL must be in your search path.
    282 If Vim reports it cannot find the perl512.dll, make sure your $PATH includes
    283 the directory where it is located.  The Perl installer normally does that.
    284 In a console window type "path" to see what directories are used.  The
    285 'perldll' option can be also used to specify the Perl DLL.
    286 
    287 The name of the DLL must match the Perl version Vim was compiled with.
    288 Currently the name is "perl512.dll".  That is for Perl 5.12.  To know for
    289 sure edit "gvim.exe" and search for "perl\d*.dll\c".
    290 
    291 
    292 Unix ~
    293 
    294 The 'perldll' option can be used to specify the Perl shared library file
    295 instead of DYNAMIC_PERL_DLL file what was specified at compile time.  The
    296 version of the shared library must match the Perl version Vim was compiled
    297 with.
    298 
    299 Note: If you are building Perl locally, you have to use a version compiled
    300 with threading support for it for Vim to successfully link against it.  You
    301 can use the `-Dusethreads` flags when configuring Perl, and check that a Perl
    302 binary has it enabled by running `perl -V` and verify that `USE_ITHREADS` is
    303 under "Compile-time options".
    304 
    305 ==============================================================================
    306  vim:tw=78:ts=8:noet:ft=help:norl: