home *** CD-ROM | disk | FTP | other *** search
/ vim.ftp.fu-berlin.de / 2015-02-03.vim.ftp.fu-berlin.de.tar / vim.ftp.fu-berlin.de / runtime / dos / doc / if_perl.txt < prev    next >
Encoding:
Text File  |  2010-08-15  |  10.7 KB  |  292 lines
  1. *if_perl.txt*   For Vim version 7.3.  Last change: 2010 Jul 21
  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|
  12. 4. Dynamic loading            |perl-dynamic|
  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
  22. Perl code if the filename has a .pl or .pm suffix.  Vim also examines the first
  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*
  54. :pe[rl] {cmd}        Execute Perl command {cmd}.  The current package
  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
  88.             turn, without a trailing <EOL>.  Setting $_ will change
  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.
  160.             WARNING: the list becomes invalid when |:bwipe| is
  161.             used.  Using it anyway may crash Vim.
  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.
  169.             WARNING: the list becomes invalid when a window is
  170.             closed.  Using it anyway may crash Vim.
  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}.
  184.             A |List| is turned into a string by joining the items
  185.             and inserting line breaks.
  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
  217.             for each {lnum} specified.  An array can be passed
  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.  
  265. ==============================================================================
  266. 4. Dynamic loading                    *perl-dynamic*
  267.  
  268. On MS-Windows and Unix the Perl library can be loaded dynamically.  The
  269. |:version| output then includes |+perl/dyn|.
  270.  
  271. This means that Vim will search for the Perl DLL or shared library file only
  272. when needed.  When you don't use the Perl interface you don't need it, thus
  273. you can use Vim without this file.
  274.  
  275.  
  276. MS-Windows ~
  277.  
  278. You can download Perl from http://www.perl.org.  The one from ActiveState was
  279. used for building Vim.
  280.  
  281. To use the Perl interface the Perl DLL must be in your search path.
  282. If Vim reports it cannot find the perl512.dll, make sure your $PATH includes
  283. the directory where it is located.  The Perl installer normally does that.
  284. In a console window type "path" to see what directories are used.
  285.  
  286. The name of the DLL must match the Perl version Vim was compiled with.
  287. Currently the name is "perl512.dll".  That is for Perl 5.12.  To know for
  288. sure edit "gvim.exe" and search for "perl\d*.dll\c".
  289.  
  290. ==============================================================================
  291.  vim:tw=78:ts=8:ft=help:norl:
  292.