if_perl.txt Nvim VIM REFERENCE MANUAL by Jacques Germishuys The perl Interface to Vim if_perl perl See provider-perl for more information. Type gO to see the table of contents. ============================================================================== 1. Commands perl-commands :perl :[range]perl {stmt} Execute perl statement {stmt}. The current package is "main". A simple check if the :perl command is working: :perl print "Hello" :[range]perl << [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. Useful for including perl code in Vim scripts. Requires perl, see script-here. Example: function! MyVimMethod() perl << EOF sub my_vim_method { print "Hello World!\n"; } EOF endfunction To see what version of perl you have: :perl print $^V :perldo :[range]perldo {cmd} Execute perl command {cmd} for each line in the[range], with $_ being set to the test of each line in turn, without a trailing <EOL>. In addition to $_, $line and $linenr is also set to the line content and line number respectively. 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,$". Examples: :perldo $_ = reverse($_); :perldo $_ = "".$linenr." => $line"; One can use :perldo in conjunction with :perl to filter a range using perl. For example: :perl << EOF sub perl_vim_string_replace { my $line = shift; my $needle = $vim->eval('@a'); my $replacement = $vim->eval('@b'); $line =~ s/$needle/$replacement/g; return $line; } EOF :let @a='somevalue' :let @b='newvalue' :'<,'>perldo $_ = perl_vim_string_replace($_) :perlfile :[range]perlfile {file} Execute the perl script in {file}. The whole argument is used as a single file name. Both of these commands do essentially the same thing - they execute a piece of perl code, with the "current range" set to the given line range. In the case of :perl, the code to execute is in the command-line. In the case of :perlfile, the code to execute is the contents of the given file. perl commands cannot be used in the sandbox. To pass arguments you need to set @ARGV explicitly. Example: :perl @ARGV = ("foo", "bar"); :perlfile myscript.pl Here are some examples perl-examples :perl print "Hello" :perl $current->line (uc ($current->line)) :perl my $str = $current->buffer->[42]; print "Set \$str to: $str" Note that changes (such as the "use" statements) persist from one command to the next. ============================================================================== 2. The VIM module perl-vim Perl code gets all of its access to Neovim via the "VIM" module. Overview print "Hello" # displays a message VIM::Msg("Hello") # displays a message VIM::SetOption("ai") # sets a vim option $nbuf = VIM::Buffers() # returns the number of buffers @buflist = VIM::Buffers() # returns array of all buffers $mybuf = (VIM::Buffers('a.c'))[0] # returns buffer object for 'a.c' @winlist = VIM::Windows() # returns array of all windows $nwin = VIM::Windows() # returns the number of windows ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1 ($success, $v) = VIM::Eval('&xyz') # $v: '' and $success: 0 $v = VIM::Eval('expand("<cfile>")') # expands <cfile> $curwin->SetHeight(10) # sets the window height @pos = $curwin->Cursor() # returns (row, col) array @pos = (10, 10) $curwin->Cursor(@pos) # sets cursor to @pos $curwin->Cursor(10,10) # sets cursor to row 10 col 10 $mybuf = $curwin->Buffer() # returns the buffer object for window $curbuf->Name() # returns buffer name $curbuf->Number() # returns buffer number $curbuf->Count() # returns the number of lines $l = $curbuf->Get(10) # returns line 10 @l = $curbuf->Get(1 .. 5) # returns lines 1 through 5 $curbuf->Delete(10) # deletes line 10 $curbuf->Delete(10, 20) # delete lines 10 through 20 $curbuf->Append(10, "Line") # appends a line $curbuf->Append(10, "L1", "L2", "L3") # appends 3 lines @l = ("L1", "L2", "L3") $curbuf->Append(10, @l) # appends L1, L2 and L3 $curbuf->Set(10, "Line") # replaces line 10 $curbuf->Set(10, "Line1", "Line2") # replaces lines 10 and 11 $curbuf->Set(10, @l) # replaces 3 lines Module Functions: perl-Msg VIM::Msg({msg}) Displays the message {msg}. 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. 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. 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. ============================================================================== 3. VIM::Buffer objects perl-buffer Methods: perl-Buffer-Name Name() Returns the filename for the Buffer. perl-Buffer-Number Number() Returns the number of the Buffer. perl-Buffer-Count Count() Returns the number of lines in the Buffer. perl-Buffer-Get 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-Buffer-Delete 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-Buffer-Append Append({lnum}, {line}, {line}?, ...) Appends each {line} string after Buffer line {lnum}. The list of {line}s can be an array. perl-Buffer-Set 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. ============================================================================== 4. VIM::Window objects perl-window Methods: perl-Window-SetHeight SetHeight({height}) Sets the Window height to {height}, within screen limits. perl-Window-GetCursor 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. Buffer() perl-Window-Buffer Returns the Buffer object corresponding to the given Window. ============================================================================== 5. Lexical variables perl-globals There are multiple lexical variables. $curwin The current Window object. $curbuf The current Buffer object. $vim A Neovim::Ext object. $nvim The same as $nvim. $current A Neovim::Ext::Current object. These are also available via the "main" package: $main::curwin The current Window object. $main::curbuf The current Buffer object. ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: