← Back to branch summary

~ubuntu-branches/ubuntu/hardy/ruby1.8/hardy-updates

« back to all changes in this revision

Viewing changes to doc/irb/irb.rd

  • Committer: Bazaar Package Importer
  • Author(s): akira yamada
  • Date: 2007-03-13 22:11:58 UTC
  • mfrom: (1.1.5 upstream)
  • Revision ID: james.westby@ubuntu.com-20070313221158-h3oql37brlaf2go2
Tags: 1.8.6-1
http://bugs.debian.org/410018
* new upstream version, 1.8.6.
* libruby1.8 conflicts with libopenssl-ruby1.8 (< 1.8.6) (closes: #410018)
* changed packaging style to cdbs from dbs.

Show diffs side-by-side

added added

removed removed

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