Adding upstream version 2:9.1.0016.upstream/2%9.1.0016

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 307 insertions, 0 deletions

diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt
new file mode 100644
index 0000000..86edd05
--- /dev/null
+++ b/runtime/doc/if_perl.txt
@@ -0,0 +1,307 @@
+*if_perl.txt*   For Vim version 9.1.  Last change: 2023 May 14
+
+
+		  VIM REFERENCE MANUAL    by Sven Verdoolaege
+					 and Matt Gerassimof
+
+Perl and Vim				*perl* *Perl*
+
+1. Editing Perl files			|perl-editing|
+2. Compiling Vim with Perl interface	|perl-compiling|
+3. Using the Perl interface		|perl-using|
+4. Dynamic loading			|perl-dynamic|
+
+{only available when Vim was compiled with the |+perl| feature}
+
+==============================================================================
+1. Editing Perl files					*perl-editing*
+
+Vim syntax highlighting supports Perl and POD files.  Vim assumes a file is
+Perl code if the filename has a .pl or .pm suffix.  Vim also examines the first
+line of a file, regardless of the filename suffix, to check if a file is a
+Perl script (see scripts.vim in Vim's syntax directory).  Vim assumes a file
+is POD text if the filename has a .POD suffix.
+
+To use tags with Perl, you need Universal/Exuberant Ctags.  Look here:
+	Universal Ctags (preferred): https://ctags.io
+	Exuberant Ctags: http://ctags.sourceforge.net
+
+Alternatively, you can use the Perl script pltags.pl, which is shipped with
+Vim in the $VIMRUNTIME/tools directory.  This script has currently more
+features than Exuberant ctags' Perl support.
+
+==============================================================================
+2. Compiling Vim with Perl interface			*perl-compiling*
+
+To compile Vim with Perl interface, you need Perl 5.004 (or later).  Perl must
+be installed before you compile Vim.  Vim's Perl interface does NOT work with
+the 5.003 version that has been officially released!  It will probably work
+with Perl 5.003_05 and later.
+
+The Perl patches for Vim were made by:
+	Sven Verdoolaege <skimo@breughel.ufsia.ac.be>
+	Matt Gerassimof
+
+Perl for MS-Windows (and other platforms) can be found at:
+	http://www.perl.org/
+The ActiveState one should work, Strawberry Perl is a good alternative.
+
+==============================================================================
+3. Using the Perl interface				*perl-using*
+
+							*:perl* *:pe*
+:pe[rl] {cmd}		Execute Perl command {cmd}.  The current package
+			is "main".  Simple example to test if `:perl` is
+			working: >
+				:perl VIM::Msg("Hello")
+
+:pe[rl] << [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.  Using
+			'.' helps when inside a function, because "$i;" looks
+			like the start of an |:insert| command to Vim.
+
+			This form of the |:perl| command is mainly useful for
+			including perl code in vim scripts.
+			Note: This command doesn't work when the Perl feature
+			wasn't compiled in.  To avoid errors, see
+			|script-here|.
+
+
+Example vim script: >
+
+	function! WhitePearl()
+	perl << EOF
+		VIM::Msg("pearls are nice for necklaces");
+		VIM::Msg("rubys for rings");
+		VIM::Msg("pythons for bags");
+		VIM::Msg("tcls????");
+	EOF
+	endfunction
+<
+To see what version of Perl you have: >
+	:perl print $^V
+<
+
+							*:perldo* *:perld*
+:[range]perld[o] {cmd}	Execute Perl command {cmd} for each line in the
+			[range], with $_ being set to the text of each line in
+			turn, without a trailing <EOL>.  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,$".
+
+Here are some things you can try: >
+
+  :perl $a=1
+  :perldo $_ = reverse($_);1
+  :perl VIM::Msg("hello")
+  :perl $line = $curbuf->Get(42)
+<							*E299*
+Executing Perl commands in the |sandbox| is limited.  ":perldo" will not be
+possible at all.  ":perl" will be evaluated in the Safe environment, if
+possible.
+
+
+							*perl-overview*
+Here is an overview of the functions that are available to Perl: >
+
+  :perl VIM::Msg("Text")		# displays a message
+  :perl VIM::Msg("Wrong!", "ErrorMsg")	# displays an error message
+  :perl VIM::Msg("remark", "Comment")	# displays a highlighted message
+  :perl VIM::SetOption("ai")		# sets a vim option
+  :perl $nbuf = VIM::Buffers()		# returns the number of buffers
+  :perl @buflist = VIM::Buffers()	# returns array of all buffers
+  :perl $mybuf = (VIM::Buffers('qq.c'))[0] # returns buffer object for 'qq.c'
+  :perl @winlist = VIM::Windows()	# returns array of all windows
+  :perl $nwin = VIM::Windows()		# returns the number of windows
+  :perl ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1
+  :perl ($success, $v) = VIM::Eval('&xyz')  # $v: '' and $success: 0
+  :perl $v = VIM::Eval('expand("<cfile>")') # expands <cfile>
+  :perl $curwin->SetHeight(10)		# sets the window height
+  :perl @pos = $curwin->Cursor()	# returns (row, col) array
+  :perl @pos = (10, 10)
+  :perl $curwin->Cursor(@pos)		# sets cursor to @pos
+  :perl $curwin->Cursor(10,10)		# sets cursor to row 10 col 10
+  :perl $mybuf = $curwin->Buffer()	# returns the buffer object for window
+  :perl $curbuf->Name()			# returns buffer name
+  :perl $curbuf->Number()		# returns buffer number
+  :perl $curbuf->Count()		# returns the number of lines
+  :perl $l = $curbuf->Get(10)		# returns line 10
+  :perl @l = $curbuf->Get(1 .. 5)	# returns lines 1 through 5
+  :perl $curbuf->Delete(10)		# deletes line 10
+  :perl $curbuf->Delete(10, 20)		# delete lines 10 through 20
+  :perl $curbuf->Append(10, "Line")	# appends a line
+  :perl $curbuf->Append(10, "Line1", "Line2", "Line3") # appends 3 lines
+  :perl @l = ("L1", "L2", "L3")
+  :perl $curbuf->Append(10, @l)		# appends L1, L2 and L3
+  :perl $curbuf->Set(10, "Line")	# replaces line 10
+  :perl $curbuf->Set(10, "Line1", "Line2")	# replaces lines 10 and 11
+  :perl $curbuf->Set(10, @l)		# replaces 3 lines
+<
+							*perl-Msg*
+VIM::Msg({msg}, {group}?)
+			Displays the message {msg}.  The optional {group}
+			argument specifies a highlight group for Vim to use
+			for the message.
+
+							*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.  Using it anyway may crash Vim.
+
+							*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.  Using it anyway may crash Vim.
+
+							*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.
+
+							*perl-SetHeight*
+Window->SetHeight({height})
+			Sets the Window height to {height}, within screen
+			limits.
+
+							*perl-GetCursor*
+Window->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.
+
+Window->Buffer()					*perl-Buffer*
+			Returns the Buffer object corresponding to the given
+			Window.
+
+							*perl-Name*
+Buffer->Name()		Returns the filename for the Buffer.
+
+							*perl-Number*
+Buffer->Number()	Returns the number of the Buffer.
+
+							*perl-Count*
+Buffer->Count()		Returns the number of lines in the Buffer.
+
+							*perl-Get*
+Buffer->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-Delete*
+Buffer->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-Append*
+Buffer->Append({lnum}, {line}, {line}?, ...)
+			Appends each {line} string after Buffer line {lnum}.
+			The list of {line}s can be an array.
+
+							*perl-Set*
+Buffer->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.
+
+$main::curwin
+			The current window object.
+
+$main::curbuf
+			The current buffer object.
+
+
+							*script-here*
+When using a script language in-line, you might want to skip this when the
+language isn't supported.  >
+   if has('perl')
+     perl << EOF
+       print 'perl works'
+   EOF
+   endif
+Note that "EOF" must be at the start of the line without preceding white
+space.
+
+==============================================================================
+4. Dynamic loading					*perl-dynamic*
+
+On MS-Windows and Unix the Perl library can be loaded dynamically.  The
+|:version| output then includes |+perl/dyn|.
+
+This means that Vim will search for the Perl DLL or shared library file only
+when needed.  When you don't use the Perl interface you don't need it, thus
+you can use Vim without this file.
+
+
+MS-Windows ~
+
+You can download Perl from http://www.perl.org.  The one from ActiveState was
+used for building Vim.
+
+To use the Perl interface the Perl DLL must be in your search path.
+If Vim reports it cannot find the perl512.dll, make sure your $PATH includes
+the directory where it is located.  The Perl installer normally does that.
+In a console window type "path" to see what directories are used.  The
+'perldll' option can be also used to specify the Perl DLL.
+
+The name of the DLL must match the Perl version Vim was compiled with.
+Currently the name is "perl512.dll".  That is for Perl 5.12.  To know for
+sure edit "gvim.exe" and search for "perl\d*.dll\c".
+
+
+Unix ~
+
+The 'perldll' option can be used to specify the Perl shared library file
+instead of DYNAMIC_PERL_DLL file what was specified at compile time.  The
+version of the shared library must match the Perl version Vim was compiled
+with.
+
+Note: If you are building Perl locally, you have to use a version compiled
+with threading support for it for Vim to successfully link against it. You can
+use the `-Dusethreads` flags when configuring Perl, and check that a Perl
+binary has it enabled by running `perl -V` and verify that `USE_ITHREADS` is
+under "Compile-time options".
+
+==============================================================================
+ vim:tw=78:ts=8:noet:ft=help:norl: