*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 << [trim] [{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 Nvim 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