|
1668
|
1 *if_perl.txt* For Vim version 7.2b. Last change: 2006 Mar 06
|
|
7
|
2
|
|
|
3
|
|
|
4 VIM REFERENCE MANUAL by Sven Verdoolaege
|
|
|
5 and Matt Gerassimof
|
|
|
6
|
|
|
7 Perl and Vim *perl* *Perl*
|
|
|
8
|
|
|
9 1. Editing Perl files |perl-editing|
|
|
|
10 2. Compiling VIM with Perl interface |perl-compiling|
|
|
|
11 3. Using the Perl interface |perl-using|
|
|
557
|
12 4. Dynamic loading |perl-dynamic|
|
|
7
|
13
|
|
|
14 {Vi does not have any of these commands}
|
|
|
15
|
|
|
16 The Perl interface only works when Vim was compiled with the |+perl| feature.
|
|
|
17
|
|
|
18 ==============================================================================
|
|
|
19 1. Editing Perl files *perl-editing*
|
|
|
20
|
|
|
21 Vim syntax highlighting supports Perl and POD files. Vim assumes a file is
|
|
236
|
22 Perl code if the filename has a .pl or .pm suffix. Vim also examines the first
|
|
7
|
23 line of a file, regardless of the filename suffix, to check if a file is a
|
|
|
24 Perl script (see scripts.vim in Vim's syntax directory). Vim assumes a file
|
|
|
25 is POD text if the filename has a .POD suffix.
|
|
|
26
|
|
|
27 To use tags with Perl, you need a recent version of Exuberant ctags. Look
|
|
|
28 here:
|
|
|
29 http://ctags.sourceforge.net
|
|
|
30
|
|
|
31 Alternatively, you can use the Perl script pltags.pl, which is shipped with
|
|
|
32 Vim in the $VIMRUNTIME/tools directory. This script has currently more
|
|
|
33 features than Exuberant ctags' Perl support.
|
|
|
34
|
|
|
35 ==============================================================================
|
|
|
36 2. Compiling VIM with Perl interface *perl-compiling*
|
|
|
37
|
|
|
38 To compile Vim with Perl interface, you need Perl 5.004 (or later). Perl must
|
|
|
39 be installed before you compile Vim. Vim's Perl interface does NOT work with
|
|
|
40 the 5.003 version that has been officially released! It will probably work
|
|
|
41 with Perl 5.003_05 and later.
|
|
|
42
|
|
|
43 The Perl patches for Vim were made by:
|
|
|
44 Sven Verdoolaege <skimo@breughel.ufsia.ac.be>
|
|
|
45 Matt Gerassimof
|
|
|
46
|
|
|
47 Perl for MS-Windows can be found at:
|
|
|
48 http://www.perl.com/CPAN/ports/nt/Standard/x86/
|
|
|
49
|
|
|
50 ==============================================================================
|
|
|
51 3. Using the Perl interface *perl-using*
|
|
|
52
|
|
|
53 *:perl* *:pe*
|
|
236
|
54 :pe[rl] {cmd} Execute Perl command {cmd}. The current package
|
|
7
|
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
|
|
|
73 Example 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
|
|
236
|
88 turn, without a trailing <EOL>. Setting $_ will change
|
|
7
|
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
|
|
|
93 Here 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*
|
|
|
101 Executing Perl commands in the |sandbox| is limited. ":perldo" will not be
|
|
|
102 possible at all. ":perl" will be evaluated in the Safe environment, if
|
|
|
103 possible.
|
|
|
104
|
|
|
105
|
|
|
106 *perl-overview*
|
|
|
107 Here 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*
|
|
|
143 VIM::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*
|
|
|
149 VIM::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*
|
|
|
154 VIM::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.
|
|
22
|
160 WARNING: the list becomes invalid when |:bwipe| is
|
|
|
161 used. Using it anyway may crash Vim.
|
|
7
|
162
|
|
|
163 *perl-Windows*
|
|
|
164 VIM::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.
|
|
22
|
169 WARNING: the list becomes invalid when a window is
|
|
|
170 closed. Using it anyway may crash Vim.
|
|
7
|
171
|
|
|
172 *perl-DoCommand*
|
|
|
173 VIM::DoCommand({cmd}) Executes Ex command {cmd}.
|
|
|
174
|
|
|
175 *perl-Eval*
|
|
|
176 VIM::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}.
|
|
714
|
184 A |List| is turned into a string by joining the items
|
|
|
185 and inserting line breaks.
|
|
7
|
186
|
|
|
187 *perl-SetHeight*
|
|
|
188 Window->SetHeight({height})
|
|
|
189 Sets the Window height to {height}, within screen
|
|
|
190 limits.
|
|
|
191
|
|
|
192 *perl-GetCursor*
|
|
|
193 Window->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
|
|
|
201 Window->Buffer() *perl-Buffer*
|
|
|
202 Returns the Buffer object corresponding to the given
|
|
|
203 Window.
|
|
|
204
|
|
|
205 *perl-Name*
|
|
|
206 Buffer->Name() Returns the filename for the Buffer.
|
|
|
207
|
|
|
208 *perl-Number*
|
|
|
209 Buffer->Number() Returns the number of the Buffer.
|
|
|
210
|
|
|
211 *perl-Count*
|
|
|
212 Buffer->Count() Returns the number of lines in the Buffer.
|
|
|
213
|
|
|
214 *perl-Get*
|
|
|
215 Buffer->Get({lnum}, {lnum}?, ...)
|
|
|
216 Returns a text string of line {lnum} in the Buffer
|
|
236
|
217 for each {lnum} specified. An array can be passed
|
|
7
|
218 with a list of {lnum}'s specified.
|
|
|
219
|
|
|
220 *perl-Delete*
|
|
|
221 Buffer->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*
|
|
|
227 Buffer->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*
|
|
|
232 Buffer->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*
|
|
|
246 When using a script language in-line, you might want to skip this when the
|
|
|
247 language 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
|
|
|
253 Instead, put the Perl/Python/Ruby/etc. command in a function and call that
|
|
|
254 function: >
|
|
|
255 if has('perl')
|
|
|
256 function DefPerl()
|
|
|
257 perl << EOF
|
|
|
258 this works
|
|
|
259 EOF
|
|
|
260 endfunction
|
|
|
261 call DefPerl()
|
|
|
262 endif
|
|
|
263 Note that "EOF" must be at the start of the line.
|
|
|
264
|
|
557
|
265 ==============================================================================
|
|
|
266 4. Dynamic loading *perl-dynamic*
|
|
|
267
|
|
|
268 On MS-Windows the Perl library can be loaded dynamically. The |:version|
|
|
|
269 output then includes |+perl/dyn|.
|
|
|
270
|
|
|
271 This means that Vim will search for the Perl DLL file only when needed. When
|
|
|
272 you don't use the Perl interface you don't need it, thus you can use Vim
|
|
|
273 without this DLL file.
|
|
|
274
|
|
|
275 To use the Perl interface the Perl DLL must be in your search path. In a
|
|
|
276 console window type "path" to see what directories are used.
|
|
|
277
|
|
|
278 The name of the DLL must match the Perl version Vim was compiled with.
|
|
|
279 Currently the name is "perl58.dll". That is for Perl 5.8. To know for
|
|
|
280 sure edit "gvim.exe" and search for "perl\d*.dll\c".
|
|
|
281
|
|
|
282 ==============================================================================
|
|
7
|
283 vim:tw=78:ts=8:ft=help:norl:
|
