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