doc/irb/irb.rd

   1 irb -- interactive ruby
   2                 $Release Version: 0.9 $
   3                 $Revision$
   4                 by Keiju ISHITSUKA(keiju@ishitsuka.com)
   5                 by gotoken-san who is original translater from japanese version
   6
   7 =begin
   8 = What is irb?
   9
  10 irb stands for `interactive ruby'. irb is a tool to execute interactively
  11 ruby expressions read from stdin.
  12
  13 = Invoking
  14
  15   % irb
  16
  17 = Usage
  18
  19 Use of irb is easy if you know ruby.  Executing irb, prompts are
  20 displayed as follows. Then, enter expression of ruby. A input is
  21 executed when it is syntacticaly completed.
  22
  23   dim% irb
  24   irb(main):001:0> 1+2
  25   3
  26   irb(main):002:0> class Foo
  27   irb(main):003:1>  def foo
  28   irb(main):004:2>    print 1
  29   irb(main):005:2>  end
  30   irb(main):006:1> end
  31   nil
  32   irb(main):007:0>
  33
  34 And, Readline extesion module can be used with irb. Using Readline
  35 is the standard default action if Readline is installed.
  36
  37 = Command line option
  38
  39   irb.rb [options] file_name opts
  40   options:
  41   -f                suppress read ~/.irbrc
  42   -m                bc mode (fraction or matrix are available)
  43   -d                set $DEBUG  to true (same as `ruby -d')
  44   -Kc               same as `ruby -Kc'
  45   -r load-module    same as `ruby -r'
  46   --verbose         command input is echoed(default)
  47   --noverbose       command input isn't echoed
  48   --echo            commands are echoed immediately before execution(default)
  49   --noecho          commands aren't echoed immediately before execution
  50   --inspect         uses `inspect' for output (the default except bc mode)
  51   --noinspect       doesn't uses inspect for output
  52   --readline        uses Readline extension module
  53   --noreadline      doesn't use Readline extension module
  54   --prompt prompt-mode
  55   --prompt-mode prompt-mode
  56                     switches prompt mode. Pre-defined prompt modes are
  57                     `default', `simple', `xmp' and `inf-ruby'
  58
  59   --inf-ruby-mode   uses prompt appreciate for inf-ruby-mode on emacs.
  60                     Suppresses --readline.
  61   --simple-prompt   simple prompt mode
  62   --noprompt        no prompt
  63   --tracer          display trace for each execution of commands.
  64   --back-trace-limit n
  65                     displayes backtrace top n and tail n. The default
  66                     value is 16.
  67   --irb_debug n     sets internal debug level to n (It shouldn't be used)
  68   -v, --version     prints the version of irb
  69
  70 = Configurations
  71
  72 irb reads `~/.irbrc' when it is invoked. If `~/.irbrb' doesn't exist
  73 irb try to read in the order `.irbrc', `irb.rc', `_irbrc' then `$irbrc'.
  74
  75 The following is altanative to the command line option. To use them
  76 type as follows in an irb session.
  77
  78   IRB.conf[:IRB_NAME]="irb"
  79   IRB.conf[:MATH_MODE]=false
  80   IRB.conf[:USE_TRACER]=false
  81   IRB.conf[:USE_LOADER]=false
  82   IRB.conf[:IGNORE_SIGINT]=true
  83   IRB.conf[:IGNORE_EOF]=false
  84   IRB.conf[:INSPECT_MODE]=nil
  85   IRB.conf[:IRB_RC] = nil
  86   IRB.conf[:BACK_TRACE_LIMIT]=16
  87   IRB.conf[:USE_LOADER] = false
  88   IRB.conf[:USE_READLINE] = nil
  89   IRB.conf[:USE_TRACER] = false
  90   IRB.conf[:IGNORE_SIGINT] = true
  91   IRB.conf[:IGNORE_EOF] = false
  92   IRB.conf[:PROMPT_MODE] = :DEFALUT
  93   IRB.conf[:PROMPT] = {...}
  94   IRB.conf[:DEBUG_LEVEL]=0
  95   IRB.conf[:VERBOSE]=true
  96
  97 == Customizing prompt
  98
  99 To costomize the prompt you set a variable
 100
 101   IRB.conf[:PROMPT]
 102
 103 For example, describe as follows in `.irbrc'.
 104
 105   IRB.conf[:PROMPT][:MY_PROMPT] = { # name of prompt mode
 106     :PROMPT_I => nil,             # normal prompt
 107     :PROMPT_S => nil,             # prompt for continuated strings
 108     :PROMPT_C => nil,             # prompt for continuated statement
 109     :RETURN => "    ==>%s\n"      # format to return value
 110   }
 111
 112 Then, invoke irb with the above prompt mode by
 113
 114   % irb --prompt my-prompt
 115
 116 Or add the following in `.irbrc'.
 117
 118   IRB.conf[:PROMPT_MODE] = :MY_PROMPT
 119
 120 Constants PROMPT_I, PROMPT_S and PROMPT_C specifies the format.
 121 In the prompt specification, some special strings are available.
 122
 123   %N    command name which is running
 124   %m    to_s of main object (self)
 125   %M    inspect of main object (self)
 126   %l    type of string(", ', /, ]), `]' is inner %w[...]
 127   %NNi  indent level. NN is degits and means as same as printf("%NNd").
 128         It can be ommited
 129   %NNn  line number.
 130   %%    %
 131
 132 For instance, the default prompt mode is defined as follows:
 133
 134 IRB.conf[:PROMPT_MODE][:DEFAULT] = {
 135       :PROMPT_I => "%N(%m):%03n:%i> ",
 136       :PROMPT_S => "%N(%m):%03n:%i%l ",
 137       :PROMPT_C => "%N(%m):%03n:%i* ",
 138       :RETURN => "%s\n"
 139 }
 140
 141 RETURN is used to printf.
 142
 143 == Configurating subirb
 144
 145 The command line option or IRB.conf specify the default behavior of
 146 (sub)irb. On the other hand, each conf of in the next sction `6. Command'
 147 is used to individually configurate (sub)irb.
 148
 149 If proc is set to IRB.conf[:IRB_RC], its subirb will be invoked after
 150 execution of that proc under giving the context of irb as its
 151 aregument. By this mechanism each subirb can be configurated.
 152
 153 = Command
 154
 155 For irb commands, both simple name and `irb_'-prefixed name are prepared.
 156
 157 --- exit, quit, irb_exit
 158     Quits (sub)irb.
 159
 160 --- conf, irb_context
 161     Displays current configuration. Modifing the configuration is
 162     achieved by sending message to `conf'.
 163
 164 --- conf.eval_history = N
 165     Sets execution result history.
 166     N is a integer or nil. If N > 0, the number of historys is N.
 167     If N == 0, the number of historys is unlimited. If N is nill,
 168     execution result history isn't used(default).
 169
 170 --- conf.back_trace_limit
 171     Sets display lines of backtrace as top n and tail n.
 172     The default value is 16.
 173
 174 --- conf.debug_level = N
 175     Sets debug level of irb.
 176
 177 --- conf.ignore_eof = true/false
 178     Whether ^D (control-d) will be ignored or not.
 179     If false is set, ^D means quit.
 180
 181 --- conf.ignore_sigint= true/false
 182     Whether ^C (control-c) will be ignored or not.
 183     If false is set, ^D means quit.  If true,
 184       during input:   cancel inputing then return to top level.
 185       during execute: abondon current execution.
 186
 187 --- conf.inf_ruby_mode = true/false
 188     Whether inf-ruby-mode or not. The default value is false.
 189
 190 --- conf.inspect_mode = true/false/nil
 191     Specifies inspect mode.
 192     true:  display inspect
 193     false: display to_s
 194     nil:   inspect mode in non math mode,
 195            non inspect mode in math mode.
 196
 197 --- conf.math_mode
 198     Whether bc mode or not.
 199
 200 --- conf.use_loader = true/false
 201     Whether irb's own file reader method is used when load/require or not.
 202     This mode is globaly affected (irb wide).
 203
 204 --- conf.prompt_c
 205     prompt for a continuating statement (e.g, immediately after of `if')
 206
 207 --- conf.prompt_i
 208     standard prompt
 209
 210 --- conf.prompt_s
 211     prompt for a continuating string
 212
 213 --- conf.rc
 214     Whether ~/.irbrc is read or not.
 215
 216 --- conf.use_prompt = true/false
 217     Prompting or not.
 218
 219 --- conf.use_readline = true/false/nil
 220     Whether readline is used or not.
 221     true: uses
 222     false: doen't use
 223     nil: intends to use readline except for inf-ruby-mode (default)
 224 #
 225 #--- conf.verbose=T/F
 226 #    Whether verbose messages are display or not.
 227
 228 --- cws, chws, irb_change_workspace [obj]
 229     obj will be self. If obj is omitted, self will be home-object, or
 230     the main object of first started irb.
 231
 232 --- pushws, irb_pushws, irb_push_workspace [obj]
 233     same as UNIX-shell command pushd.
 234
 235 --- popws, irb_popws, irb_pop_workspace
 236     same as UNIX-shell command popd
 237
 238 --- irb [obj]
 239     Invoke subirb. If obj is given, obj will be self.
 240
 241 --- jobs, irb_jobs
 242     List of subirb
 243
 244 --- fg n, irb_fg n
 245     Switch into specified subirb. The following is candidates of n:
 246
 247       irb number
 248       thhread
 249       irb object
 250       self(obj which is specified of irb obj)
 251
 252 --- kill n, irb_kill n
 253     Kill subirb. The means of n is as same as the case of irb_fg.
 254
 255 --- souce, irb_source  path
 256     This is a like UNIX-shell command source. evaluate script in path
 257     on current context.
 258
 259 --- irb_load path, prev
 260     irb-version of Ruby's load.
 261
 262 = System variable
 263
 264 --- _  The latest value of evaluation (it is local)
 265 --- __ The history of evaluation values.
 266     __[line_no] return an evaluation value of line number<line_no>. If
 267     line_no is a negative, return value before -<line_no> from latest
 268     value.
 269
 270 = Session Example
 271
 272   dim% ruby irb.rb
 273   irb(main):001:0> irb                        # invoke subirb
 274   irb#1(main):001:0> jobs                     # list of subirbs
 275   #0->irb on main (#<Thread:0x400fb7e4> : stop)
 276   #1->irb#1 on main (#<Thread:0x40125d64> : running)
 277   nil
 278   irb#1(main):002:0> fg 0                     # switch job
 279   nil
 280   irb(main):002:0> class Foo;end
 281   nil
 282   irb(main):003:0> irb Foo                    # invoke subirb which has the
 283                                               #              context of Foo
 284   irb#2(Foo):001:0> def foo                   # define Foo#foo
 285   irb#2(Foo):002:1>   print 1
 286   irb#2(Foo):003:1> end
 287   nil
 288   irb#2(Foo):004:0> fg 0                      # switch job
 289   nil
 290   irb(main):004:0> jobs                       # list of job
 291   #0->irb on main (#<Thread:0x400fb7e4> : running)
 292   #1->irb#1 on main (#<Thread:0x40125d64> : stop)
 293   #2->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
 294   nil
 295   irb(main):005:0> Foo.instance_methods       # Foo#foo is defined asurely
 296   ["foo"]
 297   irb(main):006:0> fg 2                       # switch job
 298   nil
 299   irb#2(Foo):005:0> def bar                   # define Foo#bar
 300   irb#2(Foo):006:1>  print "bar"
 301   irb#2(Foo):007:1> end
 302   nil
 303   irb#2(Foo):010:0>  Foo.instance_methods
 304   ["bar", "foo"]
 305   irb#2(Foo):011:0> fg 0
 306   nil
 307   irb(main):007:0> f = Foo.new
 308   #<Foo:0x4010af3c>
 309   irb(main):008:0> irb f                      # invoke subirb which has the
 310                                               #  context of f (instance of Foo)
 311   irb#3(#<Foo:0x4010af3c>):001:0> jobs
 312   #0->irb on main (#<Thread:0x400fb7e4> : stop)
 313   #1->irb#1 on main (#<Thread:0x40125d64> : stop)
 314   #2->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
 315   #3->irb#3 on #<Foo:0x4010af3c> (#<Thread:0x4010a1e0> : running)
 316   nil
 317   irb#3(#<Foo:0x4010af3c>):002:0> foo         # evaluate f.foo
 318   1nil
 319   irb#3(#<Foo:0x4010af3c>):003:0> bar         # evaluate f.bar
 320   barnil
 321   irb#3(#<Foo:0x4010af3c>):004:0> kill 1, 2, 3# kill job
 322   nil
 323   irb(main):009:0> jobs
 324   #0->irb on main (#<Thread:0x400fb7e4> : running)
 325   nil
 326   irb(main):010:0> exit                       # exit
 327   dim%
 328
 329 = Restrictions
 330
 331 Because irb evaluates the inputs immediately after the imput is
 332 syntactically completed, irb gives slight different result than
 333 directly use ruby. Known difference is pointed out here.
 334
 335
 336 == Declaration of the local variable
 337
 338 The following causes an error in ruby:
 339
 340   eval "foo = 0"
 341   foo
 342   --
 343   -:2: undefined local variable or method `foo' for #<Object:0x40283118> (NameError)
 344   ---
 345   NameError
 346
 347 Though, the above will successfully done by irb.
 348
 349   >> eval "foo = 0"
 350  => 0
 351  >> foo
 352  => 0
 353
 354 Ruby evaluates a code after reading entire of code and determination
 355 of the scope of local variables. On the other hand, irb do
 356 immediately. More precisely, irb evaluate at first
 357
 358   evel "foo = 0"
 359
 360 then foo is defined on this timing. It is because of this
 361 incompatibility.
 362
 363 If you'd like to detect those differences, begin...end can be used:
 364
 365   >> begin
 366   ?>   eval "foo = 0"
 367   >>   foo
 368   >> end
 369   NameError: undefined local variable or method `foo' for #<Object:0x4013d0f0>
 370   (irb):3
 371   (irb_local_binding):1:in `eval'
 372
 373 == Here-document
 374
 375 Implementation of Here-document is incomplete.
 376
 377 == Symbol
 378
 379 Irb can not always recognize a symbol as to be Symbol. Concretely, an
 380 expression have completed, however Irb regard it as continuation line.
 381
 382 =end
 383
 384 % Begin Emacs Environment
 385 % Local Variables:
 386 % mode: text
 387 % comment-column: 0
 388 % comment-start: "%"
 389 % comment-end: "\n"
 390 % End:
 391 %