| *if_perl.txt* For Vim version 7.4. Last change: 2015 Oct 16 |
| |
| |
| VIM REFERENCE MANUAL by Sven Verdoolaege |
| and Matt Gerassimof |
| |
| Perl and Vim *perl* *Perl* |
| |
| 1. Editing Perl files |perl-editing| |
| 2. Compiling VIM with Perl interface |perl-compiling| |
| 3. Using the Perl interface |perl-using| |
| 4. Dynamic loading |perl-dynamic| |
| |
| {Vi does not have any of these commands} |
| |
| The Perl interface only works when Vim was compiled with the |+perl| feature. |
| |
| ============================================================================== |
| 1. Editing Perl files *perl-editing* |
| |
| Vim syntax highlighting supports Perl and POD files. Vim assumes a file is |
| Perl code if the filename has a .pl or .pm suffix. Vim also examines the first |
| line of a file, regardless of the filename suffix, to check if a file is a |
| Perl script (see scripts.vim in Vim's syntax directory). Vim assumes a file |
| is POD text if the filename has a .POD suffix. |
| |
| To use tags with Perl, you need a recent version of Exuberant ctags. Look |
| here: |
| http://ctags.sourceforge.net |
| |
| Alternatively, you can use the Perl script pltags.pl, which is shipped with |
| Vim in the $VIMRUNTIME/tools directory. This script has currently more |
| features than Exuberant ctags' Perl support. |
| |
| ============================================================================== |
| 2. Compiling VIM with Perl interface *perl-compiling* |
| |
| To compile Vim with Perl interface, you need Perl 5.004 (or later). Perl must |
| be installed before you compile Vim. Vim's Perl interface does NOT work with |
| the 5.003 version that has been officially released! It will probably work |
| with Perl 5.003_05 and later. |
| |
| The Perl patches for Vim were made by: |
| Sven Verdoolaege <skimo@breughel.ufsia.ac.be> |
| Matt Gerassimof |
| |
| Perl for MS-Windows can be found at: http://www.perl.com/ |
| The ActiveState one should work. |
| |
| ============================================================================== |
| 3. Using the Perl interface *perl-using* |
| |
| *:perl* *:pe* |
| :pe[rl] {cmd} Execute Perl command {cmd}. The current package |
| is "main". Simple example to test if `:perl` is |
| working: > |
| :perl VIM::Msg("Hello") |
| |
| :pe[rl] << {endpattern} |
| {script} |
| {endpattern} |
| Execute Perl script {script}. |
| {endpattern} must NOT be preceded by any white space. |
| If {endpattern} is omitted, it defaults to a dot '.' |
| like for the |:append| and |:insert| commands. Using |
| '.' helps when inside a function, because "$i;" looks |
| like the start of an |:insert| command to Vim. |
| This form of the |:perl| command is mainly useful for |
| including perl code in vim scripts. |
| Note: This command doesn't work when the Perl feature |
| wasn't compiled in. To avoid errors, see |
| |script-here|. |
| |
| |
| Example vim script: > |
| |
| function! WhitePearl() |
| perl << EOF |
| VIM::Msg("pearls are nice for necklaces"); |
| VIM::Msg("rubys for rings"); |
| VIM::Msg("pythons for bags"); |
| VIM::Msg("tcls????"); |
| EOF |
| endfunction |
| < |
| |
| *:perldo* *:perld* |
| :[range]perld[o] {cmd} Execute Perl command {cmd} for each line in the |
| [range], with $_ being set to the text of each line in |
| turn, without a trailing <EOL>. Setting $_ will change |
| the text, but note that it is not possible to add or |
| delete lines using this command. |
| The default for [range] is the whole file: "1,$". |
| |
| Here are some things you can try: > |
| |
| :perl $a=1 |
| :perldo $_ = reverse($_);1 |
| :perl VIM::Msg("hello") |
| :perl $line = $curbuf->Get(42) |
| < |
| *E299* |
| Executing Perl commands in the |sandbox| is limited. ":perldo" will not be |
| possible at all. ":perl" will be evaluated in the Safe environment, if |
| possible. |
| |
| |
| *perl-overview* |
| Here is an overview of the functions that are available to Perl: > |
| |
| :perl VIM::Msg("Text") # displays a message |
| :perl VIM::Msg("Error", "ErrorMsg") # displays an error message |
| :perl VIM::Msg("remark", "Comment") # displays a highlighted message |
| :perl VIM::SetOption("ai") # sets a vim option |
| :perl $nbuf = VIM::Buffers() # returns the number of buffers |
| :perl @buflist = VIM::Buffers() # returns array of all buffers |
| :perl $mybuf = (VIM::Buffers('qq.c'))[0] # returns buffer object for 'qq.c' |
| :perl @winlist = VIM::Windows() # returns array of all windows |
| :perl $nwin = VIM::Windows() # returns the number of windows |
| :perl ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1 |
| :perl ($success, $v) = VIM::Eval('&xyz') # $v: '' and $success: 0 |
| :perl $v = VIM::Eval('expand("<cfile>")') # expands <cfile> |
| :perl $curwin->SetHeight(10) # sets the window height |
| :perl @pos = $curwin->Cursor() # returns (row, col) array |
| :perl @pos = (10, 10) |
| :perl $curwin->Cursor(@pos) # sets cursor to @pos |
| :perl $curwin->Cursor(10,10) # sets cursor to row 10 col 10 |
| :perl $mybuf = $curwin->Buffer() # returns the buffer object for window |
| :perl $curbuf->Name() # returns buffer name |
| :perl $curbuf->Number() # returns buffer number |
| :perl $curbuf->Count() # returns the number of lines |
| :perl $l = $curbuf->Get(10) # returns line 10 |
| :perl @l = $curbuf->Get(1 .. 5) # returns lines 1 through 5 |
| :perl $curbuf->Delete(10) # deletes line 10 |
| :perl $curbuf->Delete(10, 20) # delete lines 10 through 20 |
| :perl $curbuf->Append(10, "Line") # appends a line |
| :perl $curbuf->Append(10, "Line1", "Line2", "Line3") # appends 3 lines |
| :perl @l = ("L1", "L2", "L3") |
| :perl $curbuf->Append(10, @l) # appends L1, L2 and L3 |
| :perl $curbuf->Set(10, "Line") # replaces line 10 |
| :perl $curbuf->Set(10, "Line1", "Line2") # replaces lines 10 and 11 |
| :perl $curbuf->Set(10, @l) # replaces 3 lines |
| < |
| *perl-Msg* |
| VIM::Msg({msg}, {group}?) |
| Displays the message {msg}. The optional {group} |
| argument specifies a highlight group for Vim to use |
| for the message. |
| |
| *perl-SetOption* |
| VIM::SetOption({arg}) Sets a vim option. {arg} can be any argument that the |
| ":set" command accepts. Note that this means that no |
| spaces are allowed in the argument! See |:set|. |
| |
| *perl-Buffers* |
| VIM::Buffers([{bn}...]) With no arguments, returns a list of all the buffers |
| in an array context or returns the number of buffers |
| in a scalar context. For a list of buffer names or |
| numbers {bn}, returns a list of the buffers matching |
| {bn}, using the same rules as Vim's internal |
| |bufname()| function. |
| WARNING: the list becomes invalid when |:bwipe| is |
| used. Using it anyway may crash Vim. |
| |
| *perl-Windows* |
| VIM::Windows([{wn}...]) With no arguments, returns a list of all the windows |
| in an array context or returns the number of windows |
| in a scalar context. For a list of window numbers |
| {wn}, returns a list of the windows with those |
| numbers. |
| WARNING: the list becomes invalid when a window is |
| closed. Using it anyway may crash Vim. |
| |
| *perl-DoCommand* |
| VIM::DoCommand({cmd}) Executes Ex command {cmd}. |
| |
| *perl-Eval* |
| VIM::Eval({expr}) Evaluates {expr} and returns (success, value) in list |
| context or just value in scalar context. |
| success=1 indicates that val contains the value of |
| {expr}; success=0 indicates a failure to evaluate |
| the expression. '@x' returns the contents of register |
| x, '&x' returns the value of option x, 'x' returns the |
| value of internal |variables| x, and '$x' is equivalent |
| to perl's $ENV{x}. All |functions| accessible from |
| the command-line are valid for {expr}. |
| A |List| is turned into a string by joining the items |
| and inserting line breaks. |
| |
| *perl-SetHeight* |
| Window->SetHeight({height}) |
| Sets the Window height to {height}, within screen |
| limits. |
| |
| *perl-GetCursor* |
| Window->Cursor({row}?, {col}?) |
| With no arguments, returns a (row, col) array for the |
| current cursor position in the Window. With {row} and |
| {col} arguments, sets the Window's cursor position to |
| {row} and {col}. Note that {col} is numbered from 0, |
| Perl-fashion, and thus is one less than the value in |
| Vim's ruler. |
| |
| Window->Buffer() *perl-Buffer* |
| Returns the Buffer object corresponding to the given |
| Window. |
| |
| *perl-Name* |
| Buffer->Name() Returns the filename for the Buffer. |
| |
| *perl-Number* |
| Buffer->Number() Returns the number of the Buffer. |
| |
| *perl-Count* |
| Buffer->Count() Returns the number of lines in the Buffer. |
| |
| *perl-Get* |
| Buffer->Get({lnum}, {lnum}?, ...) |
| Returns a text string of line {lnum} in the Buffer |
| for each {lnum} specified. An array can be passed |
| with a list of {lnum}'s specified. |
| |
| *perl-Delete* |
| Buffer->Delete({lnum}, {lnum}?) |
| Deletes line {lnum} in the Buffer. With the second |
| {lnum}, deletes the range of lines from the first |
| {lnum} to the second {lnum}. |
| |
| *perl-Append* |
| Buffer->Append({lnum}, {line}, {line}?, ...) |
| Appends each {line} string after Buffer line {lnum}. |
| The list of {line}s can be an array. |
| |
| *perl-Set* |
| Buffer->Set({lnum}, {line}, {line}?, ...) |
| Replaces one or more Buffer lines with specified |
| {lines}s, starting at Buffer line {lnum}. The list of |
| {line}s can be an array. If the arguments are |
| invalid, replacement does not occur. |
| |
| $main::curwin |
| The current window object. |
| |
| $main::curbuf |
| The current buffer object. |
| |
| |
| *script-here* |
| When using a script language in-line, you might want to skip this when the |
| language isn't supported. But this mechanism doesn't work: > |
| if has('perl') |
| perl << EOF |
| this will NOT work! |
| EOF |
| endif |
| Instead, put the Perl/Python/Ruby/etc. command in a function and call that |
| function: > |
| if has('perl') |
| function DefPerl() |
| perl << EOF |
| this works |
| EOF |
| endfunction |
| call DefPerl() |
| endif |
| Note that "EOF" must be at the start of the line. |
| |
| ============================================================================== |
| 4. Dynamic loading *perl-dynamic* |
| |
| On MS-Windows and Unix the Perl library can be loaded dynamically. The |
| |:version| output then includes |+perl/dyn|. |
| |
| This means that Vim will search for the Perl DLL or shared library file only |
| when needed. When you don't use the Perl interface you don't need it, thus |
| you can use Vim without this file. |
| |
| |
| MS-Windows ~ |
| |
| You can download Perl from http://www.perl.org. The one from ActiveState was |
| used for building Vim. |
| |
| To use the Perl interface the Perl DLL must be in your search path. |
| If Vim reports it cannot find the perl512.dll, make sure your $PATH includes |
| the directory where it is located. The Perl installer normally does that. |
| In a console window type "path" to see what directories are used. |
| |
| The name of the DLL must match the Perl version Vim was compiled with. |
| Currently the name is "perl512.dll". That is for Perl 5.12. To know for |
| sure edit "gvim.exe" and search for "perl\d*.dll\c". |
| |
| |
| Unix ~ |
| |
| The 'perldll' option can be used to specify the Perl shared library file |
| instead of DYNAMIC_PERL_DLL file what was specified at compile time. The |
| version of the shared library must match the Perl version Vim was compiled |
| with. |
| |
| ============================================================================== |
| vim:tw=78:ts=8:ft=help:norl: |