blob: 842393a77777c8826cdb52fb6831548b995efe26 [file] [log] [blame]
Bram Moolenaarb8521962010-07-20 22:45:13 +02001*if_perl.txt* For Vim version 7.3b. Last change: 2010 Jul 20
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
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|
Bram Moolenaara5792f52005-11-23 21:25:05 +0000124. Dynamic loading |perl-dynamic|
Bram Moolenaar071d4272004-06-13 20:20:40 +000013
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
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000022Perl code if the filename has a .pl or .pm suffix. Vim also examines the first
Bram Moolenaar071d4272004-06-13 20:20:40 +000023line 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*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000054:pe[rl] {cmd} Execute Perl command {cmd}. The current package
Bram Moolenaar071d4272004-06-13 20:20:40 +000055 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
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000088 turn, without a trailing <EOL>. Setting $_ will change
Bram Moolenaar071d4272004-06-13 20:20:40 +000089 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.
Bram Moolenaard4755bb2004-09-02 19:12:26 +0000160 WARNING: the list becomes invalid when |:bwipe| is
161 used. Using it anyway may crash Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000162
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.
Bram Moolenaard4755bb2004-09-02 19:12:26 +0000169 WARNING: the list becomes invalid when a window is
170 closed. Using it anyway may crash Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000171
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}.
Bram Moolenaar362e1a32006-03-06 23:29:24 +0000184 A |List| is turned into a string by joining the items
185 and inserting line breaks.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000186
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
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000217 for each {lnum} specified. An array can be passed
Bram Moolenaar071d4272004-06-13 20:20:40 +0000218 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
Bram Moolenaara5792f52005-11-23 21:25:05 +0000265==============================================================================
2664. Dynamic loading *perl-dynamic*
267
268On MS-Windows the Perl library can be loaded dynamically. The |:version|
269output then includes |+perl/dyn|.
270
271This means that Vim will search for the Perl DLL file only when needed. When
272you don't use the Perl interface you don't need it, thus you can use Vim
273without this DLL file.
274
Bram Moolenaar69154f22010-07-18 21:42:34 +0200275You can download Perl from http://www.perl.org. The one from ActiveState was
276used for building Vim.
277
278To use the Perl interface the Perl DLL must be in your search path.
279If Vim reports it cannot find the perl512.dll, make sure your $PATH includes
Bram Moolenaarfcb7ab62010-07-20 11:16:17 +0200280the directory where it is located. The Perl installer normally does that.
Bram Moolenaar69154f22010-07-18 21:42:34 +0200281In a console window type "path" to see what directories are used.
Bram Moolenaara5792f52005-11-23 21:25:05 +0000282
283The name of the DLL must match the Perl version Vim was compiled with.
Bram Moolenaar69154f22010-07-18 21:42:34 +0200284Currently the name is "perl512.dll". That is for Perl 5.12. To know for
Bram Moolenaara5792f52005-11-23 21:25:05 +0000285sure edit "gvim.exe" and search for "perl\d*.dll\c".
286
287==============================================================================
Bram Moolenaar071d4272004-06-13 20:20:40 +0000288 vim:tw=78:ts=8:ft=help:norl: