Quick links: help overview · quick reference · user manual toc · reference manual toc
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:


Quick links: help overview · quick reference · user manual toc · reference manual toc