if_ruby.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Shugo MaedaTheRubyInterface to VimrubyRuby1. Commandsruby-commands2. The Vim moduleruby-vim3. Vim::Bufferobjectsruby-buffer4. Vim::Windowobjectsruby-window5. Globalvariablesruby-globals6.rubyeval() Vim functionruby-rubyeval7. Dynamic loadingruby-dynamicE266E267E268E269E270E271E272E273{only available when Vim was compiled with the |+ruby| feature}Thehome page forrubyishttp://www.ruby-lang.org/. You can find links fordownloadingRuby there.==============================================================================1. Commandsruby-commands:ruby:rub:rub[y]{cmd}ExecuteRuby command{cmd}.A command to tryit out::ruby print "Hello":rub[y]<<[trim] [{endmarker}]{script}{endmarker}ExecuteRubyscript{script}.If[endmarker]is omitted,it defaults toa dot '.'like for the:append and:insert commands. Referto:let-heredoc for more information.This form of the:ruby commandis mainly useful forincludingruby code in vim scripts.Note: This command doesn't work when theRuby featurewasn't compiled in. To avoid errors, seescript-here.Example Vim script:function! RedGem()ruby << EOFclass Garnetdef initialize(s)@buffer = Vim::Buffer.currentvimputs(s)enddef vimputs(s)@buffer.append(@buffer.count,s)endendgem = Garnet.new("pretty")EOFendfunctionTo see what version ofRuby you have::ruby print RUBY_VERSION:rubydo:rubydE265:[range]rubyd[o]{cmd}EvaluateRuby command{cmd} for each line in the[range], with $_ being set to the text of each line inturn, withouta trailing<EOL>. Setting $_ willchange the text, butnote thatitis not possible toadd or delete lines using this command.The default for[range]is the whole file: "1,$".:rubyfile:rubyf:rubyf[ile]{file}Execute theRubyscript in{file}. Thisis the sameas `:ruby load'file'`, but allows file name completion.ExecutingRuby commandsis not possible in thesandbox.==============================================================================2. The Vim moduleruby-vimRuby code gets all of its access to vim via the "Vim" module.Overview:print "Hello" # displays a messageVim.command(cmd) # execute an Ex commandnum = Vim::Window.count # gets the number of windowsw = Vim::Window[n] # gets window "n"cw = Vim::Window.current # gets the current windownum = Vim::Buffer.count # gets the number of buffersb = Vim::Buffer[n] # gets buffer "n"cb = Vim::Buffer.current # gets the current bufferw.height = lines # sets the window heightw.cursor = [row, col] # sets the window cursor positionpos = w.cursor # gets an array [row, col]name = b.name # gets the buffer file nameline = b[n] # gets a line from the buffernum = b.count # gets the number of linesb[n] = str # sets a line in the bufferb.delete(n) # deletes a lineb.append(n, str) # appends a line after nline = Vim::Buffer.current.line # gets the current linenum = Vim::Buffer.current.line_number # gets the current line numberVim::Buffer.current.line = "test" # sets the current line numberModule Functions:ruby-messageVim::message({msg})Displays the message{msg}.ruby-blobVim::blob({arg})ReturnBlob literalstring from{arg}.ruby-set_optionVim::set_option({arg})Setsa vim option.{arg} can be any argument that the ":set" commandaccepts.Note that this means that no spaces are allowed in theargument! See:set.ruby-commandVim::command({cmd})ExecutesEx command{cmd}.ruby-evaluateVim::evaluate({expr})Evaluates{expr} using the vim internalexpression evaluator (seeexpression). Returns theexpression result as:-aInteger if the Vimexpression evaluates toa number-aFloat if the Vimexpression evaluates toa float-aString if the Vimexpression evaluates toastring-a Array if the Vimexpression evaluates toa Vimlist-a Hash if the Vimexpression evaluates toa Vim dictionaryDictionaries and lists are recursively expanded.==============================================================================3. Vim::Bufferobjectsruby-bufferVim::Bufferobjects represent vim buffers.Class Methods:currentReturns the current buffer object.countReturns the number of buffers.self[{n}]Returns the bufferobject for the number{n}. The firstnumberis 0.Methods:nameReturns the full name of the buffer.numberReturns the number of the buffer.countReturns the number of lines.lengthReturns the number of lines.self[{n}]Returnsa line from the buffer.{n}is the line number.self[{n}]={str}Setsa line in the buffer.{n}is the line number.delete({n})Deletesa line from the buffer.{n}is the line number.append({n},{str})Appendsa line after the line{n}.lineReturns the current line of the buffer if the bufferisactive.line={str} Sets the current line of the buffer if the bufferis active.line_number Returns the number of the current line if the bufferisactive.==============================================================================4. Vim::Windowobjectsruby-windowVim::Windowobjects represent vim windows.Class Methods:currentReturns the currentwindow object.countReturns the number of windows.self[{n}]Returns thewindowobject for the number{n}. The firstnumberis 0.Methods:bufferReturns the buffer displayed in the window.heightReturns the height of the window.height={n}Sets thewindow height to{n}.widthReturns the width of the window.width={n}Sets thewindow width to{n}.cursorReturnsa [row, col] array for the cursor position.First line numberis 1 and first column numberis 0.cursor= [{row},{col}]Sets the cursor position to{row} and{col}.==============================================================================5. Globalvariablesruby-globalsThere are two global variables.$curwinThe currentwindow object.$curbufThe current buffer object.==============================================================================6.rubyeval() Vim functionruby-rubyevalTo facilitate bi-directional interface, you can userubyeval() function toevaluateRuby expressions and pass their values to Vim script.TheRuby value "true", "false" and "nil" are converted to v:true,v:false andv:null, respectively.==============================================================================7. Dynamic loadingruby-dynamicOnMS-Windows andUnix theRuby library can be loaded dynamically. The:version output then includes+ruby/dyn.This means that Vim will search for theRuby DLL file or shared library onlywhen needed. When you don't use theRubyinterface you don't need it, thusyou can use Vim even though this library fileis not on your system.MS-WindowsYou need toinstall the right version ofRuby for this to work. You can findthe package todownload from:http://rubyinstaller.org/downloads/Currently thatis rubyinstaller-2.2.5.exeTo use theRubyinterface theRuby DLLmust be in your search path. Inaconsolewindow type "path" to see what directories are used. The'rubydll'option can be also used to specify theRuby DLL.The name of the DLLmust match theRuby version Vim was compiled with.Currently the nameis "msvcrt-ruby220.dll". Thatis forRuby 2.2.X. To knowfor sure edit "gvim.exe" and search for "ruby\d*.dll\c".If you want to build Vim with RubyInstaller 1.9 or 2.X using MSVC, you needsome tricks. See the src/INSTALLpc.txt for detail.If Vimis built with RubyInstaller 2.4 or later, you may also need to add"C:\Ruby<version>\bin\ruby_builtin_dlls" to the PATH environment variable.UnixThe'rubydll' option can be used to specify theRuby shared library fileinstead of DYNAMIC_RUBY_DLL file what was specifiedat compile time. Theversion of the shared librarymust match theRuby version Vim was compiledwith.============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: