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