Mercurial > vim
annotate runtime/doc/if_ruby.txt @ 13619:41ed86454233
Added tag v8.0.1681 for changeset ea4f2a8040b4ab7111c02c71aa587e2ac121aa6b
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Tue, 10 Apr 2018 12:45:07 +0200 |
| parents | 9eebe457eb3c |
| children | 1174611ad715 |
| rev | line source |
|---|---|
|
13482
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
11062
diff
changeset
|
1 *if_ruby.txt* For Vim version 8.0. Last change: 2018 Mar 15 |
| 7 | 2 |
| 3 | |
| 4 VIM REFERENCE MANUAL by Shugo Maeda | |
| 5 | |
| 6 The Ruby Interface to Vim *ruby* *Ruby* | |
| 7 | |
| 8 | |
| 9 1. Commands |ruby-commands| | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
10 2. The Vim module |ruby-vim| |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
11 3. Vim::Buffer objects |ruby-buffer| |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
12 4. Vim::Window objects |ruby-window| |
| 7 | 13 5. Global variables |ruby-globals| |
| 557 | 14 6. Dynamic loading |ruby-dynamic| |
| 7 | 15 |
| 16 {Vi does not have any of these commands} | |
| 17 *E266* *E267* *E268* *E269* *E270* *E271* *E272* *E273* | |
| 18 | |
| 19 The Ruby interface only works when Vim was compiled with the |+ruby| feature. | |
| 20 | |
| 21 The home page for ruby is http://www.ruby-lang.org/. You can find links for | |
| 22 downloading Ruby there. | |
| 23 | |
| 24 ============================================================================== | |
| 25 1. Commands *ruby-commands* | |
| 26 | |
| 27 *:ruby* *:rub* | |
| 3750 | 28 :rub[y] {cmd} Execute Ruby command {cmd}. A command to try it out: > |
| 29 :ruby print "Hello" | |
| 7 | 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 '.' | |
| 236 | 37 like for the |:append| and |:insert| commands. This |
| 7 | 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 | |
| 44 Example Vim script: > | |
| 45 | |
| 46 function! RedGem() | |
| 47 ruby << EOF | |
| 48 class Garnet | |
| 49 def initialize(s) | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
50 @buffer = Vim::Buffer.current |
| 7 | 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 < | |
|
10153
715d6c5707b8
commit https://github.com/vim/vim/commit/abd468ed0fbcba391e7833feeaa7de3ced841455
Christian Brabandt <cb@256bit.org>
parents:
10140
diff
changeset
|
61 To see what version of Ruby you have: > |
|
715d6c5707b8
commit https://github.com/vim/vim/commit/abd468ed0fbcba391e7833feeaa7de3ced841455
Christian Brabandt <cb@256bit.org>
parents:
10140
diff
changeset
|
62 :ruby print RUBY_VERSION |
|
715d6c5707b8
commit https://github.com/vim/vim/commit/abd468ed0fbcba391e7833feeaa7de3ced841455
Christian Brabandt <cb@256bit.org>
parents:
10140
diff
changeset
|
63 < |
| 7 | 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 | |
| 236 | 68 turn, without a trailing <EOL>. Setting $_ will change |
| 7 | 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 | |
| 11062 | 75 `:ruby load 'file'`, but allows file name completion. |
| 7 | 76 |
| 77 Executing Ruby commands is not possible in the |sandbox|. | |
| 78 | |
| 79 ============================================================================== | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
80 2. The Vim module *ruby-vim* |
| 7 | 81 |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
82 Ruby code gets all of its access to vim via the "Vim" module. |
| 7 | 83 |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
84 Overview: > |
| 809 | 85 print "Hello" # displays a message |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
86 Vim.command(cmd) # execute an Ex command |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
87 num = Vim::Window.count # gets the number of windows |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
88 w = Vim::Window[n] # gets window "n" |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
89 cw = Vim::Window.current # gets the current window |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
90 num = Vim::Buffer.count # gets the number of buffers |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
91 b = Vim::Buffer[n] # gets buffer "n" |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
92 cb = Vim::Buffer.current # gets the current buffer |
| 809 | 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 | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
102 line = Vim::Buffer.current.line # gets the current line |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
103 num = Vim::Buffer.current.line_number # gets the current line number |
|
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
104 Vim::Buffer.current.line = "test" # sets the current line number |
| 7 | 105 < |
| 106 | |
| 107 Module Functions: | |
| 108 | |
| 109 *ruby-message* | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
110 Vim::message({msg}) |
| 7 | 111 Displays the message {msg}. |
| 112 | |
| 113 *ruby-set_option* | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
114 Vim::set_option({arg}) |
| 7 | 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* | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
120 Vim::command({cmd}) |
| 7 | 121 Executes Ex command {cmd}. |
| 122 | |
| 123 *ruby-evaluate* | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
124 Vim::evaluate({expr}) |
| 7 | 125 Evaluates {expr} using the vim internal expression evaluator (see |
| 6647 | 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. | |
| 7 | 133 |
| 134 ============================================================================== | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
135 3. Vim::Buffer objects *ruby-buffer* |
| 7 | 136 |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
137 Vim::Buffer objects represent vim buffers. |
| 7 | 138 |
| 139 Class Methods: | |
| 140 | |
| 141 current Returns the current buffer object. | |
| 142 count Returns the number of buffers. | |
| 236 | 143 self[{n}] Returns the buffer object for the number {n}. The first number |
| 7 | 144 is 0. |
| 145 | |
| 146 Methods: | |
| 147 | |
| 148 name Returns the name of the buffer. | |
| 149 number Returns the number of the buffer. | |
| 150 count Returns the number of lines. | |
| 151 length Returns the number of lines. | |
| 152 self[{n}] Returns a line from the buffer. {n} is the line number. | |
| 153 self[{n}] = {str} | |
| 154 Sets a line in the buffer. {n} is the line number. | |
| 155 delete({n}) Deletes a line from the buffer. {n} is the line number. | |
| 156 append({n}, {str}) | |
| 157 Appends a line after the line {n}. | |
| 856 | 158 line Returns the current line of the buffer if the buffer is |
| 809 | 159 active. |
| 160 line = {str} Sets the current line of the buffer if the buffer is active. | |
| 161 line_number Returns the number of the current line if the buffer is | |
| 162 active. | |
| 7 | 163 |
| 164 ============================================================================== | |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
165 4. Vim::Window objects *ruby-window* |
| 7 | 166 |
|
7315
444efa5f5015
commit https://github.com/vim/vim/commit/2c5e8e80eacf491d4f266983f534a77776c7ae83
Christian Brabandt <cb@256bit.org>
parents:
7196
diff
changeset
|
167 Vim::Window objects represent vim windows. |
| 7 | 168 |
| 169 Class Methods: | |
| 170 | |
| 171 current Returns the current window object. | |
| 172 count Returns the number of windows. | |
| 236 | 173 self[{n}] Returns the window object for the number {n}. The first number |
| 7 | 174 is 0. |
| 175 | |
| 176 Methods: | |
| 177 | |
| 178 buffer Returns the buffer displayed in the window. | |
| 179 height Returns the height of the window. | |
| 180 height = {n} Sets the window height to {n}. | |
| 502 | 181 width Returns the width of the window. |
| 182 width = {n} Sets the window width to {n}. | |
| 7 | 183 cursor Returns a [row, col] array for the cursor position. |
| 184 cursor = [{row}, {col}] | |
| 185 Sets the cursor position to {row} and {col}. | |
| 186 | |
| 187 ============================================================================== | |
| 557 | 188 5. Global variables *ruby-globals* |
| 7 | 189 |
| 190 There are two global variables. | |
| 191 | |
| 192 $curwin The current window object. | |
| 193 $curbuf The current buffer object. | |
| 194 | |
| 195 ============================================================================== | |
| 557 | 196 6. Dynamic loading *ruby-dynamic* |
| 197 | |
| 2625 | 198 On MS-Windows and Unix the Ruby library can be loaded dynamically. The |
| 199 |:version| output then includes |+ruby/dyn|. | |
| 557 | 200 |
| 2625 | 201 This means that Vim will search for the Ruby DLL file or shared library only |
| 202 when needed. When you don't use the Ruby interface you don't need it, thus | |
| 203 you can use Vim even though this library file is not on your system. | |
| 557 | 204 |
|
8673
ed7251c3e2d3
commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents:
7315
diff
changeset
|
205 |
|
7196
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
206 MS-Windows ~ |
|
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
207 |
|
2342
f6540762173d
Fixes and improvements for MS-Windows build.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
208 You need to install the right version of Ruby for this to work. You can find |
|
f6540762173d
Fixes and improvements for MS-Windows build.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
209 the package to download from: |
|
10244
876fbdd84e52
commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
210 http://rubyinstaller.org/downloads/ |
|
876fbdd84e52
commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
211 Currently that is rubyinstaller-2.2.5.exe |
|
2342
f6540762173d
Fixes and improvements for MS-Windows build.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
212 |
| 557 | 213 To use the Ruby interface the Ruby DLL must be in your search path. In a |
|
8673
ed7251c3e2d3
commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents:
7315
diff
changeset
|
214 console window type "path" to see what directories are used. The 'rubydll' |
|
ed7251c3e2d3
commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents:
7315
diff
changeset
|
215 option can be also used to specify the Ruby DLL. |
| 557 | 216 |
| 217 The name of the DLL must match the Ruby version Vim was compiled with. | |
|
10244
876fbdd84e52
commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
218 Currently the name is "msvcrt-ruby220.dll". That is for Ruby 2.2.X. To know |
|
2342
f6540762173d
Fixes and improvements for MS-Windows build.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
219 for sure edit "gvim.exe" and search for "ruby\d*.dll\c". |
|
f6540762173d
Fixes and improvements for MS-Windows build.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
220 |
|
10244
876fbdd84e52
commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
221 If you want to build Vim with RubyInstaller 1.9 or 2.X using MSVC, you need |
|
876fbdd84e52
commit https://github.com/vim/vim/commit/2ec618c9feac4573b154510236ad8121c77d0eca
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
222 some tricks. See the src/INSTALLpc.txt for detail. |
| 557 | 223 |
|
13482
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
11062
diff
changeset
|
224 If Vim is built with RubyInstaller 2.4 or later, you may also need to add |
|
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
11062
diff
changeset
|
225 "C:\Ruby<version>\bin\ruby_builtin_dlls" to the PATH environment variable. |
|
9eebe457eb3c
Update runtime files. Convert a couple of help files to utf-8.
Christian Brabandt <cb@256bit.org>
parents:
11062
diff
changeset
|
226 |
|
8673
ed7251c3e2d3
commit https://github.com/vim/vim/commit/e18c0b39815c5a746887a509c2cd9f11fadaba07
Christian Brabandt <cb@256bit.org>
parents:
7315
diff
changeset
|
227 |
|
7196
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
228 Unix ~ |
|
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
229 |
|
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
230 The 'rubydll' option can be used to specify the Ruby shared library file |
|
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
231 instead of DYNAMIC_RUBY_DLL file what was specified at compile time. The |
|
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
232 version of the shared library must match the Ruby version Vim was compiled |
|
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
233 with. |
|
42717d048817
commit https://github.com/vim/vim/commit/d94464ee294a351ce7b6ba18e8bd3f24f1bef920
Christian Brabandt <cb@256bit.org>
parents:
6647
diff
changeset
|
234 |
| 557 | 235 ============================================================================== |
| 7 | 236 vim:tw=78:ts=8:ft=help:norl: |