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