if_ruby.txt (8517B)
1 *if_ruby.txt* For Vim version 9.2. Last change: 2026 Feb 14 2 3 4 VIM REFERENCE MANUAL by Shugo Maeda 5 6 7 The Ruby Interface to Vim *ruby* *Ruby* 8 9 10 1. Commands |ruby-commands| 11 2. The Vim module |ruby-vim| 12 3. Vim::Buffer objects |ruby-buffer| 13 4. Vim::Window objects |ruby-window| 14 5. Global variables |ruby-globals| 15 6. rubyeval() Vim function |ruby-rubyeval| 16 7. Dynamic loading |ruby-dynamic| 17 18 *E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273* 19 20 {only available when Vim was compiled with the |+ruby| feature} 21 22 The home page for ruby is http://www.ruby-lang.org/. You can find links for 23 downloading Ruby there. 24 25 ============================================================================== 26 1. Commands *ruby-commands* 27 28 *:ruby* *:rub* 29 :rub[y] {cmd} Execute Ruby command {cmd}. A command to try it out: > 30 :ruby print "Hello" 31 32 :rub[y] << [trim] [{endmarker}] 33 {script} 34 {endmarker} 35 Execute Ruby script {script}. 36 37 If [endmarker] is omitted, it defaults to a dot '.' 38 like for the |:append| and |:insert| commands. Refer 39 to |:let-heredoc| for more information. 40 41 42 This form of the |:ruby| command is mainly useful for 43 including ruby code in vim scripts. 44 45 Note: This command doesn't work when the Ruby feature 46 wasn't compiled in. To avoid errors, see 47 |script-here|. 48 49 Example Vim script: > 50 51 function! RedGem() 52 ruby << EOF 53 class Garnet 54 def initialize(s) 55 @buffer = Vim::Buffer.current 56 vimputs(s) 57 end 58 def vimputs(s) 59 @buffer.append(@buffer.count,s) 60 end 61 end 62 gem = Garnet.new("pretty") 63 EOF 64 endfunction 65 < 66 To see what version of Ruby you have: > 67 :ruby print RUBY_VERSION 68 < 69 70 *:rubydo* *:rubyd* *E265* 71 :[range]rubyd[o] {cmd} Evaluate Ruby command {cmd} for each line in the 72 [range], with $_ being set to the text of each line in 73 turn, without a trailing <EOL>. Setting $_ will 74 change the text, but note that it is not possible to 75 add or delete lines using this command. 76 The default for [range] is the whole file: "1,$". 77 78 *:rubyfile* *:rubyf* 79 :rubyf[ile] {file} Execute the Ruby script in {file}. This is the same 80 as `:ruby load 'file'`, but allows file name completion. 81 82 Executing Ruby commands is not possible in the |sandbox|. 83 84 ============================================================================== 85 2. The Vim module *ruby-vim* 86 87 Ruby code gets all of its access to vim via the "Vim" module. 88 89 Overview: > 90 print "Hello" # displays a message 91 Vim.command(cmd) # execute an Ex command 92 num = Vim::Window.count # gets the number of windows 93 w = Vim::Window[n] # gets window "n" 94 cw = Vim::Window.current # gets the current window 95 num = Vim::Buffer.count # gets the number of buffers 96 b = Vim::Buffer[n] # gets buffer "n" 97 cb = Vim::Buffer.current # gets the current buffer 98 w.height = lines # sets the window height 99 w.cursor = [row, col] # sets the window cursor position 100 pos = w.cursor # gets an array [row, col] 101 name = b.name # gets the buffer file name 102 line = b[n] # gets a line from the buffer 103 num = b.count # gets the number of lines 104 b[n] = str # sets a line in the buffer 105 b.delete(n) # deletes a line 106 b.append(n, str) # appends a line after n 107 line = Vim::Buffer.current.line # gets the current line 108 num = Vim::Buffer.current.line_number # gets the current line number 109 Vim::Buffer.current.line = "test" # sets the current line number 110 < 111 112 Module Functions: 113 114 *ruby-message* 115 Vim::message({msg}) 116 Displays the message {msg}. 117 118 *ruby-blob* 119 Vim::blob({arg}) 120 Return |Blob| literal string from {arg}. 121 122 *ruby-set_option* 123 Vim::set_option({arg}) 124 Sets a vim option. {arg} can be any argument that the ":set" command 125 accepts. Note that this means that no spaces are allowed in the 126 argument! See |:set|. 127 128 *ruby-command* 129 Vim::command({cmd}) 130 Executes Ex command {cmd}. 131 132 *ruby-evaluate* 133 Vim::evaluate({expr}) 134 Evaluates {expr} using the vim internal expression evaluator (see 135 |expression|). Returns the expression result as: 136 - a Integer if the Vim expression evaluates to a number 137 - a Float if the Vim expression evaluates to a float 138 - a String if the Vim expression evaluates to a string 139 - a Array if the Vim expression evaluates to a Vim list 140 - a Hash if the Vim expression evaluates to a Vim dictionary 141 Dictionaries and lists are recursively expanded. 142 143 ============================================================================== 144 3. Vim::Buffer objects *ruby-buffer* 145 146 Vim::Buffer objects represent vim buffers. 147 148 Class Methods: 149 150 current Returns the current buffer object. 151 count Returns the number of buffers. 152 self[{n}] Returns the buffer object for the number {n}. The first 153 number is 0. 154 155 Methods: 156 157 name Returns the full name of the buffer. 158 number Returns the number of the buffer. 159 count Returns the number of lines. 160 length Returns the number of lines. 161 self[{n}] Returns a line from the buffer. {n} is the line number. 162 self[{n}] = {str} 163 Sets a line in the buffer. {n} is the line number. 164 delete({n}) Deletes a line from the buffer. {n} is the line number. 165 append({n}, {str}) 166 Appends a line after the line {n}. 167 line Returns the current line of the buffer if the buffer is 168 active. 169 line = {str} Sets the current line of the buffer if the buffer is active. 170 line_number Returns the number of the current line if the buffer is 171 active. 172 173 ============================================================================== 174 4. Vim::Window objects *ruby-window* 175 176 Vim::Window objects represent vim windows. 177 178 Class Methods: 179 180 current Returns the current window object. 181 count Returns the number of windows. 182 self[{n}] Returns the window object for the number {n}. The first 183 number is 0. 184 185 Methods: 186 187 buffer Returns the buffer displayed in the window. 188 height Returns the height of the window. 189 height = {n} Sets the window height to {n}. 190 width Returns the width of the window. 191 width = {n} Sets the window width to {n}. 192 cursor Returns a [row, col] array for the cursor position. 193 First line number is 1 and first column number is 0. 194 cursor = [{row}, {col}] 195 Sets the cursor position to {row} and {col}. 196 197 ============================================================================== 198 5. Global variables *ruby-globals* 199 200 There are two global variables. 201 202 $curwin The current window object. 203 $curbuf The current buffer object. 204 205 ============================================================================== 206 6. rubyeval() Vim function *ruby-rubyeval* 207 208 To facilitate bi-directional interface, you can use |rubyeval()| function to 209 evaluate Ruby expressions and pass their values to Vim script. 210 211 The Ruby value "true", "false" and "nil" are converted to v:true, v:false and 212 v:null, respectively. 213 214 ============================================================================== 215 7. Dynamic loading *ruby-dynamic* 216 217 On MS-Windows and Unix the Ruby library can be loaded dynamically. The 218 |:version| output then includes |+ruby/dyn|. 219 220 This means that Vim will search for the Ruby DLL file or shared library only 221 when needed. When you don't use the Ruby interface you don't need it, thus 222 you can use Vim even though this library file is not on your system. 223 224 225 MS-Windows ~ 226 227 You need to install the right version of Ruby for this to work. You can find 228 the package to download from: 229 http://rubyinstaller.org/downloads/ 230 Currently that is rubyinstaller-2.2.5.exe 231 232 To use the Ruby interface the Ruby DLL must be in your search path. In a 233 console window type "path" to see what directories are used. The 'rubydll' 234 option can be also used to specify the Ruby DLL. 235 236 The name of the DLL must match the Ruby version Vim was compiled with. 237 Currently the name is "msvcrt-ruby220.dll". That is for Ruby 2.2.X. To know 238 for sure edit "gvim.exe" and search for "ruby\d*.dll\c". 239 240 If you want to build Vim with RubyInstaller 1.9 or 2.X using MSVC, you need 241 some tricks. See the src/INSTALLpc.txt for detail. 242 243 If Vim is built with RubyInstaller 2.4 or later, you may also need to add 244 "C:\Ruby<version>\bin\ruby_builtin_dlls" to the PATH environment variable. 245 246 247 Unix ~ 248 249 The 'rubydll' option can be used to specify the Ruby shared library file 250 instead of DYNAMIC_RUBY_DLL file what was specified at compile time. The 251 version of the shared library must match the Ruby version Vim was compiled 252 with. 253 254 ============================================================================== 255 vim:tw=78:ts=8:noet:ft=help:norl: