Mercurial > vim
annotate runtime/doc/if_perl.txt @ 2784:930b171ce3fc v7.3.168
updated for version 7.3.168
Problem: When the second argument of input() contains a CR the text up to
that is used without asking the user. (Yasuhiro Matsumoto)
Solution: Change CR, NL and ESC in the text to a space.
| author | Bram Moolenaar <bram@vim.org> |
|---|---|
| date | Thu, 28 Apr 2011 17:30:09 +0200 |
| parents | 073ff46fe397 |
| children | 536aa8b0c934 |
| rev | line source |
|---|---|
|
2572
ee53a39d5896
Last changes for the 7.3 release!
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
1 *if_perl.txt* For Vim version 7.3. Last change: 2010 Jul 21 |
| 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 | |
|
2370
454f314d0e61
Make it possible to load Perl dynamically on Unix. (James Vega)
Bram Moolenaar <bram@vim.org>
parents:
2365
diff
changeset
|
268 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
|
269 |:version| output then includes |+perl/dyn|. |
| 557 | 270 |
|
2370
454f314d0e61
Make it possible to load Perl dynamically on Unix. (James Vega)
Bram Moolenaar <bram@vim.org>
parents:
2365
diff
changeset
|
271 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
|
272 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
|
273 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
|
274 |
| 557 | 275 |
|
2370
454f314d0e61
Make it possible to load Perl dynamically on Unix. (James Vega)
Bram Moolenaar <bram@vim.org>
parents:
2365
diff
changeset
|
276 MS-Windows ~ |
| 557 | 277 |
|
2342
f6540762173d
Fixes and improvements for MS-Windows build.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
278 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
|
279 used for building Vim. |
| 557 | 280 |
|
2342
f6540762173d
Fixes and improvements for MS-Windows build.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
281 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
|
282 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
|
283 the directory where it is located. The Perl installer normally does that. |
|
2342
f6540762173d
Fixes and improvements for MS-Windows build.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
284 In a console window type "path" to see what directories are used. |
| 557 | 285 |
| 286 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
|
287 Currently the name is "perl512.dll". That is for Perl 5.12. To know for |
| 557 | 288 sure edit "gvim.exe" and search for "perl\d*.dll\c". |
| 289 | |
| 290 ============================================================================== | |
| 7 | 291 vim:tw=78:ts=8:ft=help:norl: |