diff options
Diffstat (limited to 'runtime/doc/if_perl.txt')
| -rw-r--r-- | runtime/doc/if_perl.txt | 294 |
1 files changed, 0 insertions, 294 deletions
diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt deleted file mode 100644 index 7be5f06f68..0000000000 --- a/runtime/doc/if_perl.txt +++ /dev/null @@ -1,294 +0,0 @@ -*if_perl.txt* For Vim version 7.4. Last change: 2013 Oct 05 - - - 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". - -============================================================================== - vim:tw=78:ts=8:ft=help:norl: |