codekingpro/portable-devtools

1*if_ruby.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Shugo Maeda5 6 7The Ruby Interface to Vim				*ruby* *Ruby*8 9 101. Commands			|ruby-commands|112. The Vim module		|ruby-vim|123. Vim::Buffer objects		|ruby-buffer|134. Vim::Window objects		|ruby-window|145. Global variables		|ruby-globals|156. rubyeval() Vim function	|ruby-rubyeval|167. Dynamic loading		|ruby-dynamic|17 18			*E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273*19 20{only available when Vim was compiled with the |+ruby| feature}21 22The home page for ruby is http://www.ruby-lang.org/.  You can find links for23downloading 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] << [trim] [{endmarker}]33{script}34{endmarker}35			Execute Ruby script {script}.36 37			If [endmarker] is omitted, it defaults to a dot '.'38			like for the |:append| and |:insert| commands.  Refer39			to |:let-heredoc| for more information.40 41 42			This form of the |:ruby| command is mainly useful for43			including ruby code in vim scripts.44 45			Note: This command doesn't work when the Ruby feature46			wasn't compiled in.  To avoid errors, see47			|script-here|.48 49Example Vim script: >50 51	function! RedGem()52	ruby << EOF53	class Garnet54		def initialize(s)55			@buffer = Vim::Buffer.current56			vimputs(s)57		end58		def vimputs(s)59			@buffer.append(@buffer.count,s)60		end61	end62	gem = Garnet.new("pretty")63	EOF64	endfunction65<66To see what version of Ruby you have: >67	:ruby print RUBY_VERSION68<69 70						*:rubydo* *:rubyd* *E265*71:[range]rubyd[o] {cmd}	Evaluate Ruby command {cmd} for each line in the72			[range], with $_ being set to the text of each line in73			turn, without a trailing <EOL>.  Setting $_ will74			change the text, but note that it is not possible to75			add or delete lines using this command.76			The default for [range] is the whole file: "1,$".77 78							*:rubyfile* *:rubyf*79:rubyf[ile] {file}	Execute the Ruby script in {file}.  This is the same80			as `:ruby load 'file'`, but allows file name completion.81 82Executing Ruby commands is not possible in the |sandbox|.83 84==============================================================================852. The Vim module					*ruby-vim*86 87Ruby code gets all of its access to vim via the "Vim" module.88 89Overview: >90	print "Hello"			      # displays a message91	Vim.command(cmd)		      # execute an Ex command92	num = Vim::Window.count		      # gets the number of windows93	w = Vim::Window[n]		      # gets window "n"94	cw = Vim::Window.current	      # gets the current window95	num = Vim::Buffer.count		      # gets the number of buffers96	b = Vim::Buffer[n]		      # gets buffer "n"97	cb = Vim::Buffer.current	      # gets the current buffer98	w.height = lines		      # sets the window height99	w.cursor = [row, col]		      # sets the window cursor position100	pos = w.cursor			      # gets an array [row, col]101	name = b.name			      # gets the buffer file name102	line = b[n]			      # gets a line from the buffer103	num = b.count			      # gets the number of lines104	b[n] = str			      # sets a line in the buffer105	b.delete(n)			      # deletes a line106	b.append(n, str)		      # appends a line after n107	line = Vim::Buffer.current.line       # gets the current line108	num = Vim::Buffer.current.line_number # gets the current line number109	Vim::Buffer.current.line = "test"     # sets the current line number110<111 112Module Functions:113 114							*ruby-message*115Vim::message({msg})116	Displays the message {msg}.117 118							*ruby-blob*119Vim::blob({arg})120	Return |Blob| literal string from {arg}.121 122							*ruby-set_option*123Vim::set_option({arg})124	Sets a vim option.  {arg} can be any argument that the ":set" command125	accepts.  Note that this means that no spaces are allowed in the126	argument!  See |:set|.127 128							*ruby-command*129Vim::command({cmd})130	Executes Ex command {cmd}.131 132							*ruby-evaluate*133Vim::evaluate({expr})134	Evaluates {expr} using the vim internal expression evaluator (see135	|expression|).  Returns the expression result as:136	- a Integer if the Vim expression evaluates to a number137	- a Float if the Vim expression evaluates to a float138	- a String if the Vim expression evaluates to a string139	- a Array if the Vim expression evaluates to a Vim list140	- a Hash if the Vim expression evaluates to a Vim dictionary141	Dictionaries and lists are recursively expanded.142 143==============================================================================1443. Vim::Buffer objects					*ruby-buffer*145 146Vim::Buffer objects represent vim buffers.147 148Class Methods:149 150current		Returns the current buffer object.151count		Returns the number of buffers.152self[{n}]	Returns the buffer object for the number {n}.  The first153		number is 0.154 155Methods:156 157name		Returns the full name of the buffer.158number		Returns the number of the buffer.159count		Returns the number of lines.160length		Returns the number of lines.161self[{n}]	Returns a line from the buffer.  {n} is the line number.162self[{n}] = {str}163		Sets a line in the buffer.  {n} is the line number.164delete({n})	Deletes a line from the buffer.  {n} is the line number.165append({n}, {str})166		Appends a line after the line {n}.167line		Returns the current line of the buffer if the buffer is168		active.169line = {str}    Sets the current line of the buffer if the buffer is active.170line_number     Returns the number of the current line if the buffer is171		active.172 173==============================================================================1744. Vim::Window objects					*ruby-window*175 176Vim::Window objects represent vim windows.177 178Class Methods:179 180current		Returns the current window object.181count		Returns the number of windows.182self[{n}]	Returns the window object for the number {n}.  The first183		number is 0.184 185Methods:186 187buffer		Returns the buffer displayed in the window.188height		Returns the height of the window.189height = {n}	Sets the window height to {n}.190width		Returns the width of the window.191width = {n}	Sets the window width to {n}.192cursor		Returns a [row, col] array for the cursor position.193		First line number is 1 and first column number is 0.194cursor = [{row}, {col}]195		Sets the cursor position to {row} and {col}.196 197==============================================================================1985. Global variables					*ruby-globals*199 200There are two global variables.201 202$curwin		The current window object.203$curbuf		The current buffer object.204 205==============================================================================2066. rubyeval() Vim function				*ruby-rubyeval*207 208To facilitate bi-directional interface, you can use |rubyeval()| function to209evaluate Ruby expressions and pass their values to Vim script.210 211The Ruby value "true", "false" and "nil" are converted to v:true, v:false and212v:null, respectively.213 214==============================================================================2157. Dynamic loading					*ruby-dynamic*216 217On MS-Windows and Unix the Ruby library can be loaded dynamically.  The218|:version| output then includes |+ruby/dyn|.219 220This means that Vim will search for the Ruby DLL file or shared library only221when needed.  When you don't use the Ruby interface you don't need it, thus222you can use Vim even though this library file is not on your system.223 224 225MS-Windows ~226 227You need to install the right version of Ruby for this to work.  You can find228the package to download from:229http://rubyinstaller.org/downloads/230Currently that is rubyinstaller-2.2.5.exe231 232To use the Ruby interface the Ruby DLL must be in your search path.  In a233console window type "path" to see what directories are used.  The 'rubydll'234option can be also used to specify the Ruby DLL.235 236The name of the DLL must match the Ruby version Vim was compiled with.237Currently the name is "msvcrt-ruby220.dll".  That is for Ruby 2.2.X.  To know238for sure edit "gvim.exe" and search for "ruby\d*.dll\c".239 240If you want to build Vim with RubyInstaller 1.9 or 2.X using MSVC, you need241some tricks.  See the src/INSTALLpc.txt for detail.242 243If Vim is built with RubyInstaller 2.4 or later, you may also need to add244"C:\Ruby<version>\bin\ruby_builtin_dlls" to the PATH environment variable.245 246 247Unix ~248 249The 'rubydll' option can be used to specify the Ruby shared library file250instead of DYNAMIC_RUBY_DLL file what was specified at compile time.  The251version of the shared library must match the Ruby version Vim was compiled252with.253 254==============================================================================255 vim:tw=78:ts=8:noet:ft=help:norl:256