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: