if_perl.txt (8819B)
1 *if_perl.txt* Nvim 2 3 4 VIM REFERENCE MANUAL by Jacques Germishuys 5 6 The perl Interface to Vim *if_perl* *perl* 7 8 See |provider-perl| for more information. 9 10 Type |gO| to see the table of contents. 11 12 ============================================================================== 13 1. Commands *perl-commands* 14 15 *:perl* 16 :[range]perl {stmt} 17 Execute perl statement {stmt}. The current package is 18 "main". A simple check if the `:perl` command is 19 working: > 20 :perl print "Hello" 21 22 :[range]perl << [trim] [{endmarker}] 23 {script} 24 {endmarker} 25 Execute perl script {script}. 26 The {endmarker} after {script} must NOT be preceded by 27 any white space. 28 29 If [endmarker] is omitted, it defaults to a dot '.' 30 like for the |:append| and |:insert| commands. 31 32 Useful for including perl code in Vim scripts. 33 Requires perl, see |script-here|. 34 35 Example: > 36 function! MyVimMethod() 37 perl << EOF 38 sub my_vim_method 39 { 40 print "Hello World!\n"; 41 } 42 EOF 43 endfunction 44 45 To see what version of perl you have: > 46 47 :perl print $^V 48 < 49 *:perldo* 50 :[range]perldo {cmd} Execute perl command {cmd} for each line in the[range], 51 with $_ being set to the test of each line in turn, 52 without a trailing <EOL>. In addition to $_, $line 53 and $linenr is also set to the line content and line 54 number respectively. Setting $_ will change the text, 55 but note that it is not possible to add or delete 56 lines using this command. 57 The default for [range] is the whole file: "1,$". 58 59 Examples: 60 > 61 :perldo $_ = reverse($_); 62 :perldo $_ = "".$linenr." => $line"; 63 64 One can use `:perldo` in conjunction with `:perl` to filter a range using 65 perl. For example: > 66 67 :perl << EOF 68 sub perl_vim_string_replace 69 { 70 my $line = shift; 71 my $needle = $vim->eval('@a'); 72 my $replacement = $vim->eval('@b'); 73 $line =~ s/$needle/$replacement/g; 74 return $line; 75 } 76 EOF 77 :let @a='somevalue' 78 :let @b='newvalue' 79 :'<,'>perldo $_ = perl_vim_string_replace($_) 80 < 81 *:perlfile* 82 :[range]perlfile {file} 83 Execute the perl script in {file}. The whole 84 argument is used as a single file name. 85 86 Both of these commands do essentially the same thing - they execute a piece of 87 perl code, with the "current range" set to the given line range. 88 89 In the case of :perl, the code to execute is in the command-line. 90 In the case of :perlfile, the code to execute is the contents of the given file. 91 92 perl commands cannot be used in the |sandbox|. 93 94 To pass arguments you need to set @ARGV explicitly. Example: > 95 96 :perl @ARGV = ("foo", "bar"); 97 :perlfile myscript.pl 98 99 Here are some examples *perl-examples* > 100 101 :perl print "Hello" 102 :perl $current->line (uc ($current->line)) 103 :perl my $str = $current->buffer->[42]; print "Set \$str to: $str" 104 105 Note that changes (such as the "use" statements) persist from one command 106 to the next. 107 108 ============================================================================== 109 2. The VIM module *perl-vim* 110 111 Perl code gets all of its access to Nvim via the "VIM" module. 112 113 Overview > 114 print "Hello" # displays a message 115 VIM::Msg("Hello") # displays a message 116 VIM::SetOption("ai") # sets a vim option 117 $nbuf = VIM::Buffers() # returns the number of buffers 118 @buflist = VIM::Buffers() # returns array of all buffers 119 $mybuf = (VIM::Buffers('a.c'))[0] # returns buffer object for 'a.c' 120 @winlist = VIM::Windows() # returns array of all windows 121 $nwin = VIM::Windows() # returns the number of windows 122 ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1 123 ($success, $v) = VIM::Eval('&xyz') # $v: '' and $success: 0 124 $v = VIM::Eval('expand("<cfile>")') # expands <cfile> 125 $curwin->SetHeight(10) # sets the window height 126 @pos = $curwin->Cursor() # returns (row, col) array 127 @pos = (10, 10) 128 $curwin->Cursor(@pos) # sets cursor to @pos 129 $curwin->Cursor(10,10) # sets cursor to row 10 col 10 130 $mybuf = $curwin->Buffer() # returns the buffer object for window 131 $curbuf->Name() # returns buffer name 132 $curbuf->Number() # returns buffer number 133 $curbuf->Count() # returns the number of lines 134 $l = $curbuf->Get(10) # returns line 10 135 @l = $curbuf->Get(1 .. 5) # returns lines 1 through 5 136 $curbuf->Delete(10) # deletes line 10 137 $curbuf->Delete(10, 20) # delete lines 10 through 20 138 $curbuf->Append(10, "Line") # appends a line 139 $curbuf->Append(10, "L1", "L2", "L3") # appends 3 lines 140 @l = ("L1", "L2", "L3") 141 $curbuf->Append(10, @l) # appends L1, L2 and L3 142 $curbuf->Set(10, "Line") # replaces line 10 143 $curbuf->Set(10, "Line1", "Line2") # replaces lines 10 and 11 144 $curbuf->Set(10, @l) # replaces 3 lines 145 146 Module Functions: 147 148 *perl-Msg* 149 VIM::Msg({msg}) 150 Displays the message {msg}. 151 152 *perl-SetOption* 153 VIM::SetOption({arg}) Sets a vim option. {arg} can be any argument that the 154 ":set" command accepts. Note that this means that no 155 spaces are allowed in the argument! See |:set|. 156 157 *perl-Buffers* 158 VIM::Buffers([{bn}...]) With no arguments, returns a list of all the buffers 159 in an array context or returns the number of buffers 160 in a scalar context. For a list of buffer names or 161 numbers {bn}, returns a list of the buffers matching 162 {bn}, using the same rules as Vim's internal 163 |bufname()| function. 164 WARNING: the list becomes invalid when |:bwipe| is 165 used. 166 167 *perl-Windows* 168 VIM::Windows([{wn}...]) With no arguments, returns a list of all the windows 169 in an array context or returns the number of windows 170 in a scalar context. For a list of window numbers 171 {wn}, returns a list of the windows with those 172 numbers. 173 WARNING: the list becomes invalid when a window is 174 closed. 175 176 *perl-DoCommand* 177 VIM::DoCommand({cmd}) Executes Ex command {cmd}. 178 179 *perl-Eval* 180 VIM::Eval({expr}) Evaluates {expr} and returns (success, value) in list 181 context or just value in scalar context. 182 success=1 indicates that val contains the value of 183 {expr}; success=0 indicates a failure to evaluate 184 the expression. '@x' returns the contents of register 185 x, '&x' returns the value of option x, 'x' returns the 186 value of internal |variables| x, and '$x' is equivalent 187 to perl's $ENV{x}. All |functions| accessible from 188 the command-line are valid for {expr}. 189 A |List| is turned into a string by joining the items 190 and inserting line breaks. 191 192 *perl-Blob* 193 VIM::Blob({expr}) Return Blob literal string 0zXXXX from scalar value. 194 195 ============================================================================== 196 3. VIM::Buffer objects *perl-buffer* 197 198 Methods: 199 200 *perl-Buffer-Name* 201 Name() Returns the filename for the Buffer. 202 203 *perl-Buffer-Number* 204 Number() Returns the number of the Buffer. 205 206 *perl-Buffer-Count* 207 Count() Returns the number of lines in the Buffer. 208 209 *perl-Buffer-Get* 210 Get({lnum}, {lnum}?, ...) 211 Returns a text string of line {lnum} in the Buffer 212 for each {lnum} specified. An array can be passed 213 with a list of {lnum}'s specified. 214 215 *perl-Buffer-Delete* 216 Delete({lnum}, {lnum}?) 217 Deletes line {lnum} in the Buffer. With the second 218 {lnum}, deletes the range of lines from the first 219 {lnum} to the second {lnum}. 220 221 *perl-Buffer-Append* 222 Append({lnum}, {line}, {line}?, ...) 223 Appends each {line} string after Buffer line {lnum}. 224 The list of {line}s can be an array. 225 226 *perl-Buffer-Set* 227 Set({lnum}, {line}, {line}?, ...) 228 Replaces one or more Buffer lines with specified 229 {lines}s, starting at Buffer line {lnum}. The list of 230 {line}s can be an array. If the arguments are 231 invalid, replacement does not occur. 232 233 ============================================================================== 234 4. VIM::Window objects *perl-window* 235 236 Methods: 237 *perl-Window-SetHeight* 238 SetHeight({height}) 239 Sets the Window height to {height}, within screen 240 limits. 241 242 *perl-Window-GetCursor* 243 Cursor({row}?, {col}?) 244 With no arguments, returns a (row, col) array for the 245 current cursor position in the Window. With {row} and 246 {col} arguments, sets the Window's cursor position to 247 {row} and {col}. Note that {col} is numbered from 0, 248 Perl-fashion, and thus is one less than the value in 249 Vim's ruler. 250 251 Buffer() *perl-Window-Buffer* 252 Returns the Buffer object corresponding to the given 253 Window. 254 255 ============================================================================== 256 5. Lexical variables *perl-globals* 257 258 There are multiple lexical variables. 259 260 $curwin The current Window object. 261 $curbuf The current Buffer object. 262 $vim A Neovim::Ext object. 263 $nvim The same as $nvim. 264 $current A Neovim::Ext::Current object. 265 266 These are also available via the "main" package: 267 268 $main::curwin The current Window object. 269 $main::curbuf The current Buffer object. 270 271 vim:tw=78:ts=8:noet:ft=help:norl: