diff options
Diffstat (limited to 'runtime/doc/if_perl.txt')
| -rw-r--r-- | runtime/doc/if_perl.txt | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt new file mode 100644 index 0000000..86edd05 --- /dev/null +++ b/runtime/doc/if_perl.txt @@ -0,0 +1,307 @@ +*if_perl.txt* For Vim version 9.1. Last change: 2023 May 14 + + + 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| + +{only available 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 Universal/Exuberant Ctags. Look here: + Universal Ctags (preferred): https://ctags.io + Exuberant Ctags: 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 (and other platforms) can be found at: + http://www.perl.org/ +The ActiveState one should work, Strawberry Perl is a good alternative. + +============================================================================== +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] << [trim] [{endmarker}] +{script} +{endmarker} + Execute Perl script {script}. + The {endmarker} after {script} must NOT be preceded by + any white space. + + If [endmarker] 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 +< +To see what version of Perl you have: > + :perl print $^V +< + + *: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("Wrong!", "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-Blob* +VIM::Blob({expr}) Return |Blob| literal string 0zXXXX from scalar value. + + *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. > + if has('perl') + perl << EOF + print 'perl works' + EOF + endif +Note that "EOF" must be at the start of the line without preceding white +space. + +============================================================================== +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 +'perldll' option can be also used to specify the Perl DLL. + +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. + +Note: If you are building Perl locally, you have to use a version compiled +with threading support for it for Vim to successfully link against it. You can +use the `-Dusethreads` flags when configuring Perl, and check that a Perl +binary has it enabled by running `perl -V` and verify that `USE_ITHREADS` is +under "Compile-time options". + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: |