runtime/doc/if_ruby.txt

   1 *if_ruby.txt*   For Vim version 7.2b.  Last change: 2006 Apr 30
   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}.
  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
  43 Example 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
  73 Executing Ruby commands is not possible in the |sandbox|.
  74
  75 ==============================================================================
  76 2. The VIM module                                       *ruby-vim*
  77
  78 Ruby code gets all of its access to vim via the "VIM" module.
  79
  80 Overview >
  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
 103 Module Functions:
 104
 105                                                         *ruby-message*
 106 VIM::message({msg})
 107         Displays the message {msg}.
 108
 109                                                         *ruby-set_option*
 110 VIM::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*
 116 VIM::command({cmd})
 117         Executes Ex command {cmd}.
 118
 119                                                         *ruby-evaluate*
 120 VIM::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 ==============================================================================
 127 3. VIM::Buffer objects                                  *ruby-buffer*
 128
 129 VIM::Buffer objects represent vim buffers.
 130
 131 Class Methods:
 132
 133 current         Returns the current buffer object.
 134 count           Returns the number of buffers.
 135 self[{n}]       Returns the buffer object for the number {n}.  The first number
 136                 is 0.
 137
 138 Methods:
 139
 140 name            Returns the name of the buffer.
 141 number          Returns the number of the buffer.
 142 count           Returns the number of lines.
 143 length          Returns the number of lines.
 144 self[{n}]       Returns a line from the buffer. {n} is the line number.
 145 self[{n}] = {str}
 146                 Sets a line in the buffer. {n} is the line number.
 147 delete({n})     Deletes a line from the buffer. {n} is the line number.
 148 append({n}, {str})
 149                 Appends a line after the line {n}.
 150 line            Returns the current line of the buffer if the buffer is
 151                 active.
 152 line = {str}    Sets the current line of the buffer if the buffer is active.
 153 line_number     Returns the number of the current line if the buffer is
 154                 active.
 155
 156 ==============================================================================
 157 4. VIM::Window objects                                  *ruby-window*
 158
 159 VIM::Window objects represent vim windows.
 160
 161 Class Methods:
 162
 163 current         Returns the current window object.
 164 count           Returns the number of windows.
 165 self[{n}]       Returns the window object for the number {n}.  The first number
 166                 is 0.
 167
 168 Methods:
 169
 170 buffer          Returns the buffer displayed in the window.
 171 height          Returns the height of the window.
 172 height = {n}    Sets the window height to {n}.
 173 width           Returns the width of the window.
 174 width = {n}     Sets the window width to {n}.
 175 cursor          Returns a [row, col] array for the cursor position.
 176 cursor = [{row}, {col}]
 177                 Sets the cursor position to {row} and {col}.
 178
 179 ==============================================================================
 180 5. Global variables                                     *ruby-globals*
 181
 182 There are two global variables.
 183
 184 $curwin         The current window object.
 185 $curbuf         The current buffer object.
 186
 187 ==============================================================================
 188 6. Dynamic loading                                      *ruby-dynamic*
 189
 190 On MS-Windows the Ruby library can be loaded dynamically.  The |:version|
 191 output then includes |+ruby/dyn|.
 192
 193 This means that Vim will search for the Ruby DLL file only when needed.  When
 194 you don't use the Ruby interface you don't need it, thus you can use Vim
 195 without this DLL file.
 196
 197 To use the Ruby interface the Ruby DLL must be in your search path.  In a
 198 console window type "path" to see what directories are used.
 199
 200 The name of the DLL must match the Ruby version Vim was compiled with.
 201 Currently the name is "ruby18.dll".  That is for Ruby 1.8.  To know for sure
 202 edit "gvim.exe" and search for "ruby\d*.dll\c".
 203
 204 ==============================================================================
 205  vim:tw=78:ts=8:ft=help:norl: