vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

if_ruby.txt (8517B)


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