1*if_ruby.txt*   For Vim version 7.3.  Last change: 2010 Jul 20
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}.
29
30:rub[y] << {endpattern}
31{script}
32{endpattern}
33			Execute Ruby script {script}.
34			{endpattern} must NOT be preceded by any white space.
35			If {endpattern} is omitted, it defaults to a dot '.'
36			like for the |:append| and |:insert| commands.  This
37			form of the |:ruby| command is mainly useful for
38			including ruby code in vim scripts.
39			Note: This command doesn't work when the Ruby feature
40			wasn't compiled in.  To avoid errors, see
41			|script-here|.
42
43Example Vim script: >
44
45	function! RedGem()
46	ruby << EOF
47	class Garnet
48		def initialize(s)
49			@buffer = VIM::Buffer.current
50			vimputs(s)
51		end
52		def vimputs(s)
53			@buffer.append(@buffer.count,s)
54		end
55	end
56	gem = Garnet.new("pretty")
57	EOF
58	endfunction
59<
60
61						*:rubydo* *:rubyd* *E265*
62:[range]rubyd[o] {cmd}	Evaluate Ruby command {cmd} for each line in the
63			[range], with $_ being set to the text of each line in
64			turn, without a trailing <EOL>.  Setting $_ will change
65			the text, but note that it is not possible to add or
66			delete lines using this command.
67			The default for [range] is the whole file: "1,$".
68
69							*:rubyfile* *:rubyf*
70:rubyf[ile] {file}	Execute the Ruby script in {file}.  This is the same as
71			":ruby load 'file'", but allows file name completion.
72
73Executing Ruby commands is not possible in the |sandbox|.
74
75==============================================================================
762. The VIM module					*ruby-vim*
77
78Ruby code gets all of its access to vim via the "VIM" module.
79
80Overview >
81	print "Hello"			      # displays a message
82	VIM.command(cmd)		      # execute an Ex command
83	num = VIM::Window.count		      # gets the number of windows
84	w = VIM::Window[n]		      # gets window "n"
85	cw = VIM::Window.current	      # gets the current window
86	num = VIM::Buffer.count		      # gets the number of buffers
87	b = VIM::Buffer[n]		      # gets buffer "n"
88	cb = VIM::Buffer.current	      # gets the current buffer
89	w.height = lines		      # sets the window height
90	w.cursor = [row, col]		      # sets the window cursor position
91	pos = w.cursor			      # gets an array [row, col]
92	name = b.name			      # gets the buffer file name
93	line = b[n]			      # gets a line from the buffer
94	num = b.count			      # gets the number of lines
95	b[n] = str			      # sets a line in the buffer
96	b.delete(n)			      # deletes a line
97	b.append(n, str)		      # appends a line after n
98	line = VIM::Buffer.current.line       # gets the current line
99	num = VIM::Buffer.current.line_number # gets the current line number
100	VIM::Buffer.current.line = "test"     # sets the current line number
101<
102
103Module Functions:
104
105							*ruby-message*
106VIM::message({msg})
107	Displays the message {msg}.
108
109							*ruby-set_option*
110VIM::set_option({arg})
111	Sets a vim option.  {arg} can be any argument that the ":set" command
112	accepts.  Note that this means that no spaces are allowed in the
113	argument!  See |:set|.
114
115							*ruby-command*
116VIM::command({cmd})
117	Executes Ex command {cmd}.
118
119							*ruby-evaluate*
120VIM::evaluate({expr})
121	Evaluates {expr} using the vim internal expression evaluator (see
122	|expression|).  Returns the expression result as a string.
123	A |List| is turned into a string by joining the items and inserting
124	line breaks.
125
126==============================================================================
1273. VIM::Buffer objects					*ruby-buffer*
128
129VIM::Buffer objects represent vim buffers.
130
131Class Methods:
132
133current		Returns the current buffer object.
134count		Returns the number of buffers.
135self[{n}]	Returns the buffer object for the number {n}.  The first number
136		is 0.
137
138Methods:
139
140name		Returns the name of the buffer.
141number		Returns the number of the buffer.
142count		Returns the number of lines.
143length		Returns the number of lines.
144self[{n}]	Returns a line from the buffer. {n} is the line number.
145self[{n}] = {str}
146		Sets a line in the buffer. {n} is the line number.
147delete({n})	Deletes a line from the buffer. {n} is the line number.
148append({n}, {str})
149		Appends a line after the line {n}.
150line		Returns the current line of the buffer if the buffer is
151		active.
152line = {str}    Sets the current line of the buffer if the buffer is active.
153line_number     Returns the number of the current line if the buffer is
154		active.
155
156==============================================================================
1574. VIM::Window objects					*ruby-window*
158
159VIM::Window objects represent vim windows.
160
161Class Methods:
162
163current		Returns the current window object.
164count		Returns the number of windows.
165self[{n}]	Returns the window object for the number {n}.  The first number
166		is 0.
167
168Methods:
169
170buffer		Returns the buffer displayed in the window.
171height		Returns the height of the window.
172height = {n}	Sets the window height to {n}.
173width		Returns the width of the window.
174width = {n}	Sets the window width to {n}.
175cursor		Returns a [row, col] array for the cursor position.
176cursor = [{row}, {col}]
177		Sets the cursor position to {row} and {col}.
178
179==============================================================================
1805. Global variables					*ruby-globals*
181
182There are two global variables.
183
184$curwin		The current window object.
185$curbuf		The current buffer object.
186
187==============================================================================
1886. Dynamic loading					*ruby-dynamic*
189
190On MS-Windows the Ruby library can be loaded dynamically.  The |:version|
191output then includes |+ruby/dyn|.
192
193This means that Vim will search for the Ruby DLL file only when needed.  When
194you don't use the Ruby interface you don't need it, thus you can use Vim
195without this DLL file.
196
197You need to install the right version of Ruby for this to work.  You can find
198the package to download from:
199http://www.garbagecollect.jp/ruby/mswin32/en/download/release.html
200Currently that is ruby-1.9.1-p429-i386-mswin32.zip
201
202To use the Ruby interface the Ruby DLL must be in your search path.  In a
203console window type "path" to see what directories are used.
204
205The name of the DLL must match the Ruby version Vim was compiled with.
206Currently the name is "msvcrt-ruby191.dll".  That is for Ruby 1.9.1.  To know
207for sure edit "gvim.exe" and search for "ruby\d*.dll\c".
208
209If you want to build Vim with Ruby 1.9.1, you need to edit the config.h file
210and comment-out the check for _MSC_VER.
211
212==============================================================================
213 vim:tw=78:ts=8:ft=help:norl:
214