runtime/doc/if_perl.txt

   1 *if_perl.txt*   For Vim version 7.2.  Last change: 2006 Mar 06
   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 the Perl library can be loaded dynamically.  The |:version|
 269 output then includes |+perl/dyn|.
 270
 271 This means that Vim will search for the Perl DLL file only when needed.  When
 272 you don't use the Perl interface you don't need it, thus you can use Vim
 273 without this DLL file.
 274
 275 To use the Perl interface the Perl DLL must be in your search path.  In a
 276 console window type "path" to see what directories are used.
 277
 278 The name of the DLL must match the Perl version Vim was compiled with.
 279 Currently the name is "perl58.dll".  That is for Perl 5.8.  To know for
 280 sure edit "gvim.exe" and search for "perl\d*.dll\c".
 281
 282 ==============================================================================
 283  vim:tw=78:ts=8:ft=help:norl: