<ppdoc>
<copyright>
    Copyright (c) 2001 by Addison Wesley Longman.  This
    material may be distributed only subject to the terms and
    conditions set forth in the Open Publication License, v1.0 or
    later (the latest version is presently available at
    http://www.opencontent.org/openpub/).
</copyright>
<chapter name="Preface">
This book is a tutorial and reference for the Ruby programming
language. Use Ruby, and you'll write better code, be more productive,
and enjoy programming more.
<p/>
These are bold claims, but we think that after reading this book
you'll agree with them. And we have the experience to back up this
belief.
<p/>
As Pragmatic Programmers we've tried many, many languages in our
search for tools to make our lives easier, for tools to help us do our
jobs better.  Until now, though, we'd always been frustrated by the
languages we were using.
<p/>
Our job is to solve problems, not spoonfeed compilers, so we like
dynamic languages that adapt to us, without arbitrary, rigid rules.  We
need clarity so we can communicate using our code.
We value conciseness and the ability to express a requirement in code
accurately and efficiently.  The less code we write, the less that can
go wrong. (And our wrists and fingers are thankful, too.)
<p/>
We want to be as productive as possible, so we want our code to run
the first time; time spent in the debugger is time stolen from the
development clock. It also helps if we can try out code as we edit it;
if you have to wait for a 2-hour make cycle, you may as well be
using punch cards and submitting your work for batch compilation.
<p/>
We want a language that works at a high level of abstraction. The
higher level the language, the less time we spend translating our
requirements into code.
<p/>
When we discovered Ruby, we realized that we'd found what we'd been
looking for.  More than any other language with which
we have worked, Ruby <em>stays out of your way</em>.  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: by giving you the chance to spend your time
creating solutions for your users, not for the compiler.
<section>Ruby Sparkles</section>
<p/>
Take a true object-oriented language, such as Smalltalk. Drop the
unfamiliar syntax and move to more conventional, file-based source
code.  Now add in a good measure of the flexibility and convenience of
languages such as Python and Perl.
<p/>
You end up with Ruby.
<p/>
OO aficionados will find much to like in Ruby: things such as
pure object orientation
(everything's an object), metaclasses, closures, iterators,
and ubiquitous heterogeneous collections. Smalltalk users will feel
right at home (and C++ and Java users will feel jealous).
<p/>
At the same time, Perl and Python wizards will find many of their
favorite features: full regular expression support, tight
integration with the underlying operating system, convenient
shortcuts, and dynamic evaluation.
<p/>
Ruby is easy to learn. Everyday tasks are simple to code, and
once you've done them, they are easy to maintain and grow.  Apparently
difficult things often turn out not to have been difficult after all.
Ruby follows the <em>Principle of Least Surprise</em>---things work the
way you would expect them to, with very few special cases or
exceptions.  And that really <em>does</em> make a difference when you're
programming.
<p/>
We call Ruby a <em>transparent</em> language.
By that we mean that Ruby
doesn't obscure the solutions you write behind lots of syntax and the
need to churn out reams of support code just to get simple things done.
With Ruby you write programs close to the problem domain. Rather than
constantly mapping your ideas and designs down to the pedestrian level
of most languages, with Ruby you'll find you can express them
directly and express them elegantly. This means you code faster. It
also means your programs stay readable and maintainable.
<p/>
Using Ruby, we are constantly amazed at how much code we can write in
one sitting, code that works the first time. There are very few
syntax errors, no type violations, and far fewer bugs than usual. This
makes sense: there's less to get wrong. No bothersome semicolons to
type mechanically at the end of each line.  No troublesome type
declarations to keep in sync (especially in separate files).  No
unnecessary words just to keep the compiler happy. No error-prone
framework code. 
<p/>
So why learn Ruby?  Because we think it will help you program
<em>better</em>.  It will help you to focus on the problem at hand, with
fewer distractions.  It will make your life easier.
<section>What Kind of Language Is Ruby?</section>
<p/>
In the old days, the distinction between languages was simple: they
were either compiled, like C or Fortran, or interpreted, like BASIC.
Compiled languages gave you speed and low-level access; interpreted
languages were higher-level but slower.
<p/>
Times change, and things aren't that simple anymore.  Some language
designers have taken to calling their creations ``scripting
languages.''  By this, we guess they mean that their languages are
interpreted and can be used to replace batch files and shell
scripts, orchestrating the behavior of other programs and the
underlying operating system. Perl, TCL, and Python have all been
called scripting languages.
<p/>
What exactly <em>is</em> a scripting language? Frankly we don't know if
it's a distinction worth making.  In Ruby, you can access all the
underlying operating system features.  You can do the same stuff in
Ruby that you can in Perl or Python, and you can do it more cleanly.
But Ruby is fundamentally different. It is a true programming language,
too, with strong theoretical roots and an elegant, lightweight syntax.
You <em>could</em> hack together a mess of ``scripts'' with Ruby, but
you probably won't.  Instead, you'll be more inclined to
<em>engineer</em> a solution, to produce a program that is easy to
understand, simple to maintain, and a piece of cake to extend and
reuse in the future.
<p/>
Although we have used Ruby for scripting jobs, most of the time we use
it as a general-purpose programming language. We've used it to write
GUI applications and middle-tier server processes, and we're using it to
format large parts of this book.  Others have used it for managing
server machines and databases. Ruby is serving Web
pages, interfacing to databases and generating dynamic content. People
are writing artificial intelligence and machine learning programs in
Ruby, and at least one person is using it to investigate natural evolution.
Ruby's finding a home as a vehicle for
exploratory mathematics. And people all over the world are using it as
a way of gluing together all their different applications.  It truly
is a great language for producing solutions in a wide variety of
problem domains. 
<section>Is Ruby for Me?</section>
<p/>
Ruby is not the universal panacea for programmers' problems. There
will always be times when you'll need a particular language: the
environment may dictate it, you may have special libraries you need,
performance concerns, or simply an issue with training. We haven't
given up languages such as Java and C++ entirely (although there are
times when we wish we could).
<p/>
However, Ruby is probably more applicable than you might think. It is
easy to extend, both from within the language and by linking in
third-party libraries. It is portable across a number of
platforms. It's relatively lightweight and consumes only modest
system resources. And it's easy to learn; we've known people who've
put Ruby code into production systems within a day of picking up
drafts of this book. We've used Ruby to implement parts of an X11 window
manager, a task that's normally considered severe C coding. Ruby
excelled, and helped us write code in hours that would otherwise have
taken days.
<p/>
Once you get comfortable with Ruby, we think you'll keep coming back
to it as your language of choice.
<section>Why Did We Write This Book?</section>
<p/>
So we'd just finished writing <em>The Pragmatic Programmer,</em> our
families had just started talking to us again, and suddenly we felt
the need to write another book. Why? We guess it comes down to a kind
of missionary zeal.
<p/>
Ruby was created by Yukihiro Matsumoto (Matz) in Japan.
Since 1995,
its popularity in Japan has grown at an astounding rate; there are
rumors that Ruby is more popular than Python in Japan. But to date,
much of the detailed Ruby documentation is in Japanese. It probably
isn't a programming language you'd just stumble across.
<p/>
We wanted to spread the word, to have more people outside Japan using
Ruby and enjoying the benefits, so we decided to
document Ruby in English. And what started out as a small project
just sort of grew....
<section>Ruby Versions</section>
<p/>
This book documents Version 1.6 of Ruby, which was released in September
2000.
<p/>
Ruby version numbering follows the same scheme used for many other open source
projects. Releases with even subversion numbers (1.0, 1.2, 1.4, and
so on) are stable, public releases. These are the releases that are
prepackaged and made available on the various Ruby Web sites.
<p/>
Development versions of the software have odd subversion numbers,
such as 1.1 and 1.3. These you'll have to download and build for
yourself, as described in the box on page xxvii.
<section>Installing Ruby</section>
<p/>
You can get Ruby from <url>ftp://ftp.netlab.co.jp/pub/lang/ruby</url>, or
from the mirror sites listed on page 532 in Appendix
C.  There you will find the latest
stable release, as well as various development releases.
<p/>
You'll always find source code releases of Ruby; you may also find
prebuilt binaries for Windows or other operating systems (like
the binary distribution of Ruby for Windows at
<url>http://www.pragmaticprogrammer.com/ruby/downloads/ruby-install.html</url>).
<sidebar name="The Very Latest Ruby">
<p/>
  For those who just have to be on the very latest, hot-off-the-press and
  <em>untested</em> cutting edge (as we were while writing this book),
  you can get development versions straight from the developers'
  working repository.
<p/>
  The Ruby developers use CVS (Concurrent Version System, freely
  available from <url>http://www.cvshome.com</url>) as their revision control
  system.  You can check files out as an anonymous user from their
  archive by executing the following CVS commands:
<p/>
<tt>% cvs -d :pserver:anonymous@cvs.netlab.co.jp:/home/cvs</tt><br/><tt><nbsp/><nbsp/><nbsp/>login</tt><br/><tt>(Logging in to anonymous@cvs.netlab.co.jp)</tt><br/><tt>CVS password: guest</tt><br/><tt>% cvs -d :pserver:anonymous@cvs.netlab.co.jp:/home/cvs</tt><br/><tt><nbsp/><nbsp/><nbsp/>checkout ruby</tt>
<p/>
The complete source code tree, just as the developers last left it,
will now be copied to a ``ruby'' subdirectory on your machine,
updating your local source tree from a repository on the other side of
the world. Isn't it a great time to be alive?
<p/>
</sidebar>
<subsection>Building Ruby</subsection>
<p/>
In the Ruby distribution you'll find a file named <tt>README</tt>, which
explains the installation procedure in detail.  To summarize, you
build Ruby on POSIX-based systems using the same four commands you
use for most other open source applications:
<tt>./configure</tt>, <tt>make</tt>, <tt>make test</tt>, and <tt>make
  install</tt>.  You can build Ruby under other environments (including
Windows) by using a POSIX emulation environment such as
<tt>cygwin</tt><footnote>See <url>http://sourceware.cygnus.com/cygwin</url> for
  details.</footnote> or by using native compilers---see ``<tt>ntsetup.bat</tt>'' in
the distribution's <tt>win32</tt> subdirectory as a starting point.
<section>Running Ruby</section>
<p/>
Now that Ruby is installed, you'd probably like to run some programs.
Unlike compiled environments, there are two ways to run
Ruby---interactively and as a program.
<subsection>Interactive Ruby</subsection>
<p/>
The easiest way to run Ruby interactively is simply to type ``ruby''
at the shell prompt.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  % ruby
  puts "Hello, world!"
  ^D
  Hello, world!
]]></fullcode>
%<nbsp/>ruby
puts<nbsp/>"Hello,<nbsp/>world!"
^D
Hello,<nbsp/>world!
</alltt>
</codefragment>
<p/>
Here we typed in the single <tt>puts</tt> expression and
an end of file character (which is control-D on our system).
This process works, but it's sort of painful if you make
a typo, and you can't really see what's going on as you type.
<p/>
In the <tt>sample</tt> directory in the Ruby distribution you'll find
a script named ``<tt>eval.rb</tt>''.  It goes one step better by showing us
the value of each expression as it is entered:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  % cd sample
  % ruby eval.rb
  ruby> a = "Hello, world!"
  "Hello, world!"
  ruby> puts a
  Hello, world!
  nil
  ruby> ^D
  %
]]></fullcode>
%<nbsp/>cd<nbsp/>sample
%<nbsp/>ruby<nbsp/>eval.rb
ruby&gt;<nbsp/>a<nbsp/>=<nbsp/>"Hello,<nbsp/>world!"
"Hello,<nbsp/>world!"
ruby&gt;<nbsp/>puts<nbsp/>a
Hello,<nbsp/>world!
nil
ruby&gt;<nbsp/>^D
%
</alltt>
</codefragment>
<p/>
Here we can see the output from <tt>puts</tt>, and then the return value
from <tt>puts</tt> (which is <tt>nil</tt>).
<p/>
That's all fine and well, except that multiline expressions do not
work, and you can't edit the line you're on, or go back and use
previous lines (as you might with command history in a shell).
<p/>
For the next step up from <tt>eval.rb</tt>, we have <tt>irb</tt>---Interactive
Ruby.  <tt>irb</tt> is a Ruby Shell, complete with command-line history,
line editing capabilities, and job control.  It is quite configurable
and has many options, so much so that it has its own appendix beginning
on page 523. We recommend that you get familiar with <tt>irb</tt>
so you can try some of our examples interactively.
<subsection>Ruby Programs</subsection>
<p/>
Finally, you can run a Ruby program from a file as you would any other 
shell script, Perl program, or Python program.  You can simply run Ruby giving 
the script name as an argument:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[   % ruby myprog.rb
]]></fullcode>
%<nbsp/>ruby<nbsp/>myprog.rb
</alltt>
</codefragment>
<p/>
Or you can use the Unix ``shebang'' notation as the first line of the
program file.<footnote>If your system supports it, you can avoid hard-coding
  the path to Ruby in the <em>shebang</em> line by using
  <tt>#!/usr/bin/env ruby</tt>, which will search your path for <tt>ruby</tt>
  and then execute it.</footnote>
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  #!/usr/local/bin/ruby -w

  puts "Hello, World!"
]]></fullcode>
#!/usr/local/bin/ruby<nbsp/>-w
<p/>
puts<nbsp/>"Hello,<nbsp/>World!"
</alltt>
</codefragment>
<p/>
If you make this source file executable (using, for instance,
<tt>chmod<nbsp/>+x<nbsp/>myprog.rb</tt>), Unix lets you run the file as a
program:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  % ./myprog.rb
  Hello, World!
]]></fullcode>
%<nbsp/>./myprog.rb
Hello,<nbsp/>World!
</alltt>
</codefragment>
<p/>
You can do something similar under Microsoft Windows using file
associations.
<section>Resources</section>
<p/>
Visit the Ruby Web sites, <url>http://www.rubycentral.com</url> and
<url>http://www.ruby-lang.org</url>, to see what's new, and chat with other Ruby
users on the newsgroup or mailing lists (see Appendix
C).
<p/>
And we'd certainly appreciate hearing from you. Comments, suggestions,
errors in the text, and problems in the examples are all welcome.
E-mail us at:
<p/>
<url>mailto:rubybook@pragmaticprogrammer.com</url>
<p/>
If you tell us about errors in the book, we'll add them to the errata
list at:
<p/>
<url>http://www.pragmaticprogrammer.com/ruby/errata/errata.html</url>
<p/>
Finally, <url>http://www.pragmaticprogrammer.com/ruby</url> also contains the
source code for almost all the book's examples, organized by page.
<section>Acknowledgments</section>
<p/>
A book is a massive undertaking, one that we would never be able to
complete without help from our all our friends, old and new. We're
proud to count among our old friends
the team at Addison-Wesley:
Mike<nbsp/>Hendrickson, John<nbsp/>Fuller, 
the ever-helpful Julie<nbsp/>Steele, and the wonderful
Julie<nbsp/>DiNicola. Thank you all.
<p/>
  Our reviewers were fantastic. We put them up against some incredibly
tight deadlines and they came through for us. Reviewing a book full of
technical detail isn't easy, so we're especially grateful to
George<nbsp/>Coe,
Bob<nbsp/>Davison,
Jeff<nbsp/>Deifik,
Hal<nbsp/>Fulton,
Tadayoshi<nbsp/>Funaba,
Clemens<nbsp/>Hintze,
Kazuhiro<nbsp/>Hiwada,
Kikutani<nbsp/>Makoto,
Mike<nbsp/>Linksvayer,
Aleksi<nbsp/>Niemel&#228;,
Lew<nbsp/>Perin,
Jared<nbsp/>Richardson,
Armin<nbsp/>Roehrl,
Conrad<nbsp/>Schneiker,
Patrick<nbsp/>Schoenbach, and
Eric<nbsp/>Vought.
Thanks also go to the two Julies at Addison-Wesley for coordinating
this truly international effort.
<p/>
Several people helped us with specific areas of this book.
Tadayoshi Funaba exchanged countless e-mails with us until
we finally understood the <classname>Date</classname> module. Guy Decoux and
Clemens Hintze patiently answered our questions about
writing Ruby extensions, and Masaki Suketa helped us
understand the <classname>WinOLE</classname> module.
<p/>
Although much of the original Ruby documentation is in Japanese, there 
is a growing body of English translations, mostly undertaken by
Japanese developers whose skills with English never cease to amaze
us. Although there are too many individual contributions to this
effort to name each author, we would like to single out
Goto Kentaro, who has produced a large volume of
high-quality documentation and placed it online.
<p/>
Finally, we have to thank Yukihiro ``Matz''  Matsumoto, the creator of 
Ruby. We've lost count of the number of questions we've asked of him,
and the number of patient and detailed answers he's sent back. As well 
as creating a truly wonderful language, Matz has fostered a
wonderfully supportive and open culture in which that language can
prosper.
<p/>
Thank you all. Domo arigato gozaimasu.
<p/>
  <em>Dave Thomas</em> and <em>Andy Hunt</em><br/>T<smallfont>HE</smallfont> P<smallfont>RAGMATIC</smallfont> P<smallfont>ROGRAMMERS</smallfont><br/><url>http://www.pragmaticprogrammer.com</url><p/>
<p/>
<section>Notation Conventions</section>
<p/>
Throughout this book, we use the following typographic notations.
<p/>
Literal code examples are shown using a typewriter-like font:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  class SampleCode
    def run
      #...
    end
  end
]]></fullcode>
class<nbsp/>SampleCode
<nbsp/><nbsp/>def<nbsp/>run
<nbsp/><nbsp/><nbsp/><nbsp/>#...
<nbsp/><nbsp/>end
end
</alltt>
</codefragment>
<p/>
Within the text, <cim><front>Fred</front><back>doIt</back></cim> is a reference to an instance method
(<meth>doIt</meth>) of class <classname>Fred</classname>, while <ccm><front>Fred</front><back>new</back></ccm><footnote>In
  some other Ruby documentation, you may see class methods written as
  <tt>Fred::new</tt>. This is perfectly valid Ruby syntax; we just happen
  to feel that <tt>Fred.new</tt> is less distracting to read.</footnote> is a class
method, and <classconst><front>Fred</front><back>EOF</back></classconst> is a class constant.
<p/>
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:
<p/>
<codefragment>
<fullcode><![CDATA[  a = 1
  b = 2
  a + b
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt>b<nbsp/>=<nbsp/>2</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>+<nbsp/>b</tt></td>
  <td>&#187;</td>
  <td><tt>3</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
At times, we're also interested in the values of assignment statements,
in which case we'll show them.
<p/>
<codefragment>
<fullcode><![CDATA[  a = 1
  b = 2
  a + b
]]></fullcode><rubycode>
<tr>
  <td><tt>a<nbsp/>=<nbsp/>1</tt></td>
  <td>&#187;</td>
  <td><tt>1</tt></td>
</tr>
<tr>
  <td><tt>b<nbsp/>=<nbsp/>2</tt></td>
  <td>&#187;</td>
  <td><tt>2</tt></td>
</tr>
<tr>
  <td><tt>a<nbsp/>+<nbsp/>b</tt></td>
  <td>&#187;</td>
  <td><tt>3</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
If the program produces more complex output, we show it below the
program code:
<p/>
<codefragment>
<alltt><fullcode><![CDATA[  3.times { puts "Hello!" }
]]></fullcode>
3.times<nbsp/>{<nbsp/>puts<nbsp/>"Hello!"<nbsp/>}
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Hello!
Hello!
Hello!
</alltt>
</codefragment>
<p/>
In some of the library documentation, we wanted to show where spaces
appear in the output. You'll see these spaces as ``<visible_space/>'' characters.
<p/>
Command-line invocations are shown with literal text in a Roman font,
and parameters you supply in an <em>italic</em> font.
Optional elements are shown in large square brackets.
<p/>
<syntax>
ruby <optz><nt>flags</nt></optz> <opt><nt>progname</nt></opt> <optn><nt>arguments</nt></optn>
</syntax>
</chapter>
</ppdoc>