1*if_ruby.txt* For Vim version 8.0. Last change: 2016 Sep 01 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. Dynamic loading |ruby-dynamic| 15 16{Vi does not have any of these commands} 17 *E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273* 18 19The Ruby interface only works 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-set_option* 114Vim::set_option({arg}) 115 Sets a vim option. {arg} can be any argument that the ":set" command 116 accepts. Note that this means that no spaces are allowed in the 117 argument! See |:set|. 118 119 *ruby-command* 120Vim::command({cmd}) 121 Executes Ex command {cmd}. 122 123 *ruby-evaluate* 124Vim::evaluate({expr}) 125 Evaluates {expr} using the vim internal expression evaluator (see 126 |expression|). Returns the expression result as: 127 - a Integer if the Vim expression evaluates to a number 128 - a Float if the Vim expression evaluates to a float 129 - a String if the Vim expression evaluates to a string 130 - a Array if the Vim expression evaluates to a Vim list 131 - a Hash if the Vim expression evaluates to a Vim dictionary 132 Dictionaries and lists are recursively expanded. 133 134============================================================================== 1353. Vim::Buffer objects *ruby-buffer* 136 137Vim::Buffer objects represent vim buffers. 138 139Class Methods: 140 141current Returns the current buffer object. 142count Returns the number of buffers. 143self[{n}] Returns the buffer object for the number {n}. The first number 144 is 0. 145 146Methods: 147 148name Returns the name of the buffer. 149number Returns the number of the buffer. 150count Returns the number of lines. 151length Returns the number of lines. 152self[{n}] Returns a line from the buffer. {n} is the line number. 153self[{n}] = {str} 154 Sets a line in the buffer. {n} is the line number. 155delete({n}) Deletes a line from the buffer. {n} is the line number. 156append({n}, {str}) 157 Appends a line after the line {n}. 158line Returns the current line of the buffer if the buffer is 159 active. 160line = {str} Sets the current line of the buffer if the buffer is active. 161line_number Returns the number of the current line if the buffer is 162 active. 163 164============================================================================== 1654. Vim::Window objects *ruby-window* 166 167Vim::Window objects represent vim windows. 168 169Class Methods: 170 171current Returns the current window object. 172count Returns the number of windows. 173self[{n}] Returns the window object for the number {n}. The first number 174 is 0. 175 176Methods: 177 178buffer Returns the buffer displayed in the window. 179height Returns the height of the window. 180height = {n} Sets the window height to {n}. 181width Returns the width of the window. 182width = {n} Sets the window width to {n}. 183cursor Returns a [row, col] array for the cursor position. 184cursor = [{row}, {col}] 185 Sets the cursor position to {row} and {col}. 186 187============================================================================== 1885. Global variables *ruby-globals* 189 190There are two global variables. 191 192$curwin The current window object. 193$curbuf The current buffer object. 194 195============================================================================== 1966. Dynamic loading *ruby-dynamic* 197 198On MS-Windows and Unix the Ruby library can be loaded dynamically. The 199|:version| output then includes |+ruby/dyn|. 200 201This means that Vim will search for the Ruby DLL file or shared library only 202when needed. When you don't use the Ruby interface you don't need it, thus 203you can use Vim even though this library file is not on your system. 204 205 206MS-Windows ~ 207 208You need to install the right version of Ruby for this to work. You can find 209the package to download from: 210http://rubyinstaller.org/downloads/ 211Currently that is rubyinstaller-2.2.5.exe 212 213To use the Ruby interface the Ruby DLL must be in your search path. In a 214console window type "path" to see what directories are used. The 'rubydll' 215option can be also used to specify the Ruby DLL. 216 217The name of the DLL must match the Ruby version Vim was compiled with. 218Currently the name is "msvcrt-ruby220.dll". That is for Ruby 2.2.X. To know 219for sure edit "gvim.exe" and search for "ruby\d*.dll\c". 220 221If you want to build Vim with RubyInstaller 1.9 or 2.X using MSVC, you need 222some tricks. See the src/INSTALLpc.txt for detail. 223 224 225Unix ~ 226 227The 'rubydll' option can be used to specify the Ruby shared library file 228instead of DYNAMIC_RUBY_DLL file what was specified at compile time. The 229version of the shared library must match the Ruby version Vim was compiled 230with. 231 232============================================================================== 233 vim:tw=78:ts=8:ft=help:norl: 234