irb -- interactive ruby $Release Version: 0.9 $ $Revision$ $Date$ by Keiju ISHITSUKA(keiju@ishitsuka.com) by gotoken-san who is original translater from japanese version =begin = What is irb? irb stands for `interactive ruby'. irb is a tool to execute interactively ruby expressions read from stdin. = Invoking % irb = Usage Use of irb is easy if you know ruby. Executing irb, prompts are displayed as follows. Then, enter expression of ruby. A input is executed when it is syntacticaly completed. dim% irb irb(main):001:0> 1+2 3 irb(main):002:0> class Foo irb(main):003:1> def foo irb(main):004:2> print 1 irb(main):005:2> end irb(main):006:1> end nil irb(main):007:0> And, Readline extesion module can be used with irb. Using Readline is the standard default action if Readline is installed. = Command line option irb.rb [options] file_name opts options: -f suppress read ~/.irbrc -m bc mode (fraction or matrix are available) -d set $DEBUG to true (same as `ruby -d') -Kc same as `ruby -Kc' -r load-module same as `ruby -r' --verbose command input is echoed(default) --noverbose command input isn't echoed --echo commands are echoed immediately before execution(default) --noecho commands aren't echoed immediately before execution --inspect uses `inspect' for output (the default except bc mode) --noinspect doesn't uses inspect for output --readline uses Readline extension module --noreadline doesn't use Readline extension module --prompt prompt-mode --prompt-mode prompt-mode switches prompt mode. Pre-defined prompt modes are `default', `simple', `xmp' and `inf-ruby' --inf-ruby-mode uses prompt appreciate for inf-ruby-mode on emacs. Suppresses --readline. --simple-prompt simple prompt mode --noprompt no prompt --tracer display trace for each execution of commands. --back-trace-limit n displayes backtrace top n and tail n. The default value is 16. --irb_debug n sets internal debug level to n (It shouldn't be used) -v, --version prints the version of irb = Configurations irb reads `~/.irbrc' when it is invoked. If `~/.irbrb' doesn't exist irb try to read in the order `.irbrc', `irb.rc', `_irbrc' then `$irbrc'. The following is altanative to the command line option. To use them type as follows in an irb session. IRB.conf[:IRB_NAME]="irb" IRB.conf[:MATH_MODE]=false IRB.conf[:USE_TRACER]=false IRB.conf[:USE_LOADER]=false IRB.conf[:IGNORE_SIGINT]=true IRB.conf[:IGNORE_EOF]=false IRB.conf[:INSPECT_MODE]=nil IRB.conf[:IRB_RC] = nil IRB.conf[:BACK_TRACE_LIMIT]=16 IRB.conf[:USE_LOADER] = false IRB.conf[:USE_READLINE] = nil IRB.conf[:USE_TRACER] = false IRB.conf[:IGNORE_SIGINT] = true IRB.conf[:IGNORE_EOF] = false IRB.conf[:PROMPT_MODE] = :DEFALUT IRB.conf[:PROMPT] = {...} IRB.conf[:DEBUG_LEVEL]=0 IRB.conf[:VERBOSE]=true == Customizing prompt To costomize the prompt you set a variable IRB.conf[:PROMPT] For example, describe as follows in `.irbrc'. IRB.conf[:PROMPT][:MY_PROMPT] = { # name of prompt mode :PROMPT_I => nil, # normal prompt :PROMPT_S => nil, # prompt for continuated strings :PROMPT_C => nil, # prompt for continuated statement :RETURN => " ==>%s\n" # format to return value } Then, invoke irb with the above prompt mode by % irb --prompt my-prompt Or add the following in `.irbrc'. IRB.conf[:PROMPT_MODE] = :MY_PROMPT Constants PROMPT_I, PROMPT_S and PROMPT_C specifies the format. In the prompt specification, some special strings are available. %N command name which is running %m to_s of main object (self) %M inspect of main object (self) %l type of string(", ', /, ]), `]' is inner %w[...] %NNi indent level. NN is degits and means as same as printf("%NNd"). It can be ommited %NNn line number. %% % For instance, the default prompt mode is defined as follows: IRB.conf[:PROMPT_MODE][:DEFAULT] = { :PROMPT_I => "%N(%m):%03n:%i> ", :PROMPT_S => "%N(%m):%03n:%i%l ", :PROMPT_C => "%N(%m):%03n:%i* ", :RETURN => "%s\n" } RETURN is used to printf. == Configurating subirb The command line option or IRB.conf specify the default behavior of (sub)irb. On the other hand, each conf of in the next sction `6. Command' is used to individually configurate (sub)irb. If proc is set to IRB.conf[:IRB_RC], its subirb will be invoked after execution of that proc under giving the context of irb as its aregument. By this mechanism each subirb can be configurated. = Command For irb commands, both simple name and `irb_'-prefixed name are prepared. --- exit, quit, irb_exit Quits (sub)irb. --- conf, irb_context Displays current configuration. Modifing the configuration is achieved by sending message to `conf'. --- conf.eval_history = N Sets execution result history. N is a integer or nil. If N > 0, the number of historys is N. If N == 0, the number of historys is unlimited. If N is nill, execution result history isn't used(default). --- conf.back_trace_limit Sets display lines of backtrace as top n and tail n. The default value is 16. --- conf.debug_level = N Sets debug level of irb. --- conf.ignore_eof = true/false Whether ^D (control-d) will be ignored or not. If false is set, ^D means quit. --- conf.ignore_sigint= true/false Whether ^C (control-c) will be ignored or not. If false is set, ^D means quit. If true, during input: cancel inputing then return to top level. during execute: abondon current execution. --- conf.inf_ruby_mode = true/false Whether inf-ruby-mode or not. The default value is false. --- conf.inspect_mode = true/false/nil Specifies inspect mode. true: display inspect false: display to_s nil: inspect mode in non math mode, non inspect mode in math mode. --- conf.math_mode Whether bc mode or not. --- conf.use_loader = true/false Whether irb's own file reader method is used when load/require or not. This mode is globaly affected (irb wide). --- conf.prompt_c prompt for a continuating statement (e.g, immediately after of `if') --- conf.prompt_i standard prompt --- conf.prompt_s prompt for a continuating string --- conf.rc Whether ~/.irbrc is read or not. --- conf.use_prompt = true/false Prompting or not. --- conf.use_readline = true/false/nil Whether readline is used or not. true: uses false: doen't use nil: intends to use readline except for inf-ruby-mode (default) # #--- conf.verbose=T/F # Whether verbose messages are display or not. --- cws, chws, irb_change_workspace [obj] obj will be self. If obj is omitted, self will be home-object, or the main object of first started irb. --- pushws, irb_pushws, irb_push_workspace [obj] same as UNIX-shell command pushd. --- popws, irb_popws, irb_pop_workspace same as UNIX-shell command popd --- irb [obj] Invoke subirb. If obj is given, obj will be self. --- jobs, irb_jobs List of subirb --- fg n, irb_fg n Switch into specified subirb. The following is candidates of n: irb number thhread irb object self(obj which is specified of irb obj) --- kill n, irb_kill n Kill subirb. The means of n is as same as the case of irb_fg. --- souce, irb_source path This is a like UNIX-shell command source. evaluate script in path on current context. --- irb_load path, prev irb-version of Ruby's load. = System variable --- _ The latest value of evaluation (it is local) --- __ The history of evaluation values. __[line_no] return an evaluation value of line number. If line_no is a negative, return value before - from latest value. = Session Example dim% ruby irb.rb irb(main):001:0> irb # invoke subirb irb#1(main):001:0> jobs # list of subirbs #0->irb on main (# : stop) #1->irb#1 on main (# : running) nil irb#1(main):002:0> fg 0 # switch job nil irb(main):002:0> class Foo;end nil irb(main):003:0> irb Foo # invoke subirb which has the # context of Foo irb#2(Foo):001:0> def foo # define Foo#foo irb#2(Foo):002:1> print 1 irb#2(Foo):003:1> end nil irb#2(Foo):004:0> fg 0 # switch job nil irb(main):004:0> jobs # list of job #0->irb on main (# : running) #1->irb#1 on main (# : stop) #2->irb#2 on Foo (# : stop) nil irb(main):005:0> Foo.instance_methods # Foo#foo is defined asurely ["foo"] irb(main):006:0> fg 2 # switch job nil irb#2(Foo):005:0> def bar # define Foo#bar irb#2(Foo):006:1> print "bar" irb#2(Foo):007:1> end nil irb#2(Foo):010:0> Foo.instance_methods ["bar", "foo"] irb#2(Foo):011:0> fg 0 nil irb(main):007:0> f = Foo.new # irb(main):008:0> irb f # invoke subirb which has the # context of f (instance of Foo) irb#3(#):001:0> jobs #0->irb on main (# : stop) #1->irb#1 on main (# : stop) #2->irb#2 on Foo (# : stop) #3->irb#3 on # (# : running) nil irb#3(#):002:0> foo # evaluate f.foo 1nil irb#3(#):003:0> bar # evaluate f.bar barnil irb#3(#):004:0> kill 1, 2, 3# kill job nil irb(main):009:0> jobs #0->irb on main (# : running) nil irb(main):010:0> exit # exit dim% = Restrictions Because irb evaluates the inputs immediately after the imput is syntactically completed, irb gives slight different result than directly use ruby. Known difference is pointed out here. == Declaration of the local variable The following causes an error in ruby: eval "foo = 0" foo -- -:2: undefined local variable or method `foo' for # (NameError) --- NameError Though, the above will successfully done by irb. >> eval "foo = 0" => 0 >> foo => 0 Ruby evaluates a code after reading entire of code and determination of the scope of local variables. On the other hand, irb do immediately. More precisely, irb evaluate at first evel "foo = 0" then foo is defined on this timing. It is because of this incompatibility. If you'd like to detect those differences, begin...end can be used: >> begin ?> eval "foo = 0" >> foo >> end NameError: undefined local variable or method `foo' for # (irb):3 (irb_local_binding):1:in `eval' == Here-document Implementation of Here-document is incomplete. == Symbol Irb can not always recognize a symbol as to be Symbol. Concretely, an expression have completed, however Irb regard it as continuation line. =end % Begin Emacs Environment % Local Variables: % mode: text % comment-column: 0 % comment-start: "%" % comment-end: "\n" % End: %