share/vim/vim74/doc/if_ruby.txt

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