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