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