path: root/runtime/doc/if_perl.txt

*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: