Home Explore Blog CI



neovim

1st chunk of `runtime/doc/if_perl.txt`
2acd1073f8cb1c659003fb4cdd3b65f861281cc32b49c9d30000000100000fa4
*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

Title: Perl Interface to Vim: Commands and VIM Module
Summary
This section of the Vim reference manual describes the Perl interface to Vim, focusing on the `:perl`, `:perldo`, and `:perlfile` commands for executing Perl code within Vim. It explains how to use these commands, including passing arguments and incorporating Perl scripts. The section also introduces the `VIM` module, which provides Perl code with access to Vim functionalities, offering examples of how to display messages, set options, retrieve buffer and window information, evaluate expressions, and manipulate window and cursor positions.