Programming Ruby (2nd edition) ppt

Developers the world over talk about
Programming Ruby and the Ruby language. . .
“Ruby is a wonderf ully powerful and useful language, and whenever I’m working
with it, this book is at my side.”
Martin Fowler, Chief Scientist, Though tWorks
“If your world revolves aroun d Java, as mine did, then you need this outstanding book
to learn all the wonderful things you’re missing. There ’s just one c a tc h: yo u’ll be
spoiled from then on. Indee d, after re ading just a few pages of Programming Ruby,
programming in any language other than Ruby will feel like you’re pushing rope.”
Mike Clark, Author and Consultant
“Ruby is sma rt, elegant, and fun, and it deserves a book that’s smart, elegant, and fun.
The first edition of Programming Ruby was su c h a book; the second edition is even
better.”
James Britt, Administrato r,

“The best reaso n to learn a new programming language is to learn to think differently.
The best way to learn to thin k the Ruby way is to read Programming Ruby. Several
years ago, with the first edition of this book, I did just that. Since then, I’ve had a
constant stream of enjoyable Ruby prog ramming experiences. This is d ue in no
insignificant part to the quality of the source from which I learned the language. I’m
not the only person I’ve heard say that every language sho uld have a book like this.”
Chad Fowler, Codirec tor, Ruby Central, Inc.
“The PickAxe got me started on Ruby. It is still the first book I turn to.”
Ryan Davis, Founde r, Seattle.rb
“This book changed my life. Sounds rather cliché d, but it’s the truth. After six y ears
and 300,000 lines of Java code, I needed a change. That change occurred upon reading
the first edition of this book. With the support of a solid community and ever-growing
foundation of superb libraries, I founded a company that largely profits from applying
Ruby to solve real-world problems. Ruby is ready for prime time, and this new
version of the PickAxe will show a waiting world what a gem Ruby really is.”

Rich Kilmer, President and CEO, InfoE ther LLC
“The first edition of PickAxe has been a desk-side companion for years. The second
edition will be an eagerly awaited replacem ent.”
Tom Enebo, JRuby Developer
“The first edition of Programming Ruby brought about no less than the introduction of
Ruby on a large scale ou tside of Japan, in the process becoming the de fa cto standard
published language reference and an oft-cited m odel of clear, effective technical
writing. The appearance of the second, expanded edition is exciting for Ruby
programmers around the world and will no doubt attract a fresh wave of newcomers to
this elegant, versatile language.”
David A. Black, Ph.D., Codirector, Ruby Central, Inc.
“Ruby is my de finite choice for all scripting and proto typing issues, and this book will
help you to discover its usefulness as well as its beauty. Apart from that, it’s really fun
to re ad!”
Robert Klemme
“I bought the first edition of this b ook the day it was released and had a fantastic time
using it to learn Ruby. I eventually bought a second copy to keep at home. But Ruby
has changed since then. I’m delighted that this second edition of Programming Ruby
is available to help a new round of programmers learn about this fantastic, beautiful
languag e. And it’s not just good news for Ruby newbies, o f course—like me, most
Ruby developers will want a copy (no, ma ke that two) so that all of the details abo ut
today’s Ruby will be close at hand.”
Glenn Vanderburg, Software Architect, Countrywide Financial
“Ruby is one of those great languages that takes an afternoon to start using and years
(maybe a lifetime) to master. In C, I’m always having to work around the limitations
of the language; in Ruby, I’m always d iscovering a neate r, cleaner, more efficient way
to d o thin gs. Programming Ruby is the essential reference to the Ruby language . More
than just teaching you the syntax, it teaches you the spirit and the feel of the language.”
Ben Giddings
“Confuciu s said, “What you hear, you forget.” He also said, “Wh at you do you

understand.” But it’s not easy to actually “do ” things unless you’re using a great
languag e with strength in quick and clean pr ototyping . In my case, this language is
Ruby! Thank you!”
Michael Neumann
Programming Ruby
The Pragm atic Programmers ’ Guide
Second Editio n
Dave Thomas
with
Chad Fowler
and An dy Hunt
The Pragma tic Bookshelf
Raleigh, North Carolina Dallas, Texas
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as
trademarks. Where those designations appear in this book, and The Pragmatic Programmers, LLC, was aware
of a trademark claim, the designations have been printed in initial capital letters or in all capitals.
Every precaution was taken in the preparation of this book. However, the publisher assumes no responsibility
for errors or omissions or for damages that may result from the use of information (including program
listings) contained herein.
This book is a heavily revised version of the book Programming Ruby, originally published by Addison
Wesley. This book is printed with their permission.
Our Pragmatic courses, workshops, and other products can help you and your team create better software
and have more fun. For more information, as well as the latest Pragmatic titles, please visit us at

Copyright
©
2005 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.
Printed in the United States of A merica.

ISBN 0-9745140-5-5
Text printed on acid-free paper.
First Printing, October 2004
Version: 2004-9-30
Contents
FOREWORD TO THE FIRST EDITION xvii
FOREWORD TO THE SECOND EDITION xix
PREFACE xx
ROAD MAP xxvi
PART I—FACETS OF RUBY
1 G
ETTING STARTED 2
Installing Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Running Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Ruby Documenta tion: RDoc and ri . . . . . . . . . . . . . . . . . . . . . 7
2 RUBY.NEW 9
Ruby Is an Object-Oriented Language . . . . . . . . . . . . . . . . . . . 9
Some Basic Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Arrays and Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Control Stru ctures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Regular Expre ssions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Blocks and Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Reading and ’Riting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Onward and Upward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3 CLASSES, OBJECTS, AND VARIABLES 23
Inheritance and Message s . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Objects and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Class Variables and Class Methods . . . . . . . . . . . . . . . . . . . . . 31
Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Prepared exclusively for Yeganefar v
CONTENTS vi
4 CONTAINERS, BLOCKS, AND ITERATORS 40
Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Blocks and Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Containers Everywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5 STANDARD TYPES 55
Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Regular Expre ssions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6 MORE ABOUT METHODS 74
Defining a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Calling a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
7 EXPRESSIONS 81
Operator Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Miscellaneous Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 83
Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Conditional Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Case E xpressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Variable Scope, Loops, and Blocks . . . . . . . . . . . . . . . . . . . . . 99
8 EXCEPTIONS, CATCH, AND THROW 101
The Exception Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Handling Exception s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Raising Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Catch and Th row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
9 MODULES 110
Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Mixins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Iterators and the Enumerable Module . . . . . . . . . . . . . . . . . . . . 113
Composing Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3
Including Other Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
10 BASIC INPUT AND OUTPUT 119
What Is an IO Object? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Opening and Closing Files . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Reading and Writing Files . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Talking to Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Prepared exclusively for Yeganefar
CONTENTS vii
11 THREADS AND PROCESSES 127
Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Controlling the Thread Scheduler . . . . . . . . . . . . . . . . . . . . . . 132
Mutual Exclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Running Multiple Processes . . . . . . . . . . . . . . . . . . . . . . . . . 139
12 UNIT TESTING 143
Test::Unit Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Structuring Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Organizing and Running Tests . . . . . . . . . . . . . . . . . . . . . . . . 151
13 WHEN TROUBLE STRIKES 155
Ruby Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Interactive Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Editor Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
But It Doesn’t Work! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
But It’s Too Slow! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
PART II—RUBY IN ITS SETTING
14 R
UBY AND ITS WORLD 167
Command-Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . 167
Program Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Where Ru by Finds Its Modules . . . . . . . . . . . . . . . . . . . . . . . 172
Build Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
15 INTERACTIVE RUBY SHELL 174
Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
rtags and xmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
16 DOCUMENTING RUBY 187
Adding RDoc to Ruby Code . . . . . . . . . . . . . . . . . . . . . . . . . 187
Adding RDoc to C Exten sions . . . . . . . . . . . . . . . . . . . . . . . . 195
Running RDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Displaying Program Usage . . . . . . . . . . . . . . . . . . . . . . . . . 200
Prepared exclusively for Yeganefar
CONTENTS viii
17 PACKA GE MANAGEMENT WITH RUBYGEMS 203
Installing RubyGems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Installing Ap plication Gems . . . . . . . . . . . . . . . . . . . . . . . . . 204
Installing and Using Gem Libraries . . . . . . . . . . . . . . . . . . . . . 206
Creating Your Own Gems . . . . . . . . . . . . . . . . . . . . . . . . . . 211
18 RUBY AND THE WEB 222
Writing CGI Scr ipts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Improving Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Choice of Web Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
SOAP an d Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
19 RUBY TK 241
Simple Tk Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Binding Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Translating from Perl/Tk Docum e ntation . . . . . . . . . . . . . . . . . . 251
20 RUBY AND MICROSOFT WINDOWS 253
Getting Ruby for Windows . . . . . . . . . . . . . . . . . . . . . . . . . 253
Running Ruby Und er Windows . . . . . . . . . . . . . . . . . . . . . . . 254
Win32API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Windows Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
21 EXTENDING 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 Ru by to Other Languages . . . . . . . . . . . . . . . . . . . . . 290
Ruby C Language API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Prepared exclusively for Yeganefar
CONTENTS ix
PART III—RUBY CRYSTALLIZED
22 T
HE RUBY LANGUAGE 302
Source La yout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
The Basic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Variables and Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Predefined Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
Boolean Expression s . . . . . . . . . . . . . . . . . . . . . . . . . . 326
if and unless Expressions . . . . . . . . . . . . . . . . . . . . . . . 328
case Expre ssions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Loop Co nstructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Method Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Invoking a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Aliasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6
Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Module Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Blocks, Closu res, and Proc Objects . . . . . . . . . . . . . . . . . . . . . 341
Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Catch and Th row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
23 DUCK TYPING 349
Classes Aren’t Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Coding like a Duck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Standard Protocols and Coercions . . . . . . . . . . . . . . . . . . . . . . 355
Walk the Walk, Talk the Talk . . . . . . . . . . . . . . . . . . . . . . . . 361
24 CLASSES AND OBJECTS 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 LOCKING RUBY IN THE SAFE 379
Safe Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 0
Tainted Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Prepared exclusively for Yeganefar
CONTENTS x

26 REFLECTION, OBJECTSPACE, AND DISTRIBUTED RUBY 384
Lookin g at Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Lookin g at Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Calling Me thods Dynamically . . . . . . . . . . . . . . . . . . . . . . . . 388
System Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Tracing Your Program’s Execution . . . . . . . . . . . . . . . . . . . . . 393
Marshaling and Distributed Ruby . . . . . . . . . . . . . . . . . . . . . . 395
Compile Time? Runtim e? Anytime! . . . . . . . . . . . . . . . . . . . . . 400
PART IV—RUBY LIBRARY REFERENCE
27 B
UILT-IN CLASSES AND MODULES 402
Alphabetical Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Bignum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 3
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Comparable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 6
Continuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
Enumerable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 3
Errno . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
FalseClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 3
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
File::Stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6
FileTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Fixnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
GC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 0
IO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Marshal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 4
MatchData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522
Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
NilClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Numeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 1
Prepared exclusively for Yeganefar
CONTENTS xi
Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
ObjectSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557
Proc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 2
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 STANDARD LIBRARY 632
Abbrev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
Base64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
Benchmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636
BigDecimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 7
CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638
CGI::Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
Complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 1
CSV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Curses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643
Date/DateTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
DBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
Delegator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Digest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
DL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
dRuby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
English . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 0
Enumerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 1
erb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Etc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
expect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Fcntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
Prepared exclusively for Yeganefar
CONTENTS xii
FileUtils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658
Forwardable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659
ftools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660

GDBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662
GetoptLong . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 3
GServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4
Iconv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665
IO/Wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 6
IPAddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
jcode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
mathn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673
Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 4
Mutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
Mutex_m . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 6
Net::FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Net::HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
Net::IMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
Net::POP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681
Net::SMTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
Net::Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
NKF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
Observable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 5
open-uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686
Open3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687
OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 8
OpenStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 9
OptionParser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
ParseDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692
Pathname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693

PP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694
PrettyPrint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 6
Profiler_ _ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697
PStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698
PTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
Rational . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
readbytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701
Readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Prepared exclusively for Yeganefar
CONTENTS xiii
Resolv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
REXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
Rinda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
RSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Scanf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
SDBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Shellwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 1
Singleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712
SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
StringIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
StringScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
Sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Tempfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
Test::Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 1
thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
ThreadsWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723

Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 5
Tk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
tmpdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
TSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
un . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
WeakRef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 2
WEBrick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 3
Win32API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734
WIN32OLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
XMLRPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736
YAML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
Zlib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
Prepared exclusively for Yeganefar
CONTENTS xiv
PART V—APPENDIXES
A S
OCKET LIBRARY 740
BasicSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
IPSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
TCPSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748
SOCKSSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
TCPServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
UDPSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751
UNIXSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 3
UNIXServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 4
B MKMF REFERENCE 755

mkmf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
C SUPPORT 758
Web Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
Download Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Usenet Newsgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Mailing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
D BIBLIOGRAPHY 761
INDEX 762
SUMMARY TABLES 797
Prepared exclusively for Yeganefar
List o f Tables
2.1 Example variable and class names . . . . . . . . . . . . . . . . . . . . 15
5.1 Character class abbreviations . . . . . . . . . . . . . . . . . . . . . . . 68
7.1 Common comparison operators . . . . . . . . . . . . . . . . . . . . . . 89
11.1 Two thr e ads in a race condition . . . . . . . . . . . . . . . . . . . . . . 135
13.1 Debugger commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
14.1 Environm ent 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 d ouble-quoted strings . . . . . . . . . . . . . . . . . . 306
22.3 Reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
22.4 Ruby operator s (high to low precedence) . . . . . . . . . . . . . . . . . 324
25.1 Definition of the safe levels . . . . . . . . . . . . . . . . . . . . . . . . 383
27.1 Class Array: pack directives . . . . . . . . . . . . . . . . . . . . . . . 414
27.2 Class File: matc h-mode constants . . . . . . . . . . . . . . . . . . . . 447
27.3 Class File: pa th separators . . . . . . . . . . . . . . . . . . . . . . . . 449
27.4 Class File: open-mode constants . . . . . . . . . . . . . . . . . . . . . 451

27.5 Class File: lock-mode constants . . . . . . . . . . . . . . . . . . . . . 455
27.6 Class IO: mo de strings . . . . . . . . . . . . . . . . . . . . . . . . . . 483
27.7 Module Kernel: sprintf flag characters . . . . . . . . . . . . . . . . 510
27.8 Module Kernel: sprintf field types . . . . . . . . . . . . . . . . . . . 51 1
27.9 Module Kernel: file tests with a single argum e nt . . . . . . . . . . . . 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 dir e ctives . . . . . . . . . . . . . . . . . . . . . 603
27.15 Class Time: strftime dire ctives . . . . . . . . . . . . . . . . . . . . . 627
28.1 Class ERB: inline directives . . . . . . . . . . . . . . . . . . . . . . . . 653
28.2 Class OptionParser: option defin itions . . . . . . . . . . . . . . . . . 691
Prepared exclusively for Yeganefar xv
List o f Figures
3.1 Variables hold object references. . . . . . . . . . . . . . . . . . . . . . 39
4.1 How arrays are in dexed . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.1 Ruby exception hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . 103
12.1 Roman numerals generation (with bugs) . . . . . . . . . . . . . . . . . 145
12.2 Test::Unit assertion s . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 wh en source has comments . . . . . . . . . . . . 189
16.3 Using r i to read documentation . . . . . . . . . . . . . . . . . . . . . . 190
16.4 Document for class Proc generated by RDoc/ri . . . . . . . . . . . . . 191
16.5 Ruby source file doc umented with RDoc . . . . . . . . . . . . . . . . . 196
16.6 C source file documented with RDo c . . . . . . . . . . . . . . . . . . . 198
16.7 Sample program using RDoc::usage . . . . . . . . . . . . . . . . . . . 201
16.8 Help generated by sample progr am . . . . . . . . . . . . . . . . . . . . 202

17.1 MomLog pa c kage 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 extensio n . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
22.1 State transitions for boolean range . . . . . . . . . . . . . . . . . . . . 32 7
24.1 A basic object, with its class and superclass . . . . . . . . . . . . . . . 363
24.2 Adding a metaclass to Guitar . . . . . . . . . . . . . . . . . . . . . . 364
24.3 Adding a virtu al class to an object . . . . . . . . . . . . . . . . . . . . 367
24.4 An included module and its prox y class . . . . . . . . . . . . . . . . . 369
27.1 Standard exception hierarchy . . . . . . . . . . . . . . . . . . . . . . . 441
27.2 Method#arity in action . . . . . . . . . . . . . . . . . . . . . . . . . 523
Prepared exclusively for Yeganefar xvi
Foreword to the
First Edition
Man is driven to create; I know I really love to create things. And while I’m not good
at painting, drawing , or music, I can write software.
Shortly after I was intr oduced to computers, I became interested in programming lan-
guages. I believed that an ideal programming language m ust be attainable, and I wanted
to be the desig ner of it. Later, after gaining some experience, I realized that this kind of
ideal, all-purpose language might be more difficult than I had thoug ht. But I was still
hoping to design a language that would work for most of the job s I d id everyday. That
was my dream as a student.
Years later I ta lked with colleagues about scripting languages, the ir power a nd po ssi-
bility. As an object-oriented fan for more than fifteen years, it seemed to me that OO
programming was very suitable for scrip ting too. I did some research on the ’n et for a
while, but the candidates I found, Perl and Python, were not exactly what I was look-
ing for. I wanted a language more powerful than Perl and more object-oriented than
Python.

Then, I remembered m y old dream and decided to design my own language. At first I
was just toying around with it at work. But gradually it gr ew to be a tool good enough
to replace Perl. I named it Ruby—after the p recious red stone—and released it to the
public in 1995.
Since then a lot of people have become interested in Ruby. Believe it or not, Ruby is
actually more popular than Python in Japan right now. I hop e that eventually it will be
just as we ll received all over the world.
I believe that the purpose of life is, at least in part, to be happy. Based on this belief,
Ruby is designed to make programming not only easy but also fun. It allows you to
concentr ate on the creative side of pr ogrammin g, with less stress. If you don’t believe
me, read this book and try Ruby. I’m sure you’ll find ou t for yourself.
I’m very thankful to the people who have joined the Ruby com munity; they have h e lped
me a lot. I alm ost feel like Ruby is one of my children, but in fact, it is the result of the
Prepared exclusively for Yeganefar xvii
FOREWORD xviii
combined efforts of many people. Without their help, Ruby could never have bec ome
what it is.
I am especially thankful to the authors of this book, Dave Thomas and Andy Hunt.
Ruby has never been a well-documented language. Because I have always preferred
writing programs over writing do cuments, the Ruby manuals tend to be less thorough
than they should be. You had to read the sourc e to know the exact behavior of the
languag e. But now Dave and Andy have done the work fo r yo u.
They became interested in a lesser-known language from the Far East. They researched
it, r e ad thousands of lines of sourc e code, wr ote uncountable test scripts and e-mails,
clarified th e ambiguous behavior of the language, found bugs (and even fixed so me of
them), and fina lly com piled this great book. Ruby is certainly well documented now!
Their work on this bo ok has not been trivial. While they were writing it, I was modi-
fying the language itself. But we worked together o n the updates, and this book is as
accurate as possible.
It is my hope that both Ruby a nd th is book will serve to make your programming easy

and enjoyable. Have fun!
Yukihiro Matsumoto, a .k.a. “Matz”
Japan, October 2000
Prepared exclusively for Yeganefar
Foreword to the
Second Edition
No one in 1993 would have believed that an object-oriented language created by a
Japanese amateur language designer would end up bein g used worldwide and that the
languag e would become almost as popular as Perl. It was insane. I a dmit that. I didn’t
believe it either.
But it happened, far exceeding my expectations. It was caused—at least in part—by
the first edition of this book . The famous Pragmatic Programmers chose a dynamic
languag e that was virtually unknown to anyone outside of Japan and w rote a good
book about it. It was just like a miracle.
That’s now history. The future starts now. We have the secon d edition of Programming
Ruby, which is better than the first one. It’s no lo nger a miracle. This time, the grown-
up Ruby community helped to develop the book. I just needed to sit and watch the
community working together.
I really a ppreciate the Pragmatic Program mers, Dave Thomas and A ndy Hunt, and
other p eople fro m the community who helped with this bo ok (guys, sorry f or not nam-
ing you per sonally). I love the friendliness of the Ruby commun ity. It’s the best soft-
ware community I have ever seen. I also appreciate every programmer in the world who
uses Ruby.
The stone ha s started rolling. It will became a great mountain and fill the whole earth.
Yukihiro Matsumoto, a .k.a. “Matz”
Japan, August 2004
Prepared exclusively for Yeganefar xix
Preface
This book is the second ed ition of the PickA xe, as Programming Ruby is known to
Rubyists. It is a tutorial and reference for the Ruby programming language. If you have

the first edition, you’ll find that this version is a significant rewrite.
When Andy and I wro te the first edition, we h ad to explain the background and appeal
of Ruby. Among other thin gs, we wrote “Whe n we discovered Ruby, we realize d that
we’d found what we’d been looking for. More than any other lang uage with which we
have worked, Ruby stays out of your way. You can concentrate on solving the problem
at hand, instead of struggling with compiler and language issues. That’s how it can help
you become a better programmer: b y giving you the chance to spend your time creating
solutions for your users, not for the compiler.”
That belief is even stronger today. Four years later. Ruby is still our language of choice:
I use it for client applicatio ns, I use it to run our publishing business, and I use it for all
those little programming jobs I do just to get things runnin g smoothly.
In those four years, Ruby has progressed nicely. A large number of methods have been
added to the built-in classes and modules, and the size of the standard library (those
libraries included in the Ruby distribution) has grown tremendously. The community
now has a standard documentation system (RDoc), and RubyGems may well become
the system of ch oice for packaging Ruby code for distribution.
This change has been wonderful, but it left the o riginal PickAxe looking a tad dated.
This book remedies that: like its predec essor, it is written for the very latest version of
Ruby.
Ruby Versions
This version of the PickAxe documents Ruby 1.8 (and in particular covers changes
incorporated into Ruby 1.8.2).
1
1. Ruby version numbering follows the same scheme used for many other open-source projects. Releases
with even subversion numbers—1.6, 1.8, and so on—are stable, public releases. These are the releases that
are prepackaged and made available on the various Ruby Web sites. Development versions of the software
Prepared exclusively for Yeganefar xx
PREFACE xxi
Exactly what version of Ruby did I use to wr ite this book? Let’s ask Ru by.
% ruby -v

ruby 1.8.2 (2004-08-24) [powerpc-darwin7.5.0]
This illustrates an important point. M ost of the cod e samples you see in this book
are actually executed ea c h time I format the book. Wh e n you see some ou tput from a
program, that output was produced by running the co de and insertin g the results back
into the book.
Changes in t he Book
Apart from the updates to support Ruby 1.8, you’ll find that the book has changed
somewhat from the original editio n.
In the first half of the book, I’ve added six new chapters. Getting Started is a more
complete introduction to g etting up-and-running with Ruby th a n we had in the first
book. The secon d new chapter, Unit Testing, reflects a growing emphasis on using
testing among Rub yists. Three new chapte rs cover tools for the Ruby programm er: irb
for experimentin g with Ruby, RDoc for documenting your code, and R ubyGems for
packing code for distribution. Finally, a new chapte r covers duck typing, that slightly
slippery philosophy of programming that fits in so well with the ideas behind Ruby.
That’s not all that’s n ew. You’ll also find that th e chapter on threads ha s been extended
significantly with a discussion on synchronization and that the chapter on writing Ruby
extensions has been largely rewritten. The chapter on Web programming now discusses
alternative templating systems and has a section on SOAP. The language refere nce
chapter has been significantly extended (particularly when dealing with the new rules
for blocks, procs, breaks, and returns).
The next quarter of the book, which documents the built-in classes and modules, has
more than 250 significant changes. Ma ny of them are new methods, some are depre-
cated old methods, and some are methods with significant new behavior. You’ll also
find a number of new modules and classes documented.
Finally, the book includes a section on the standard library. T he librar y has grown
extensively sin c e Ruby 1.6 and is now so big that I couldn’t document it to any level
of detail without making the b ook thou sands of pages long. At the same time, th e
Ruby Documentation project has been busy adding RDoc documentation to the library
source itself. (I explain RDoc in Chapter

16
on page
187
.) This means that you will
increasingly be able to get accurate, up-to-date documentation on a library module
have odd subversion numbers, such as 1.7 and 1.9. These you’ll have to download and build for yourself, as
described on page
3.
Prepared exclusively for Yeganefar
PREFACE xxii
using the ri utility that comes with your Ruby distribution. As a consequence of all
this, I decided to change the sty le of the library documentation—it is now a road map
to available libraries, showing code samples and describing the overall use. I’ll leave
the lower-level details to RDoc.
Throu ghout the book I’ve tried to mark changes between 1.6 and 1.8 using a small
symbol in the margin,
1.8
like the one he re. One change I didn’t make: I decided to continue
to use the word we when talking about the authors in the body of the book. Many of the
words there come fr om the first edition, and I certainly don’t want to claim any credit
for Andy’s work on that book.
In all, this book is a significant overhaul of the first version. I hope you find it useful.
Resources
Visit the Ruby Web site

to see what’s new. Chat with
other Ruby user s on the newsgrou p or mailin g lists (see Appendix
C).
And I’d certainly appreciate hea ring from you. Comments, suggestions, errors in the
text, and problem s in the exam ples are all welcome. E-mail us at

If you tell us about errors in the book, I’ll add them to the errata list at
/>You’ll find links to the source code for almost all the book’s example code at
/>Acknowledgments
For the second edition of the PickAxe, I asked on the Ruby mailing list if anyone would
consider helping review the text. I was overwhelmed with the response: almost one
hundred p eople volunteered. To keep it manageable, I had to restrict the list on a first-
come basis. Even so, my wonderful reviewers produced more than 1.5Mb of review
text. These folks picked on everything, from misplaced commas to missing methods. I
couldn’t have gotten better help. So a big “th ank you” to Richard Amacker, David A.
Black, Tony Bowden, James Britt, Warren Brown, Mike Clark, Rya n Davis (thanks for
the Jap anese PDF!), Guy Decoux, Friedrich Dominicus, Thomas Enebo, Chad Fowler,
Hal Fulton, Ben Giddings, Johan Holmbe rg, Andrew Johnson, Rich Kilmer, Robert
Klemme, Yukihiro Matsumoto, Marcel Molina Jr., Roeland Moors, Michael Neumann,
Prepared exclusively for Yeganefar
PREFACE xxiii
Paul Rogers, Sean Russell, Hugh Sasse, Gavin Sincla ir, Tanaka Akira, Juliet Thomas,
Glenn Vanderburg, Koen Vervloesem, and Austin Ziegler.
Chad Fowler wrote the chapter on RubyGems. In fact, he wrote it twice. The fir st tim e,
he was on vacation in Europe. On his way home, his Powerbook was stolen, and he lost
all his work. So, when he got back, he cheerfu lly sat down and did it all again. I can’t
thank him enough.
Kim Wimpsett had the unenviable job of copyediting the book. She did a tr emendou s
job (and in record time), which was made even m ore amazing by both the volume of
jargon in the b ook and by m y inability to string together more than two words without
breaking one or more rules of grammar. Ed Gidden s did a gre a t job creating th e cover,
which nicely blends the old with the new. Thanks to you both!
Finally, I’m still deeply indebted to Yukihiro “Matz” Matsumoto, the creator of Ruby.
Throu ghout this period of growth and change, he has remained helpful, cheer y, and
dedicated to polishing this gem of a language. The friendly and open spirit of the Ru by

community is a dire ct reflection of the person at its center.
Thank you all. Domo arigato gozaimasu.
Dave Thomas
THE PRAGMATIC PROGRAMMERS

Prepared exclusively for Yeganefar
PREFACE xxiv
Notation Conventions
Throu ghout this book, we use the following typographic notations.
Literal code examples are sh own using a typewriter-like font.
class SampleCode
def run
#
end
end
Within the text,
Fred#do_something is a re ference to an instance method (in this case
do_something) of class Fred, Fred.new
2
is a class method, and Fred::EOF is a class
constant. The decision to use a hash character to indicate instance methods was a tough
one: it isn’t valid Ruby syntax, but we thought that it was important to differentiate
between the instance and class methods of a particular class. When you see us write
File.read, you know we’re talking about the class method read. When instead we
write
File#read, we’re referring to the instanc e method read.
The book contains many snippets of Ruby code. Where possible, we’ve tried to show
what happens when they run. In simple cases, we show the value of expressions on the
same line as the expression. For example:
a = 1

b = 2
a + b → 3
Here, you can see that the result of evaluating
a + b is the value 3, shown to the right
of the arrow. Note that if you simply run this program, you wouldn’t see the value 3
output—you’d need to use a method such as
puts to w rite it out.
At times, we’re also interested in the values of assignment statements, in which case
we’ll show them.
a = 1 → 1
b = 2 → 2
a + b → 3
If the program produces more complex ou tput, we show it below the program code.
3.times { puts "Hello!" }
produces:
Hello!
Hello!
Hello!
2. In some other Ruby documentation, you may see class methods written as Fred::new. This is perfectly
valid Ruby syntax; we just happen to think that
Fred.new is less distracting to read.
Prepared exclusively for Yeganefar