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