Extracted from:

Programming Ruby
The Pragmatic Programmers’ Guide
Second Edition

This PDF file contains pages extracted from Programming Ruby, published by The Pragmatic Bookshelf.
For more information, visit http://www.pragmaticbookshelf.com.

Note: This extract contains some colored text. is available only in online versions of the books. The printed
versions are black and white. Pagination might vary between the online and printer versions; the content is
otherwise identical.
Copyright © 2004 The Pragmatic Programmers, LLC.

All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form, or by any means, electronic, mechanical, photocopying, recording, or
otherwise, without the prior consent of the publisher.
Contents
F OREWORD TO THE F IRST E DITION xix
F OREWORD TO THE S ECOND E DITION xxi
P REFACE xxii
ROAD M AP xxviii

PART I—FACETS OF R UBY

1 G ETTING S TARTED 2
Installing Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Running Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Ruby Documentation: RDoc and ri . . . . . . . . . . . . . . . . . . . . . 7

2 RUBY. NEW 9
Ruby Is an Object-Oriented Language . . . . . . . . . . . . . . . . . . . 9
Some Basic Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Arrays and Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Blocks and Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Reading and ’Riting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Onward and Upward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3 C LASSES , O BJECTS , AND VARIABLES 23

Inheritance and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Objects and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Class Variables and Class Methods . . . . . . . . . . . . . . . . . . . . . 31
Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Prepared exclusively for a Pragmatic Client vii

4 C ONTAINERS , B LOCKS , AND I TERATORS 40
Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Blocks and Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Containers Everywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5 S TANDARD T YPES 55
Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

6 M ORE ABOUT M ETHODS 74

Defining a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Calling a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

7 E XPRESSIONS 81
Operator Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Miscellaneous Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 83
Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Conditional Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Case Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Variable Scope, Loops, and Blocks . . . . . . . . . . . . . . . . . . . . . 99

8 E XCEPTIONS , C ATCH , AND T HROW 101

The Exception Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Handling Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Raising Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Catch and Throw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

9 M ODULES 110
Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Mixins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Iterators and the Enumerable Module . . . . . . . . . . . . . . . . . . . . 113
Composing Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Including Other Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

10 BASIC I NPUT AND O UTPUT 119

What Is an IO Object? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Opening and Closing Files . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Reading and Writing Files . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Talking to Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
11 T HREADS AND P ROCESSES 127
Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Controlling the Thread Scheduler . . . . . . . . . . . . . . . . . . . . . . 132
Mutual Exclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Running Multiple Processes . . . . . . . . . . . . . . . . . . . . . . . . . 139

12 U NIT T ESTING 143

Test::Unit Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Structuring Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Organizing and Running Tests . . . . . . . . . . . . . . . . . . . . . . . . 151

13 W HEN T ROUBLE S TRIKES 155

Ruby Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Interactive Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Editor Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
But It Doesn’t Work! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
But It’s Too Slow! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

PART II—R UBY IN I TS S ETTING

14 RUBY AND I TS W ORLD 167
Command-Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . 167
Program Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Where Ruby Finds Its Modules . . . . . . . . . . . . . . . . . . . . . . . 172
Build Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

15 I NTERACTIVE RUBY S HELL 174

Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
rtags and xmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

16 D OCUMENTING RUBY 187

Adding RDoc to Ruby Code . . . . . . . . . . . . . . . . . . . . . . . . . 187
Adding RDoc to C Extensions . . . . . . . . . . . . . . . . . . . . . . . . 195
Running RDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Displaying Program Usage . . . . . . . . . . . . . . . . . . . . . . . . . 200
17 PACKAGE M ANAGEMENT WITH RUBY G EMS 203
Installing RubyGems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Installing Application Gems . . . . . . . . . . . . . . . . . . . . . . . . . 204
Installing and Using Gem Libraries . . . . . . . . . . . . . . . . . . . . . 206
Creating Your Own Gems . . . . . . . . . . . . . . . . . . . . . . . . . . 211

18 RUBY AND THE W EB 222

Writing CGI Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Improving Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Choice of Web Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
SOAP and Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

19 RUBY T K 241
Simple Tk Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Binding Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Translating from Perl/Tk Documentation . . . . . . . . . . . . . . . . . . 251

20 RUBY AND M ICROSOFT W INDOWS 253

Getting Ruby for Windows . . . . . . . . . . . . . . . . . . . . . . . . . 253
Running Ruby Under Windows . . . . . . . . . . . . . . . . . . . . . . . 254
Win32API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Windows Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

21 E XTENDING RUBY 261

Your First Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
Ruby Objects in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
The Jukebox Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Ruby Type System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Creating an Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Embedding a Ruby Interpreter . . . . . . . . . . . . . . . . . . . . . . . . 287
Bridging Ruby to Other Languages . . . . . . . . . . . . . . . . . . . . . 290
Ruby C Language API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
 PART III—R UBY C RYSTALLIZED
22 T HE RUBY L ANGUAGE 302
Source Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
The Basic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Variables and Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Predefined Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Boolean Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 326
if and unless Expressions . . . . . . . . . . . . . . . . . . . . . . . 328
case Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Loop Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Method Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Invoking a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Aliasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Module Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Blocks, Closures, and Proc Objects . . . . . . . . . . . . . . . . . . . . . 341
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Catch and Throw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

23 D UCK T YPING 349

Classes Aren’t Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Coding like a Duck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Standard Protocols and Coercions . . . . . . . . . . . . . . . . . . . . . . 355
Walk the Walk, Talk the Talk . . . . . . . . . . . . . . . . . . . . . . . . 361

24 C LASSES AND O BJECTS 362

How Classes and Objects Interact . . . . . . . . . . . . . . . . . . . . . . 362
Class and Module Definitions . . . . . . . . . . . . . . . . . . . . . . . . 370
Top-Level Execution Environment . . . . . . . . . . . . . . . . . . . . . 376
Inheritance and Visibility . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Freezing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

25 L OCKING RUBY IN THE S AFE 379

Safe Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
Tainted Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
26 R EFLECTION , O BJECT S PACE , AND D ISTRIBUTED RUBY 384
Looking at Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Looking at Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Calling Methods Dynamically . . . . . . . . . . . . . . . . . . . . . . . . 388
System Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Tracing Your Program’s Execution . . . . . . . . . . . . . . . . . . . . . 393
Marshaling and Distributed Ruby . . . . . . . . . . . . . . . . . . . . . . 395
Compile Time? Runtime? Anytime! . . . . . . . . . . . . . . . . . . . . . 400

PART IV—R UBY L IBRARY R EFERENCE

27 BUILT- IN C LASSES AND M ODULES 402
Alphabetical Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Bignum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Comparable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Continuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Enumerable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Errno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
FalseClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
File::Stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
FileTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Fixnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
GC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
IO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Marshal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514
MatchData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
NilClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Numeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
 Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
ObjectSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
Proc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Process::GID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
Process::Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 570
Process::Sys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
Process::UID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Regexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
Struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
Struct::Tms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Symbol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
Thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612
ThreadGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
TrueClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629
UnboundMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630

28 S TANDARD L IBRARY 632

Abbrev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Base64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
BigDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637
CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
CGI::Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
Complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
CSV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Curses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Date/DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
DBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
Delegator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Digest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
DL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
dRuby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
English . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
Enumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651
erb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Etc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
expect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
FileUtils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
Forwardable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
ftools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
GDBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
GetoptLong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
GServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664
Iconv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
IO/Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666
IPAddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
jcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
mathn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674
Mutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
Mutex_m . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Net::FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Net::HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
Net::IMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
Net::POP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
Net::SMTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
Net::Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
NKF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
Observable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
open-uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
Open3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688
OpenStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689
OptionParser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
ParseDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Pathname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693
PP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
PrettyPrint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696
Profiler_ _ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
PStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
PTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
Rational . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
readbytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
Readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Resolv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
REXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
Rinda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
RSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Scanf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
SDBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Shellwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
Singleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
StringIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
StringScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Tempfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
Test::Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
ThreadsWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725
Tk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
tmpdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
TSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
un . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
WeakRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
WEBrick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
Win32API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
WIN32OLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
XMLRPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
YAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
Zlib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
 PART V—A PPENDIXES
A S OCKET L IBRARY 740
BasicSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
IPSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
TCPSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
SOCKSSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
TCPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
UDPSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
UNIXSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753
UNIXServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754

B MKMF R EFERENCE 755

mkmf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755

C S UPPORT 758
Web Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
Download Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Usenet Newsgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Mailing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759

D B IBLIOGRAPHY 761

I NDEX 762

S UMMARY TABLES 797

List of Tables
2.1 Example variable and class names . . . . . . . . . . . . . . . . . . . . 15
5.1 Character class abbreviations . . . . . . . . . . . . . . . . . . . . . . . 68
7.1 Common comparison operators . . . . . . . . . . . . . . . . . . . . . . 89
11.1 Two threads in a race condition . . . . . . . . . . . . . . . . . . . . . . 135
13.1 Debugger commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
14.1 Environment variables used by Ruby . . . . . . . . . . . . . . . . . . . 172
15.1 irb command-line options . . . . . . . . . . . . . . . . . . . . . . . . . 175
17.1 Version operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
18.1 Command-line options for erb . . . . . . . . . . . . . . . . . . . . . . 230
21.1 C/Ruby data type conversion functions and macros . . . . . . . . . . . 266
22.1 General delimited input . . . . . . . . . . . . . . . . . . . . . . . . . . 304
22.2 Substitutions in double-quoted strings . . . . . . . . . . . . . . . . . . 306
22.3 Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
22.4 Ruby operators (high to low precedence) . . . . . . . . . . . . . . . . . 324
25.1 Definition of the safe levels . . . . . . . . . . . . . . . . . . . . . . . . 383
27.1 Class Array: pack directives . . . . . . . . . . . . . . . . . . . . . . . 414
27.2 Class File: match-mode constants . . . . . . . . . . . . . . . . . . . . 447
27.3 Class File: path separators . . . . . . . . . . . . . . . . . . . . . . . . 449
27.4 Class File: open-mode constants . . . . . . . . . . . . . . . . . . . . . 451
27.5 Class File: lock-mode constants . . . . . . . . . . . . . . . . . . . . . 455
27.6 Class IO: mode strings . . . . . . . . . . . . . . . . . . . . . . . . . . 483
27.7 Module Kernel: sprintf flag characters . . . . . . . . . . . . . . . . 510
27.8 Module Kernel: sprintf field types . . . . . . . . . . . . . . . . . . . 511
27.9 Module Kernel: file tests with a single argument . . . . . . . . . . . . 512
27.10 Module Kernel: file tests with two arguments . . . . . . . . . . . . . . 512
27.11 Class Numeric: methods and subclasses . . . . . . . . . . . . . . . . . 543
27.12 Class Numeric: divmod, modulo, and remainder . . . . . . . . . . . . 544
27.13 Class String: backslash sequences in substitution strings . . . . . . . . 593
27.14 Class String: unpack directives . . . . . . . . . . . . . . . . . . . . . 603
27.15 Class Time: strftime directives . . . . . . . . . . . . . . . . . . . . . 627
28.1 Class ERB: inline directives . . . . . . . . . . . . . . . . . . . . . . . . 653
28.2 Class OptionParser: option definitions . . . . . . . . . . . . . . . . . 691

Prepared exclusively for a Pragmatic Client xvii

List of Figures
3.1 Variables hold object references. . . . . . . . . . . . . . . . . . . . . . 39
4.1 How arrays are indexed . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.1 Ruby exception hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . 103
12.1 Roman numerals generation (with bugs) . . . . . . . . . . . . . . . . . 145
12.2 Test::Unit assertions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
13.1 Sample irb session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
13.2 Comparing variable access costs using benchmark . . . . . . . . . . . . 163
16.1 Browse RDoc output for class counter . . . . . . . . . . . . . . . . . . 188
16.2 Browse RDoc output when source has comments . . . . . . . . . . . . 189
16.3 Using ri to read documentation . . . . . . . . . . . . . . . . . . . . . . 190
16.4 Document for class Proc generated by RDoc/ri . . . . . . . . . . . . . 191
16.5 Ruby source file documented with RDoc . . . . . . . . . . . . . . . . . 196
16.6 C source file documented with RDoc . . . . . . . . . . . . . . . . . . . 198
16.7 Sample program using RDoc::usage . . . . . . . . . . . . . . . . . . . 201
16.8 Help generated by sample program . . . . . . . . . . . . . . . . . . . . 202
17.1 MomLog package structure . . . . . . . . . . . . . . . . . . . . . . . . 220
18.1 Sample CGI Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
18.2 Erb processing a file with loops . . . . . . . . . . . . . . . . . . . . . . 232
19.1 Drawing on a Tk Canvas . . . . . . . . . . . . . . . . . . . . . . . . . 248
21.1 Wrapping objects around C data types . . . . . . . . . . . . . . . . . . 272
21.2 Building an extension . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
22.1 State transitions for boolean range . . . . . . . . . . . . . . . . . . . . 327
24.1 A basic object, with its class and superclass . . . . . . . . . . . . . . . 363
24.2 Adding a metaclass to Guitar . . . . . . . . . . . . . . . . . . . . . . 364
24.3 Adding a virtual class to an object . . . . . . . . . . . . . . . . . . . . 367
24.4 An included module and its proxy class . . . . . . . . . . . . . . . . . 369
27.1 Standard exception hierarchy . . . . . . . . . . . . . . . . . . . . . . . 441
27.2 Method#arity in action . . . . . . . . . . . . . . . . . . . . . . . . . 523

Prepared exclusively for a Pragmatic Client xviii