share/vim/vim74/doc/if_perl.txt

   1 *if_perl.txt*   For Vim version 7.4.  Last change: 2012 Oct 25
   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: http://www.perl.com/
  48 The ActiveState one should work.
  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".  Simple example to test if `:perl` is
  56                         working: >
  57                                 :perl VIM::Msg("Hello")
  58
  59 :pe[rl] << {endpattern}
  60 {script}
  61 {endpattern}
  62                         Execute Perl script {script}.
  63                         {endpattern} must NOT be preceded by any white space.
  64                         If {endpattern} is omitted, it defaults to a dot '.'
  65                         like for the |:append| and |:insert| commands.  Using
  66                         '.' helps when inside a function, because "$i;" looks
  67                         like the start of an |:insert| command to Vim.
  68                         This form of the |:perl| command is mainly useful for
  69                         including perl code in vim scripts.
  70                         Note: This command doesn't work when the Perl feature
  71                         wasn't compiled in.  To avoid errors, see
  72                         |script-here|.
  73
  74
  75 Example vim script: >
  76
  77         function! WhitePearl()
  78         perl << EOF
  79                 VIM::Msg("pearls are nice for necklaces");
  80                 VIM::Msg("rubys for rings");
  81                 VIM::Msg("pythons for bags");
  82                 VIM::Msg("tcls????");
  83         EOF
  84         endfunction
  85 <
  86
  87                                                         *:perldo* *:perld*
  88 :[range]perld[o] {cmd}  Execute Perl command {cmd} for each line in the
  89                         [range], with $_ being set to the text of each line in
  90                         turn, without a trailing <EOL>.  Setting $_ will change
  91                         the text, but note that it is not possible to add or
  92                         delete lines using this command.
  93                         The default for [range] is the whole file: "1,$".
  94
  95 Here are some things you can try: >
  96
  97   :perl $a=1
  98   :perldo $_ = reverse($_);1
  99   :perl VIM::Msg("hello")
 100   :perl $line = $curbuf->Get(42)
 101 <
 102                                                         *E299*
 103 Executing Perl commands in the |sandbox| is limited.  ":perldo" will not be
 104 possible at all.  ":perl" will be evaluated in the Safe environment, if
 105 possible.
 106
 107
 108                                                         *perl-overview*
 109 Here is an overview of the functions that are available to Perl: >
 110
 111   :perl VIM::Msg("Text")                # displays a message
 112   :perl VIM::Msg("Error", "ErrorMsg")   # displays an error message
 113   :perl VIM::Msg("remark", "Comment")   # displays a highlighted message
 114   :perl VIM::SetOption("ai")            # sets a vim option
 115   :perl $nbuf = VIM::Buffers()          # returns the number of buffers
 116   :perl @buflist = VIM::Buffers()       # returns array of all buffers
 117   :perl $mybuf = (VIM::Buffers('qq.c'))[0] # returns buffer object for 'qq.c'
 118   :perl @winlist = VIM::Windows()       # returns array of all windows
 119   :perl $nwin = VIM::Windows()          # returns the number of windows
 120   :perl ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1
 121   :perl ($success, $v) = VIM::Eval('&xyz')  # $v: '' and $success: 0
 122   :perl $v = VIM::Eval('expand("<cfile>")') # expands <cfile>
 123   :perl $curwin->SetHeight(10)          # sets the window height
 124   :perl @pos = $curwin->Cursor()        # returns (row, col) array
 125   :perl @pos = (10, 10)
 126   :perl $curwin->Cursor(@pos)           # sets cursor to @pos
 127   :perl $curwin->Cursor(10,10)          # sets cursor to row 10 col 10
 128   :perl $mybuf = $curwin->Buffer()      # returns the buffer object for window
 129   :perl $curbuf->Name()                 # returns buffer name
 130   :perl $curbuf->Number()               # returns buffer number
 131   :perl $curbuf->Count()                # returns the number of lines
 132   :perl $l = $curbuf->Get(10)           # returns line 10
 133   :perl @l = $curbuf->Get(1 .. 5)       # returns lines 1 through 5
 134   :perl $curbuf->Delete(10)             # deletes line 10
 135   :perl $curbuf->Delete(10, 20)         # delete lines 10 through 20
 136   :perl $curbuf->Append(10, "Line")     # appends a line
 137   :perl $curbuf->Append(10, "Line1", "Line2", "Line3") # appends 3 lines
 138   :perl @l = ("L1", "L2", "L3")
 139   :perl $curbuf->Append(10, @l)         # appends L1, L2 and L3
 140   :perl $curbuf->Set(10, "Line")        # replaces line 10
 141   :perl $curbuf->Set(10, "Line1", "Line2")      # replaces lines 10 and 11
 142   :perl $curbuf->Set(10, @l)            # replaces 3 lines
 143 <
 144                                                         *perl-Msg*
 145 VIM::Msg({msg}, {group}?)
 146                         Displays the message {msg}.  The optional {group}
 147                         argument specifies a highlight group for Vim to use
 148                         for the message.
 149
 150                                                         *perl-SetOption*
 151 VIM::SetOption({arg})   Sets a vim option.  {arg} can be any argument that the
 152                         ":set" command accepts.  Note that this means that no
 153                         spaces are allowed in the argument!  See |:set|.
 154
 155                                                         *perl-Buffers*
 156 VIM::Buffers([{bn}...]) With no arguments, returns a list of all the buffers
 157                         in an array context or returns the number of buffers
 158                         in a scalar context.  For a list of buffer names or
 159                         numbers {bn}, returns a list of the buffers matching
 160                         {bn}, using the same rules as Vim's internal
 161                         |bufname()| function.
 162                         WARNING: the list becomes invalid when |:bwipe| is
 163                         used.  Using it anyway may crash Vim.
 164
 165                                                         *perl-Windows*
 166 VIM::Windows([{wn}...]) With no arguments, returns a list of all the windows
 167                         in an array context or returns the number of windows
 168                         in a scalar context.  For a list of window numbers
 169                         {wn}, returns a list of the windows with those
 170                         numbers.
 171                         WARNING: the list becomes invalid when a window is
 172                         closed.  Using it anyway may crash Vim.
 173
 174                                                         *perl-DoCommand*
 175 VIM::DoCommand({cmd})   Executes Ex command {cmd}.
 176
 177                                                         *perl-Eval*
 178 VIM::Eval({expr})       Evaluates {expr} and returns (success, value) in list
 179                         context or just value in scalar context.
 180                         success=1 indicates that val contains the value of
 181                         {expr}; success=0 indicates a failure to evaluate
 182                         the expression.  '@x' returns the contents of register
 183                         x, '&x' returns the value of option x, 'x' returns the
 184                         value of internal |variables| x, and '$x' is equivalent
 185                         to perl's $ENV{x}.  All |functions| accessible from
 186                         the command-line are valid for {expr}.
 187                         A |List| is turned into a string by joining the items
 188                         and inserting line breaks.
 189
 190                                                         *perl-SetHeight*
 191 Window->SetHeight({height})
 192                         Sets the Window height to {height}, within screen
 193                         limits.
 194
 195                                                         *perl-GetCursor*
 196 Window->Cursor({row}?, {col}?)
 197                         With no arguments, returns a (row, col) array for the
 198                         current cursor position in the Window.  With {row} and
 199                         {col} arguments, sets the Window's cursor position to
 200                         {row} and {col}.  Note that {col} is numbered from 0,
 201                         Perl-fashion, and thus is one less than the value in
 202                         Vim's ruler.
 203
 204 Window->Buffer()                                        *perl-Buffer*
 205                         Returns the Buffer object corresponding to the given
 206                         Window.
 207
 208                                                         *perl-Name*
 209 Buffer->Name()          Returns the filename for the Buffer.
 210
 211                                                         *perl-Number*
 212 Buffer->Number()        Returns the number of the Buffer.
 213
 214                                                         *perl-Count*
 215 Buffer->Count()         Returns the number of lines in the Buffer.
 216
 217                                                         *perl-Get*
 218 Buffer->Get({lnum}, {lnum}?, ...)
 219                         Returns a text string of line {lnum} in the Buffer
 220                         for each {lnum} specified.  An array can be passed
 221                         with a list of {lnum}'s specified.
 222
 223                                                         *perl-Delete*
 224 Buffer->Delete({lnum}, {lnum}?)
 225                         Deletes line {lnum} in the Buffer.  With the second
 226                         {lnum}, deletes the range of lines from the first
 227                         {lnum} to the second {lnum}.
 228
 229                                                         *perl-Append*
 230 Buffer->Append({lnum}, {line}, {line}?, ...)
 231                         Appends each {line} string after Buffer line {lnum}.
 232                         The list of {line}s can be an array.
 233
 234                                                         *perl-Set*
 235 Buffer->Set({lnum}, {line}, {line}?, ...)
 236                         Replaces one or more Buffer lines with specified
 237                         {lines}s, starting at Buffer line {lnum}.  The list of
 238                         {line}s can be an array.  If the arguments are
 239                         invalid, replacement does not occur.
 240
 241 $main::curwin
 242                         The current window object.
 243
 244 $main::curbuf
 245                         The current buffer object.
 246
 247
 248                                                         *script-here*
 249 When using a script language in-line, you might want to skip this when the
 250 language isn't supported.  But this mechanism doesn't work: >
 251    if has('perl')
 252      perl << EOF
 253        this will NOT work!
 254    EOF
 255    endif
 256 Instead, put the Perl/Python/Ruby/etc. command in a function and call that
 257 function: >
 258     if has('perl')
 259       function DefPerl()
 260         perl << EOF
 261           this works
 262     EOF
 263       endfunction
 264       call DefPerl()
 265     endif
 266 Note that "EOF" must be at the start of the line.
 267
 268 ==============================================================================
 269 4. Dynamic loading                                      *perl-dynamic*
 270
 271 On MS-Windows and Unix the Perl library can be loaded dynamically.  The
 272 |:version| output then includes |+perl/dyn|.
 273
 274 This means that Vim will search for the Perl DLL or shared library file only
 275 when needed.  When you don't use the Perl interface you don't need it, thus
 276 you can use Vim without this file.
 277
 278
 279 MS-Windows ~
 280
 281 You can download Perl from http://www.perl.org.  The one from ActiveState was
 282 used for building Vim.
 283
 284 To use the Perl interface the Perl DLL must be in your search path.
 285 If Vim reports it cannot find the perl512.dll, make sure your $PATH includes
 286 the directory where it is located.  The Perl installer normally does that.
 287 In a console window type "path" to see what directories are used.
 288
 289 The name of the DLL must match the Perl version Vim was compiled with.
 290 Currently the name is "perl512.dll".  That is for Perl 5.12.  To know for
 291 sure edit "gvim.exe" and search for "perl\d*.dll\c".
 292
 293 ==============================================================================
 294  vim:tw=78:ts=8:ft=help:norl: