blob: b82ee832fadb9dbf689739d7a173b22ce6df4937 [file] [log] [blame]
Bram Moolenaarb1c91982018-05-17 17:04:55 +02001*if_perl.txt* For Vim version 8.1. Last change: 2017 Nov 24
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|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200102. Compiling Vim with Perl interface |perl-compiling|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000113. 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==============================================================================
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200362. Compiling Vim with Perl interface *perl-compiling*
Bram Moolenaar071d4272004-06-13 20:20:40 +000037
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
Bram Moolenaar9b451252012-08-15 17:43:31 +020047Perl for MS-Windows can be found at: http://www.perl.com/
48The ActiveState one should work.
Bram Moolenaar071d4272004-06-13 20:20:40 +000049
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 Moolenaar9b451252012-08-15 17:43:31 +020055 is "main". Simple example to test if `:perl` is
56 working: >
57 :perl VIM::Msg("Hello")
Bram Moolenaar071d4272004-06-13 20:20:40 +000058
59:pe[rl] << {endpattern}
60{script}
61{endpattern}
62 Execute Perl script {script}.
63 {endpattern} must NOT be preceded by any white space.
64 If {endpattern} 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 This form of the |:perl| command is mainly useful for
69 including perl code in vim scripts.
70 Note: This command doesn't work when the Perl feature
71 wasn't compiled in. To avoid errors, see
72 |script-here|.
73
74
75Example vim script: >
76
77 function! WhitePearl()
78 perl << EOF
79 VIM::Msg("pearls are nice for necklaces");
80 VIM::Msg("rubys for rings");
81 VIM::Msg("pythons for bags");
82 VIM::Msg("tcls????");
83 EOF
84 endfunction
85<
Bram Moolenaarabd468e2016-09-08 22:22:43 +020086To see what version of Perl you have: >
87 :perl print $^V
88<
Bram Moolenaar071d4272004-06-13 20:20:40 +000089
90 *:perldo* *:perld*
91:[range]perld[o] {cmd} Execute Perl command {cmd} for each line in the
92 [range], with $_ being set to the text of each line in
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000093 turn, without a trailing <EOL>. Setting $_ will change
Bram Moolenaar071d4272004-06-13 20:20:40 +000094 the text, but note that it is not possible to add or
95 delete lines using this command.
96 The default for [range] is the whole file: "1,$".
97
98Here are some things you can try: >
99
100 :perl $a=1
101 :perldo $_ = reverse($_);1
102 :perl VIM::Msg("hello")
103 :perl $line = $curbuf->Get(42)
104<
105 *E299*
106Executing Perl commands in the |sandbox| is limited. ":perldo" will not be
107possible at all. ":perl" will be evaluated in the Safe environment, if
108possible.
109
110
111 *perl-overview*
112Here is an overview of the functions that are available to Perl: >
113
114 :perl VIM::Msg("Text") # displays a message
Bram Moolenaar2f058492017-11-30 20:27:52 +0100115 :perl VIM::Msg("Wrong!", "ErrorMsg") # displays an error message
Bram Moolenaar071d4272004-06-13 20:20:40 +0000116 :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*
148VIM::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*
154VIM::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*
159VIM::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.
Bram Moolenaard4755bb2004-09-02 19:12:26 +0000165 WARNING: the list becomes invalid when |:bwipe| is
166 used. Using it anyway may crash Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000167
168 *perl-Windows*
169VIM::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.
Bram Moolenaard4755bb2004-09-02 19:12:26 +0000174 WARNING: the list becomes invalid when a window is
175 closed. Using it anyway may crash Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000176
177 *perl-DoCommand*
178VIM::DoCommand({cmd}) Executes Ex command {cmd}.
179
180 *perl-Eval*
Bram Moolenaar97d62492012-11-15 21:28:22 +0100181VIM::Eval({expr}) Evaluates {expr} and returns (success, value) in list
182 context or just value in scalar context.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000183 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}.
Bram Moolenaar362e1a32006-03-06 23:29:24 +0000190 A |List| is turned into a string by joining the items
191 and inserting line breaks.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000192
193 *perl-SetHeight*
194Window->SetHeight({height})
195 Sets the Window height to {height}, within screen
196 limits.
197
198 *perl-GetCursor*
199Window->Cursor({row}?, {col}?)
200 With no arguments, returns a (row, col) array for the
201 current cursor position in the Window. With {row} and
202 {col} arguments, sets the Window's cursor position to
203 {row} and {col}. Note that {col} is numbered from 0,
204 Perl-fashion, and thus is one less than the value in
205 Vim's ruler.
206
207Window->Buffer() *perl-Buffer*
208 Returns the Buffer object corresponding to the given
209 Window.
210
211 *perl-Name*
212Buffer->Name() Returns the filename for the Buffer.
213
214 *perl-Number*
215Buffer->Number() Returns the number of the Buffer.
216
217 *perl-Count*
218Buffer->Count() Returns the number of lines in the Buffer.
219
220 *perl-Get*
221Buffer->Get({lnum}, {lnum}?, ...)
222 Returns a text string of line {lnum} in the Buffer
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000223 for each {lnum} specified. An array can be passed
Bram Moolenaar071d4272004-06-13 20:20:40 +0000224 with a list of {lnum}'s specified.
225
226 *perl-Delete*
227Buffer->Delete({lnum}, {lnum}?)
228 Deletes line {lnum} in the Buffer. With the second
229 {lnum}, deletes the range of lines from the first
230 {lnum} to the second {lnum}.
231
232 *perl-Append*
233Buffer->Append({lnum}, {line}, {line}?, ...)
234 Appends each {line} string after Buffer line {lnum}.
235 The list of {line}s can be an array.
236
237 *perl-Set*
238Buffer->Set({lnum}, {line}, {line}?, ...)
239 Replaces one or more Buffer lines with specified
240 {lines}s, starting at Buffer line {lnum}. The list of
241 {line}s can be an array. If the arguments are
242 invalid, replacement does not occur.
243
244$main::curwin
245 The current window object.
246
247$main::curbuf
248 The current buffer object.
249
250
251 *script-here*
252When using a script language in-line, you might want to skip this when the
253language isn't supported. But this mechanism doesn't work: >
254 if has('perl')
255 perl << EOF
256 this will NOT work!
257 EOF
258 endif
259Instead, put the Perl/Python/Ruby/etc. command in a function and call that
260function: >
261 if has('perl')
262 function DefPerl()
263 perl << EOF
264 this works
265 EOF
266 endfunction
267 call DefPerl()
268 endif
269Note that "EOF" must be at the start of the line.
270
Bram Moolenaara5792f52005-11-23 21:25:05 +0000271==============================================================================
2724. Dynamic loading *perl-dynamic*
273
Bram Moolenaare06c1882010-07-21 22:05:20 +0200274On MS-Windows and Unix the Perl library can be loaded dynamically. The
275|:version| output then includes |+perl/dyn|.
Bram Moolenaara5792f52005-11-23 21:25:05 +0000276
Bram Moolenaare06c1882010-07-21 22:05:20 +0200277This means that Vim will search for the Perl DLL or shared library file only
278when needed. When you don't use the Perl interface you don't need it, thus
279you can use Vim without this file.
280
281
282MS-Windows ~
Bram Moolenaara5792f52005-11-23 21:25:05 +0000283
Bram Moolenaar69154f22010-07-18 21:42:34 +0200284You can download Perl from http://www.perl.org. The one from ActiveState was
285used for building Vim.
286
287To use the Perl interface the Perl DLL must be in your search path.
288If Vim reports it cannot find the perl512.dll, make sure your $PATH includes
Bram Moolenaarfcb7ab62010-07-20 11:16:17 +0200289the directory where it is located. The Perl installer normally does that.
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100290In a console window type "path" to see what directories are used. The
291'perldll' option can be also used to specify the Perl DLL.
Bram Moolenaara5792f52005-11-23 21:25:05 +0000292
293The name of the DLL must match the Perl version Vim was compiled with.
Bram Moolenaar69154f22010-07-18 21:42:34 +0200294Currently the name is "perl512.dll". That is for Perl 5.12. To know for
Bram Moolenaara5792f52005-11-23 21:25:05 +0000295sure edit "gvim.exe" and search for "perl\d*.dll\c".
296
Bram Moolenaard94464e2015-11-02 15:28:18 +0100297
298Unix ~
299
300The 'perldll' option can be used to specify the Perl shared library file
301instead of DYNAMIC_PERL_DLL file what was specified at compile time. The
302version of the shared library must match the Perl version Vim was compiled
303with.
304
Bram Moolenaara5792f52005-11-23 21:25:05 +0000305==============================================================================
Bram Moolenaar91f84f62018-07-29 15:07:52 +0200306 vim:tw=78:ts=8:noet:ft=help:norl: