irb.1

   1 .TH IRB "1" "December 2002"
   2 .SH NAME
   3 irb \- interactive ruby
   4 .SH SYNOPSIS
   5 .B irb
   6 [\fIoptions\fR]
   7 .SH DESCRIPTION
   8 .PP
   9 irb stands for `interactive ruby'. irb is a tool to execute interactively
  10 ruby expressions read from stdin.
  11 Use of irb is easy if you know ruby.  Executing irb, prompts are
  12 displayed as follows. Then, enter expression of ruby. A input is
  13 executed when it is syntacticaly completed.
  14
  15 .nf
  16 \&    $ irb1.8
  17 \&    irb(main):001:0> 1+2
  18 \&    3
  19 \&    irb(main):002:0> class Foo
  20 \&    irb(main):003:1>  def foo
  21 \&    irb(main):004:2>    print 1
  22 \&    irb(main):005:2>  end
  23 \&    irb(main):006:1> end
  24 \&    nil
  25 \&    irb(main):007:0>
  26 .fi
  27
  28 And, Readline extesion module can be used with irb. Using Readline
  29 is the standard default action if Readline is installed.
  30 .SH OPTIONS
  31
  32 .PP
  33
  34 .TP
  35 .fi
  36 .B
  37 \-f
  38 suppress read ~/.irbrc
  39 .TP
  40 .fi
  41 .B
  42 \-m
  43 bc mode (fraction or matrix are available)
  44 .TP
  45 .fi
  46 .B
  47 \-d
  48 set $DEBUG  to true (same as `ruby \-d')
  49 .TP
  50 .fi
  51 .B
  52 \-r load\-module
  53 same as `ruby \-r'
  54 .TP
  55 .fi
  56 .B
  57 \-\-inspect
  58 uses `inspect' for output (the default except bc mode)
  59 .TP
  60 .fi
  61 .B
  62 \-\-noinspect
  63 doesn't uses inspect for output
  64 .TP
  65 .fi
  66 .B
  67 \-\-readline
  68 uses Readline extension module
  69 .TP
  70 .fi
  71 .B
  72 \-\-noreadline
  73 doesn't use Readline extension module
  74 .TP
  75 .fi
  76 .B
  77 \-\-prompt prompt\-mode
  78 .TP
  79 .fi
  80 .B
  81 \-\-prompt\-mode prompt\-mode
  82 switches prompt mode. Pre\-defined prompt modes are
  83 `default', `simple', `xmp' and `inf\-ruby'
  84 .TP
  85 .fi
  86 .B
  87 \-\-inf\-ruby\-mode
  88 uses prompt appreciate for inf\-ruby\-mode on emacs.
  89 Suppresses \-\-readline.
  90 .TP
  91 .fi
  92 .B
  93 \-\-simple\-prompt
  94 simple prompt mode
  95 .TP
  96 .fi
  97 .B
  98 \-\-noprompt
  99 no prompt
 100 .TP
 101 .fi
 102 .B
 103 \-\-tracer
 104 display trace for each execution of commands.
 105 .TP
 106 .fi
 107 .B
 108 \-\-back\-trace\-limit n
 109 displayes backtrace top n and tail n. The default
 110 value is 16.
 111 .TP
 112 .fi
 113 .B
 114 \-\-irb_debug n
 115 sets internal debug level to n (It shouldn't be used)
 116 .TP
 117 .fi
 118 .B
 119 \-v, \-\-version
 120 prints the version of irb
 121 .SH CONFIGURATIONS
 122
 123 .PP
 124 irb reads `~/.irbrc' when it is invoked. If `~/.irbrb' doesn't exist
 125 irb try to read in the order `.irbrc', `irb.rc', `_irbrc' then `$irbrc'.
 126 The following is altanative to the command line option. To use them
 127 type as follows in an irb session.
 128
 129 .nf
 130 \&    IRB.conf[:IRB_NAME]="irb"
 131 \&    IRB.conf[:MATH_MODE]=false
 132 \&    IRB.conf[:USE_TRACER]=false
 133 \&    IRB.conf[:USE_LOADER]=false
 134 \&    IRB.conf[:IGNORE_SIGINT]=true
 135 \&    IRB.conf[:IGNORE_EOF]=false
 136 \&    IRB.conf[:INSPECT_MODE]=nil
 137 \&    IRB.conf[:IRB_RC] = nil
 138 \&    IRB.conf[:BACK_TRACE_LIMIT]=16
 139 \&    IRB.conf[:USE_LOADER] = false
 140 \&    IRB.conf[:USE_READLINE] = nil
 141 \&    IRB.conf[:USE_TRACER] = false
 142 \&    IRB.conf[:IGNORE_SIGINT] = true
 143 \&    IRB.conf[:IGNORE_EOF] = false
 144 \&    IRB.conf[:PROMPT_MODE] = :DEFALUT
 145 \&    IRB.conf[:PROMPT] = {...}
 146 \&    IRB.conf[:DEBUG_LEVEL]=0
 147 \&    IRB.conf[:VERBOSE]=true
 148 .fi
 149 .SH Customizing prompt
 150
 151 .PP
 152 To costomize the prompt you set a variable
 153
 154 .nf
 155 \&    IRB.conf[:PROMPT]
 156 .fi
 157
 158 For example, describe as follows in `.irbrc'.
 159
 160 .nf
 161 \&    IRB.conf[:PROMPT][:MY_PROMPT] = { # name of prompt mode
 162 \&      :PROMPT_I => nil,                 # normal prompt
 163 \&      :PROMPT_S => nil,                 # prompt for continuated strings
 164 \&      :PROMPT_C => nil,                 # prompt for continuated statement
 165 \&      :RETURN => "    ==>%s\\n"         # format to return value
 166 \&    }
 167 .fi
 168
 169 Then, invoke irb with the above prompt mode by
 170
 171 .nf
 172 \&    $ irb1.8 \-\-prompt my\-prompt
 173 .fi
 174
 175 Or add the following in `.irbrc'.
 176
 177 .nf
 178 \&    IRB.conf[:PROMPT_MODE] = :MY_PROMPT
 179 .fi
 180
 181 Constants PROMPT_I, PROMPT_S and PROMPT_C specifies the format.
 182 In the prompt specification, some special strings are available.
 183
 184 .nf
 185 \&    %N        command name which is running
 186 \&    %m        to_s of main object (self)
 187 \&    %M        inspect of main object (self)
 188 \&    %l        type of string(", ', /, ]), `]' is inner %w[...]
 189 \&    %NNi      indent level. NN is degits and means as same as printf("%NNd").
 190 \&          It can be ommited
 191 \&    %NNn      line number.
 192 \&    %%    %
 193 .fi
 194 For instance, the default prompt mode is defined as follows:
 195 IRB.conf[:PROMPT_MODE][:DEFAULT] = {
 196 .TP
 197 .fi
 198 .B
 199 PROMPT_I => "%N(%m):%03n:%i> ",
 200 .TP
 201 .fi
 202 .B
 203 PROMPT_S => "%N(%m):%03n:%i%l ",
 204 .TP
 205 .fi
 206 .B
 207 PROMPT_C => "%N(%m):%03n:%i* ",
 208 .TP
 209 .fi
 210 .B
 211 RETURN => "%s\\n"}
 212 RETURN is used to printf.
 213 .SH Configurating subirb
 214
 215 .PP
 216 The command line option or IRB.conf specify the default behavior of
 217 (sub)irb. On the other hand, each conf of in the next sction `6. Command'
 218 is used to individually configurate (sub)irb.
 219 If proc is set to IRB.conf[:IRB_RC], its subirb will be invoked after
 220 execution of that proc under giving the context of irb as its
 221 aregument. By this mechanism each subirb can be configurated.
 222 .SH Command
 223
 224 .PP
 225 For irb commands, both simple name and `irb_'\-prefixed name are prepared.
 226 .TP
 227 .fi
 228 .B
 229 exit, quit, irb_exit
 230 Quits (sub)irb.
 231 if you've done cb (see below), exit from the binding mode.
 232
 233 .TP
 234 .fi
 235 .B
 236 conf, irb_context
 237 Displays current configuration. Modifing the configuration is
 238 achieved by sending message to `conf'.
 239 .TP
 240 .fi
 241 .B
 242 conf.back_trace_limit
 243 Sets display lines of backtrace as top n and tail n.
 244 The default value is 16.
 245 .TP
 246 .fi
 247 .B
 248 conf.debug_level = N
 249 Sets debug level of irb.
 250 .TP
 251 .fi
 252 .B
 253 conf.ignore_eof = true/false
 254 Whether ^D (control\-d) will be ignored or not.
 255 If false is set, ^D means quit.
 256 .TP
 257 .fi
 258 .B
 259 conf.ignore_sigint= true/false
 260 Whether ^C (control\-c) will be ignored or not.
 261 If false is set, ^D means quit.  If true,
 262 .nf
 263 \&    during input:   cancel inputing then return to top level.
 264 \&    during execute: abondon current execution.
 265 .fi
 266 .TP
 267 .fi
 268 .B
 269 conf.inf_ruby_mode = true/false
 270 Whether inf\-ruby\-mode or not. The default value is false.
 271 .TP
 272 .fi
 273 .B
 274 conf.inspect_mode = true/false/nil
 275 Specifies inspect mode.
 276 true:  display inspect
 277 false: display to_s
 278 nil:   inspect mode in non math mode,
 279 .nf
 280 \&    non inspect mode in math mode.
 281 .fi
 282 .TP
 283 .fi
 284 .B
 285 conf.irb_level
 286 The level of cb.
 287 .TP
 288 .fi
 289 .B
 290 conf.math_mode
 291 Whether bc mode or not.
 292 .TP
 293 .fi
 294 .B
 295 conf.use_loader = true/false
 296 Whether irb's own file reader method is used when load/require or not.
 297 This mode is globaly affected (irb wide).
 298 .TP
 299 .fi
 300 .B
 301 conf.prompt_c
 302 prompt for a continuating statement (e.g, immediately after of `if')
 303 .TP
 304 .fi
 305 .B
 306 conf.prompt_i
 307 standard prompt
 308 .TP
 309 .fi
 310 .B
 311 conf.prompt_s
 312 prompt for a continuating string
 313 .TP
 314 .fi
 315 .B
 316 conf.rc
 317 Whether ~/.irbrc is read or not.
 318 .TP
 319 .fi
 320 .B
 321 conf.use_prompt = true/false
 322 Prompting or not.
 323 .TP
 324 .fi
 325 .B
 326 conf.use_readline = true/false/nil
 327 Whether readline is used or not.
 328 true: uses
 329 false: doen't use
 330 nil: intends to use readline except for inf\-reuby\-mode (default)
 331 .TP
 332 .fi
 333 .B
 334 conf.verbose=T/F
 335 Whether verbose messages are display or not.
 336 .TP
 337 .fi
 338 .B
 339 cb, irb_change_binding [obj]
 340 Enter new binding which has a distinct scope of local variables.
 341 If obj is given, obj will be self.
 342 .TP
 343 .fi
 344 .B
 345 irb [obj]
 346 Invoke subirb. If obj is given, obj will be self.
 347 .TP
 348 .fi
 349 .B
 350 jobs, irb_jobs
 351 List of subirb
 352 .TP
 353 .fi
 354 .B
 355 fg n, irb_fg n
 356 Switch into specified subirb. The following is candidates of n:
 357 .nf
 358 \&    irb number
 359 \&    thhread
 360 \&    irb object
 361 \&    self(obj which is specified of irb obj)
 362 .fi
 363 .TP
 364 .fi
 365 .B
 366 kill n, irb_kill n
 367 Kill subirb. The means of n is as same as the case of irb_fg.
 368 .SH System variable
 369
 370 .PP
 371
 372 .TP
 373 .fi
 374 .B
 375 _
 376 The latest value of evaluation (it is local)
 377 .SH Session Example
 378
 379 .PP
 380 .nf
 381 \&    $ irb1.8
 382 \&    irb(main):001:0> irb                        # invoke subirb
 383 \&    irb#1(main):001:0> jobs                     # list of subirbs
 384 \&    #0\->irb on main (#<Thread:0x400fb7e4> : stop)
 385 \&    #1\->irb#1 on main (#<Thread:0x40125d64> : running)
 386 \&    nil
 387 \&    irb#1(main):002:0> fg 0                     # switch job
 388 \&    nil
 389 \&    irb(main):002:0> class Foo;end
 390 \&    nil
 391 \&    irb(main):003:0> irb Foo                    # invoke subirb which has the
 392 .fi
 393 .nf
 394 \&    #              context of Foo
 395 .fi
 396 .nf
 397 \&    irb#2(Foo):001:0> def foo                   # define Foo#foo
 398 \&    irb#2(Foo):002:1>   print 1
 399 \&    irb#2(Foo):003:1> end
 400 \&    nil
 401 \&    irb#2(Foo):004:0> fg 0                      # switch job
 402 \&    nil
 403 \&    irb(main):004:0> jobs                       # list of job
 404 \&    #0\->irb on main (#<Thread:0x400fb7e4> : running)
 405 \&    #1\->irb#1 on main (#<Thread:0x40125d64> : stop)
 406 \&    #2\->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
 407 \&    nil
 408 \&    irb(main):005:0> Foo.instance_methods       # Foo#foo is defined asurely
 409 \&    ["foo"]
 410 \&    irb(main):006:0> fg 2                       # switch job
 411 \&    nil
 412 \&    irb#2(Foo):005:0> def bar                   # define Foo#bar
 413 \&    irb#2(Foo):006:1>  print "bar"
 414 \&    irb#2(Foo):007:1> end
 415 \&    nil
 416 \&    irb#2(Foo):010:0>  Foo.instance_methods
 417 \&    ["bar", "foo"]
 418 \&    irb#2(Foo):011:0> fg 0
 419 \&    nil
 420 \&    irb(main):007:0> f = Foo.new
 421 \&    #<Foo:0x4010af3c>
 422 \&    irb(main):008:0> irb f                      # invoke subirb which has the
 423 .fi
 424 .nf
 425 \&    #  context of f (instance of Foo)
 426 .fi
 427 .nf
 428 \&    irb#3(#<Foo:0x4010af3c>):001:0> jobs
 429 \&    #0\->irb on main (#<Thread:0x400fb7e4> : stop)
 430 \&    #1\->irb#1 on main (#<Thread:0x40125d64> : stop)
 431 \&    #2\->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
 432 \&    #3\->irb#3 on #<Foo:0x4010af3c> (#<Thread:0x4010a1e0> : running)
 433 \&    nil
 434 \&    irb#3(#<Foo:0x4010af3c>):002:0> foo         # evaluate f.foo
 435 \&    1nil
 436 \&    irb#3(#<Foo:0x4010af3c>):003:0> bar         # evaluate f.bar
 437 \&    barnil
 438 \&    irb#3(#<Foo:0x4010af3c>):004:0> kill 1, 2, 3# kill job
 439 \&    nil
 440 \&    irb(main):009:0> jobs
 441 \&    #0\->irb on main (#<Thread:0x400fb7e4> : running)
 442 \&    nil
 443 \&    irb(main):010:0> exit                       # exit
 444 .fi
 445 .SH Restrictions
 446
 447 .PP
 448 Because irb evaluates the inputs immediately after the imput is
 449 syntactically completed, irb gives slight different result than
 450 directly use ruby. Known difference is pointed out here.
 451 .SH Declaration of the local variable
 452
 453 .PP
 454 The following causes an error in ruby:
 455
 456 .nf
 457 \&    eval "foo = 0"
 458 \&    foo
 459 \&    \-\-
 460 \&    \-:2: undefined local variable or method `foo' for #<Object:0x40283118> (NameError)
 461 \&    \-\-\-
 462 \&    NameError
 463 .fi
 464
 465 Though, the above will successfully done by irb.
 466
 467 .nf
 468 \&    >> eval "foo = 0"
 469 .fi
 470 .nf
 471 \&    => 0
 472 \&    >> foo
 473 \&    => 0
 474 .fi
 475
 476 Ruby evaluates a code after reading entire of code and determination
 477 of the scope of local variables. On the other hand, irb do
 478 immediately. More precisely, irb evaluate at first
 479
 480 .nf
 481 \&    evel "foo = 0"
 482 .fi
 483
 484 then foo is defined on this timing. It is because of this
 485 incompatibility.
 486 If you'd like to detect those differences, begin...end can be used:
 487
 488 .nf
 489 \&    >> begin
 490 \&    ?>   eval "foo = 0"
 491 \&    >>   foo
 492 \&    >> end
 493 \&    NameError: undefined local variable or method `foo' for #<Object:0x4013d0f0>
 494 \&    (irb):3
 495 \&    (irb_local_binding):1:in `eval'
 496 .fi
 497 .SH Here\-document
 498
 499 .PP
 500 Implementation of Here\-document is incomplete.
 501 .SH Symbol
 502
 503 .PP
 504 Irb can not always recognize a symbol as to be Symbol. Concretely, an
 505 expression have completed, however Irb regard it as continuation line.
 506