Ruby Cookbook（英文影印版）（2007年第17届Jolt大奖提名图书）(低价优惠)

.　　 --why the lucky stiff

.1.19 validating an email address
1.20 classifying text with a bayesian analyzer
2 numbers
2.1 parsing a number from a string
2.2 comparing floating-point numbers
2.3 representing numbers to arbitrary precision
2.4 representing rational numbers
2.5 generating random numbers
2.6 converting between numeric bases
2.7 taking logarithms
2.8 finding mean, median, and mode
2.9 converting between degrees and radians
2.10 multiplying matrices
2.11 solving a system of linear equations
2.12 using complex numbers
2.13 simulating a subclass of fixnum
2.14 doing math with roman numbers
2.15 generating a sequence of numbers
2.16 generating prime numbers
2.17 checking a credit card checksum
3 date and time
3.1 finding today's date
3.2 parsing dates, precisely or fuzzily
3.3 printing a date
3.4 iterating over dates
3.5 doing date arithmetic
3.6 counting the days since an arbitrary date
3.7 converting between time zones
3.8 checking whether daylight saving time is in effect
3.9 converting between time and datetime objects
3.10 finding the day of the week
3.11 handling commercial dates
3.12 running a code block periodically
3.13 waiting a certain amount of time
3.14 adding a timeout to a long-running operation
4 arrays
4.1 iterating over an array
4.2 rearranging values without using temporary variables
4.3 stripping duplicate elements from an array
4.4 reversing an array
4.5 sorting an array
4.6 ignoring case when sorting strings
4.7 making sure a sorted array stays sorted
4.8 summing the items of an array
4.9 sorting an array by frequency of appearance
4.10 shuffling an array
4.11 getting the n smallest items of an array
4.12 building up a hash using injection
4.13 extracting portions of arrays
4.14 computing set operations on arrays
4.15 partitioning or classifying a set
5 hashes
5.1 using symbols as hash keys
5.2 creating a hash with a default value
5.3 adding elements to a hash
5.4 removing elements from a hash
5.5 using an array or other modifiable object as a hash key
5.6 keeping multiple values for the same hash key
5.7 iterating over a hash
5.8 iterating over a hash in insertion order
5.9 printing a hash
5.10 inverting a hash
5.11 choosing randomly from a weighted list
5.12 building a histogram
5.13 remapping the keys and values of a hash
5.14 extracting portions of hashes
5.15 searching a hash with regular expressions
6 files and directories
6.1 checking to see if a file exists
6.2 checking your access to a file
6.3 changing the permissions on a file
6.4 seeing when a file was last used problem
6.5 listing a directory
6.6 reading the contents of a file
6.7 writing to a file
6.8 writing to a temporary file
6.9 picking a random line from a file
6.10 comparing two files
6.11 performing random access on "read-once" input streams
6.12 walking a directory tree
6.13 locking a file
6.14 backing up to versioned filenames
6.15 pretending a string is a file
6.16 redirecting standard input or output
6.17 processing a binary file
6.18 deleting a file
6.19 truncating a file
6.20 finding the files you want
6.21 finding and changing the current working directory
7 code blocks and iteration
7.1 creating and invoking a block
7.2 writing a method that accepts a block
7.3 binding a block argument to a variable
7.4 blocks as closures: using outside variables within a code block
7.5 writing an iterator over a data structure
7.6 changing the way an object iterates
7.7 writing block methods that classify or collect
7.8 stopping an iteration
7.9 looping through multiple iterables in parallel
7.10 hiding setup and cleanup in a block method
7.11 coupling systems loosely with callbacks
8 objects and classes8
8.1 managing instance data
8.2 managing class data
8.3 checking class or module membership
8.4 writing an inherited class
8.5 overloading methods
8.6 validating and modifying attribute values
8.7 defining a virtual attribute
8.8 delegating method calls to another object
8.9 converting and coercing objects to different types
8.10 getting a human-readable printout of any object
8.11 accepting or passing a variable number of arguments
8.12 simulating keyword arguments
8.13 calling a superclass's method
8.14 creating an abstract method
8.15 freezing an object to prevent changes
8.16 making a copy of an object
8.17 declaring constants
8.18 implementing class and singleton methods
8.19 controlling access by making methods private
9 modules and namespaces
9.1 simulating multiple inheritance with mixins
9.2 extending specific objects with modules
9.3 mixing in class methods
9.4 implementing enumerable: write one method, get 22 free
9.5 avoiding naming collisions with namespaces
9.6 automatically loading libraries as needed
9.7 including namespaces
9.8 initializing instance variables defined by a module
9.9 automatically initializing mixed-in modules
10 reflection and metaprogramming
10.1 finding an object's class and superclass
10.2 listing an object's methods
10.3 listing methods unique to an object
10.4 getting a reference to a method
10.5 fixing bugs in someone else's class
10.6 listening for changes to a class
10.7 checking whether an object has necessary attributes
10.8 responding to calls to undefined methods
10.9 automatically initializing instance variables
10.10 avoiding boilerplate code with metaprogramming
10.11 metaprogramming with string evaluations
10.12 evaluating code in an earlier context
10.13 undefining a method
10.14 aliasing methods
10.15 doing aspect-oriented programming
10.16 enforcing software contracts
11 xml and html
11.1 checking xml well-formedness
11.2 extracting data from a document's tree structure
11.3 extracting data while parsing a document
11.4 navigating a document with xpath
11.5 parsing invalid markup ..
11.6 converting an xml document into a hash
11.7 validating an xml document
11.8 substituting xml entities
11.9 creating and modifying xml documents
11.10 compressing whitespace in an xml document
11.11 guessing a document's encoding
11.12 converting from one encoding to another
11.13 extracting all the urls from an html document
11.14 transforming plain text to html
11.15 converting html documents from the web into text
11.16 a simple feed aggregator
12 graphics and other file formats
12.1 thumbnailing images
12.2 adding text to an image
12.3 converting one image format to another
12.4 graphing data
12.5 adding graphical context with sparklines
12.6 strongly encrypting data
12.7 parsing comma-separated data
12.8 parsing not-quite-comma-separated data
12.9 generating and parsing excel spreadsheets
12.10 compressing and archiving files with gzip and tar
12.11 reading and writing zip files
12.12 reading and writing configuration files
12.13 generating pdf files
12.14 representing data as midi music
13 databases and persistence
13.1 serializing data with yaml
13.2 serializing data with marshal
13.3 persisting objects with madeleine
13.4 indexing unstructured text with simplesearch
13.5 indexing structured text with ferret
13.6 using berkeley db databases
13.7 controlling mysql on unix
13.8 finding the number of rows returned by a query
13.9 talking directly to a mysql database
13.10 talking directly to a postgresql database
13.11 using object relational mapping with activerecord
13.12 using object relational mapping with og
13.13 building queries programmatically
13.14 validating data with activerecord
13.15 preventing sql injection attacks
13.16 using transactions in activerecord
13.17 adding hooks to table events
13.18 adding taggability with a database mixin
14 internet services
14.1 grabbing the contents of a web page
14.2 making an https web request
14.3 customizing http request headers
14.4 performing dns queries
14.5 sending mail
14.6 reading mail with imap
14.7 reading mail with pop3
14.8 being an ftp client
14.9 being a telnet client
14.10 being an ssh client
14.11 copying a file to another machine
14.12 being a bittorrent client
14.13 pinging a machine
14.14 writing an internet server
14.15 parsing urls
14.16 writing a cgi script
14.17 setting cookies and other http response headers
14.18 handling file uploads via cgi
14.19 running servlets with webrick
14.20 a real-world http client
15 web development: ruby on rails
15.1 writing a simple rails application to show system status
15.2 passing data from the controller to the view
15.3 creating a layout for your header and footer
15.4 redirecting to a different location
15.5 displaying templates with render
15.6 integrating a database with your rails application
15.7 understanding pluralization rules
15.8 creating a login system
15.9 storing hashed user passwords in the database
15.10 escaping html and javascript for display
15.11 setting and retrieving session information
15.12 setting and retrieving cookies
15.13 extracting code into helper functions
15.14 refactoring the view into partial snippets of views
15.15 adding dhtml effects with script.aculo.us
15.16 generating forms for manipulating model objects
15.17 creating an ajax form
15.18 exposing web services on your web site
15.19 sending mail with rails
15.20 automatically sending error messages to your email
15.21 documenting your web site
15.22 unit testing your web site
15.23 using breakpoint in your web application
16 web services and distributed programming
16.1 searching for books on amazon
16.2 finding photos on flickr
16.3 writing an xml-rpc client
16.4 writing a soap client
16.5 writing a soap server
16.6 searching the web with google's soap service
16.7 using a wsdl file to make soap calls easier
16.8 charging a credit card
16.9 finding the cost to ship packages via ups or fedex
16.10 sharing a hash between any number of computers
16.11 implementing a distributed queue
16.12 creating a shared "whiteboard"
16.13 securing drb services with access control lists
16.14 automatically discovering drb services with rinda
16.15 proxying objects that can't be distributed
16.16 storing data on distributed ram with memcached
16.17 caching expensive results with memcached
16.18 a remote-controlled jukebox
17 testing, debugging, optimizing, and documenting
17.1 running code only in debug mode
17.2 raising an exception
17.3 handling an exception
17.4 rerunning after an exception
17.5 adding logging to your application
17.6 creating and understanding tracebacks
17.7 writing unit tests
17.8 running unit tests
17.9 testing code that uses external resources
17.10 using breakpoint to inspect and change the state of your application
17.11 documenting your application
17.12 profiling your application
17.13 benchmarking competing solutions
17.14 running multiple analysis tools at once
17.15 who's calling that method? a call graph analyzer
18 packaging and distributing software
18.1 finding libraries by querying gem respositories
18.2 installing and using a gem
18.3 requiring a specific version of a gem
18.4 uninstalling a gem
18.5 reading documentation for installed gems
18.6 packaging your code as a gem
18.7 distributing your gems
18.8 installing and creating standalone packages with setup.rb
19 automating tasks with rake
19.1 automatically running unit tests
19.2 automatically generating documentation
19.3 cleaning up generated files
19.4 automatically building a gem
19.5 gathering statistics about your code
19.6 publishing your documentation
19.7 running multiple tasks in parallel
19.8 a generic project rakefile
20 multitasking and multithreading
20.1 running a daemon process on unix
20.2 creating a windows service
20.3 doing two things at once with threads
20.4 synchronizing access to an object
20.5 terminating a thread
20.6 running a code block on many objects simultaneously
20.7 limiting multithreading with a thread pool
20.8 driving an external process with popen
20.9 capturing the output and error streams from a unix shell command
20.10 controlling a process on another machine
20.11 avoiding deadlock
21 user interface
21.1
21.2 getting input one line at a time
21.3 getting input one character at a time
21.4 parsing command-line arguments
21.5 testing whether a program is running interactively
21.6 setting up and tearing down a curses program
21.7 clearing the screen
21.8 determining terminal size
21.9 changing text color
21.10 reading a password
21.11 allowing input editing with readline
21.12 making your keyboard lights blink
21.13 creating a gui application with tk
21.14 creating a gui application with wxruby
21.15 creating a gui application with ruby/gtk
21.16 creating a mac os x application with rubycocoa
21.17 using applescript to get user input
22 extending ruby with other languages
22.1 writing a c extension for ruby
22.2 using a c library from ruby
22.3 calling a c library through swig
22.4 writing inline c in your ruby code
22.5 using java libraries with jruby
23 system administration
23.1 scripting an external program
23.2 managing windows services
23.3 running code as another user
23.4 running periodic tasks without cron or at
23.5 deleting files that match a regular expression
23.6 renaming files in bulk
23.7 finding duplicate files
23.8 automating backups
23.9 normalizing ownership and permissions in user directories
23.10 killing all processes for a given user
index ...

.　　The Structure of This Book
　　Each of this book's 23 chapters focuses on a kind of programming or a particular data type. This overview of the chapters should give you a picture of how we divided up the recipes. Each chapter also has its own, somewhat lengthier introduction, which gives a more detailed view of its recipes. At the very least, we recommend you skim the chapter introductions and the table of contents.
　　We start with six chapters covering Ruby's built-in data structures.
　　Chapter 1, Strings, contains recipes for building, processing, and manipulating strings of text. We devote a few recipes specifically to regular expressions (Recipes 1.17, 1.18 through 1.19), but our focus is on Ruby-specific issues, and regular expressions are a very general tool. If you haven't encountered them yet, or just find them intimidating, we recommend you go through an online tutorial or Mastering Regular Expressions by Jeffrey Friedl (O'Reilly).
　　Chapter 2, Numbers, covers the representation of different types of numbers: real numbers, complex numbers, arbitrary-precision decimals, and so on. It also includes Ruby implementations of common mathematical and statistical algorithms, and explains some Ruby quirks you'll run into if you create your own numeric types (Recipes 2.13 and 2.14).
　　Chapter 3, Date and Time, covers Ruby's two interfaces for dealing with time: the one based on the C time library, which may be familiar to you from other programming languages, and the one implemented in pure Ruby, which is more idiomatic.
　　Chapter 4, Arrays, introduces the array, Ruby's simplest compound data type. Many of an array's methods are actually methods of the Enumerable mixin; this means you can apply many of these recipes to hashes and other data types. Some features of Enumerable are covered in this chapter (Recipes 4.4 and 4.6), and some are covered in Chapter 7.
　　Chapter 5, Hashes, covers the hash, Ruby's other basic compound data type. Hashes make it easy to associate objects with names and find them later (hashes are sometimes called "lookup tables" or "dictionaries," two telling names). It's easy to use hashes along with arrays to build deep and complex data structures.
　　Chapter 6, Files and Directories, covers techniques for reading, writing, and manipulating files. Ruby's file access interface is based on the standard C file libraries, so it may look familiar to you. This chapter also covers Ruby's standard libraries for searching and manipulating the filesystem; many of these recipes show up again in Chapter 23.
　　The first six chapters deal with specific algorithmic problems. The next four are more abstract: they're about Ruby idiom and philosophy. If you can't get the Ruby language itself to do what you want, or you're having trouble writing Ruby code that looks the way Ruby "should" look, the recipes in these chapters may help.
　　Chapter 7, Code Blocks and Iteration, contains recipes that explore the possibilities of Ruby's code blocks (also known as closures).
　　Chapter 8, Objects and Classes, covers Ruby's take on object-oriented programming. It contains recipes for writing different types of classes and methods, and a few recipes that demonstrate capabilities of all Ruby objects (such as freezing and cloning).
　　Chapter 9, Modules and Namespaces, covers Ruby's modules. These constructs are used to "mix" new behavior into existing classes and to segregate functionality into different namespaces.
　　Chapter 10, Reflection and Metaprogramming, covers techniques for programatically exploring and modifying Ruby class definitions.
　　Chapter 6 covers basic file access, but doesn't touch much on specific file formats. We devote three chapters to popular ways of storing data.
　　Chapter 11, XML and HTML, shows how to handle the most popular data interchange formats. The chapter deals mostly with parsing other people's XML documents and web pages (but see Recipe 11.9).
　　Chapter 12, Graphics and Other File Formats, covers data interchange formats other than XML and HTML, with a special focus on generating and manipulating graphics.
　　Chapter 13, Databases and Persistence, covers the best Ruby interfaces to data storage formats, whether you're serializing Ruby objects to disk, or storing structured data in a database. This chapter demonstrates everything from different ways of serializing data and indexing text, to the Ruby client libraries for popular SQL databases, to full-blown abstraction layers like ActiveRecord that save you from having to write SQL at all.
　　Currently the most popular use of Ruby is in network applications (mostly through Ruby on Rails). We devote three chapters to different types of applications:
　　Chapter 14, Internet Services, kicks off our networking coverage by illustrating a wide variety of clients and servers written with Ruby libraries.
　　Chapter 15, Web Development: Ruby on Rails, covers the web application framework that's been driving so much of Ruby's recent popularity.
　　Chapter 16, Web Services and Distributed Programming, covers two techniques for sharing information between computers during a Ruby program. In order to use a web service, you make an HTTP request of a program on some other computer, usually one you don't control. Ruby's DRb library lets you share Ruby data structures between programs running on a set of computers, all of which you control.
　　We then have three chapters on the auxilliary tasks that surround the main programming work of a project.
　　Chapter 17, Testing, Debugging, Optimizing, and Documenting, focuses mainly on handling exception conditions and creating unit tests for your code. There are also several recipes on the processes of debugging and optimization.
　　Chapter 18, Packaging and Distributing Software, mainly deals with Ruby's Gem packaging system and the RubyForge server that hosts many gem files. Many recipes in other chapters require that you install a particular gem, so if you're not familiar with gems, we recommend you read Recipe 18.2 in particular. The chapter also shows you how to create and distribute gems for your own projects.
　　Chapter 19, Automating Tasks with Rake, covers the most popular Ruby build tool. With Rake, you can script common tasks like running unit tests or packaging your code as a gem. Though it's usually used in Ruby projects, it's a general-purpose build language that you can use wherever you might use Make.
　　We close the book with four chapters on miscellaneous topics.
　　Chapter 20, Multitasking and Multithreading, shows how to use threads to do more than one thing at once, and how to use Unix subprocesses to run external commands.
　　Chapter 21, User Interface, covers user interfaces (apart from the web interface, which was covered in Chapter 15). We discuss the command-line interface, character-based GUIs with Curses and HighLine, GUI toolkits for various platforms, and more obscure kinds of user interface (Recipe 21.11).
　　Chapter 22, Extending Ruby with Other Languages, focuses on hooking up Ruby to other languages, either for performance or to get access to more libraries. Most of the chapter focuses on getting access to C libraries, but there is one recipe about JRuby, the Ruby implementation that runs on the Java Virtual Machine (Recipe 22.5).
　　Chapter 23, System Administration, is full of self-contained programs for doing administrative tasks, usually using techniques from other chapters. The recipes have a heavy focus on Unix administration, but there are some resources for Windows users (including Recipe 23.2), and some cross-platform scripts.
　　How the Code Listings Work
　　Learning from a cookbook means performing the recipes. Some of our recipes define big chunks of Ruby code that you can simply plop into your program and use without really understanding them (Recipe 19.8 is a good example). But most of the recipes demonstrate techniques, and the best way to learn a technique is to practice it.
　　We wrote the recipes, and their code listings, with this in mind. Most of our listings act like unit tests for the concepts described in the recipe: they poke at objects and show you the results.
　　Now, a Ruby installation comes with an interactive interpreter called irb. Within an irb session, you can type in lines of Ruby code and see the output immediately. You don't have to create a Ruby program file and run it through the interpreter.
　　Most of our recipes are presented in a form that you can type or copy/paste directly into an irb session. To study a recipe in depth, we recommend that you start an irb session and run through the code listings as you read it. You'll have a deeper understanding of the concept if you do it yourself than if you just read about it. Once you're done, you can experiment further with the objects you defined while running the code listings.
　　Sometimes we want to draw your attention to the expected result of a Ruby expression. We do this with a Ruby comment containing an ASCII arrow that points to the expected value of the expression. This is the same arrow irb uses to tell you the value of every expression you type.
　　We also use textual comments to explain some pieces of code. Here's a fragment of Ruby code that I've formatted with comments as I would in a recipe:
　　1 + 2 # =] 3
　　# On a long line, the expected value goes on a new line:
　　Math.sqrt(1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10)
　　# =] 7.41619848709566
　　To display the expected output of a Ruby expression, we use a comment that has no ASCII arrow, and that always goes on a new line:
　　puts "This string is self-referential."
　　# This string is self-referential...
　　If you type these two snippets of code into irb, ignoring the comments, you can check back against the text and verify that you got the same results we did:
　　$ irb
　　irb(main):001:0] 1 + 2
　　=] 3
　　irb(main):002:0] Math.sqrt(1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10)
　　=] 7.41619848709566
　　irb(main):003:0] puts "This string is self-referential."
　　This string is self-referential.
　　=] nil
　　If you're reading this book in electronic form, you can copy and paste the code fragments into irb. The Ruby interpreter will ignore the comments, but you can use them to make sure your answers match ours, without having to look back at the text. (But you should know that typing in the code yourself, at least the first time, is better for comprehension.)
　　$ irb
　　irb(main):001:0] 1 + 2 # =] 3
　　=] 3
　　irb(main):002:0]
　　irb(main):003:0* # On a long line, the expected value goes on a new line:
　　irb(main):004:0* Math.sqrt(1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10)
　　=] 7.41619848709566
　　irb(main):005:0] # =] 7.41619848709566
　　irb(main):006:0*
　　irb(main):007:0* puts "This string is self-referential."
　　This string is self-referential.
　　=] nil
　　irb(main):008:0] # This string is self-referential.
　　We don't cut corners. Most of our recipes demonstrate a complete irb session from start to finish, and they include any imports or initialization necessary to illustrate the point we're trying to make. If you run the code exactly as it is in the recipe, you should get the same results we did.[1] This fits in with our philosophy that code samples should be unit tests for the underlying concepts. In fact, we tested our code samples like unit tests, with a Ruby script that parses recipe texts and runs the code listings.
　　[1] When a program's behavior depends on the current time, the random number generator, or the presence of certain files on disk, you might not get the exact same results we did, but it should be similar.
　　The irb session technique doesn't always work. Rails recipes have to run within Rails. Curses recipes take over the screen and don't play well with irb. So sometimes we show you standalone files. We present them in the following format:
　　#!/usr/bin/ruby -w
　　# sample_ruby_file.rb: A sample file
　　1 + 2
　　Math.sqrt(1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10)
　　puts "This string is self-referential."
　　Whenever possible, we'll also show what you'll get when you run this program: maybe a screenshot of a GUI program, or a record of the program's output when run from the Unix command line:
　　$ ruby sample_ruby_file.rb
　　This string is self-referential.
　　Note that the output of sample_ruby_file.rb looks different from the same code entered into irb. Here, there's no trace of the addition and the square root operations, because they produce no output.
　　Installing the Software
　　Ruby comes preinstalled on Mac OS X and most Linux installations. Windows doesn't come with Ruby, but it's easy to get it with the One-Click Installer: see http://rubyforge.org/projects/rubyinstaller/.
　　If you're on a Unix/Linux system and you don't have Ruby installed (or you want to upgrade), your distribution's package system may make a Ruby package available. On Debian GNU/Linux, it's available as the package ruby-[version]: for instance, ruby-1.8 or ruby-1.9. Red Hat Linux calls it ruby; so does the DarwinParts system on Mac OS X.
　　If all else fails, download the Ruby source code and compile it yourself. You can get the Ruby source code through FTP or HTTP by visiting http://www.ruby-lang.org/.
　　Many of the recipes in this book require that you install third-party libraries in the form of Ruby gems. In general, we prefer standalone solutions (using only the Ruby standard library) to solutions that use gems, and gem-based solutions to ones that require other kinds of third-party software.
　　If you're not familiar with gems, consult Chapter 18 as needed. To get started, all you need to know is that you first download the Rubygems library from http://rubyforge.org/projects/rubygems/ (choose the latest release from that page). Unpack the tarball or ZIP file, change into the rubygems-[version] directory, and run this command as the superuser:
　　$ ruby setup.rb
　　The Rubygems library is included in the Windows One-Click Installer, so you don't have to worry about this step on Windows.
　　Once you've got the Rubygems library installed, it's easy to install many other pieces of Ruby code. When a recipe says something like "Ruby on Rails is available as the rails gem," you can issue the following command from the command line (again, as the superuser):
　　$ gem install rails --include-dependencies
　　The RubyGems library will download the rails gem (and any other gems on which it depends) and automatically install them. You should then be able to run the code in the recipe, exactly as it appears.
　　The three most useful gems for new Ruby installations are rails (if you intend to create Rails applications) and the two gems provided by the Ruby Facets project: facets_core and facets_more. The Facets Core library extends the classes of the Ruby standard library with generally useful methods. The Facets More library adds entirely new classes and modules. The Ruby Facets homepage (http://facets.rubyforge.org/) has a complete reference.
　　Some Ruby libraries (especially older ones) are not packaged as gems. Most of the nongem libraries mentioned in this book have entries in the Ruby Application Archive (http://raa.ruby-lang.org/), a directory of Ruby programs and libraries. In most cases you can download a tarball or ZIP file from the RAA, and install it with the technique described in Recipe 18.8.
　　Platform Differences, Version Differences, and Other Headaches
　　Except where noted, the recipes describe cross-platform concepts, and the code itself should run the same way on Windows, Linux, and Mac OS X. Most of the platform differences and platform-specific recipes show up in the final chapters: Chapter 20, Chapter 21, and Chapter 23 (but see the introduction to Chapter 6 for a note about Windows filenames).
　　We wrote and tested the recipes using Ruby version 1.8.4 and Rails version 1.1.2, the latest stable versions as of the time of writing. In a couple of places we mention code changes you should make if you're running Ruby 1.9 (the latest unstable version as of the time of writing) or 2.0.
　　Despite our best efforts, this book may contain unflagged platform-specific code, not to mention plain old bugs. We apologize for these in advance of their discovery. If you have problems with a recipe, check out the eratta for this book (see below).
　　In several recipes in this book, we modify standard Ruby classes like Array to add new methods (see, for instance, Recipe 1.10, which defines a new method called String#capitalize_first_letter). These methods are then available to every instance of that class in your program. This is a fairly common technique in Ruby: both Rails and the Facets Core library mentioned above do it. It's somewhat controversial, though, and it can cause problems (see Recipe 8.4 for an in-depth discussion), so we felt we should mention it here in the Preface, even though it might be too technical for people who are new to Ruby.
　　If you don't want to modify the standard classes, you can put the methods we demonstrate into a subclass, or define them in the Kernel namespace: that is, define capitalize_first_letter_of_string instead of reopening String and defining capitalize_first_letter inside it.
　　Other Resources
　　If you need to learn Ruby, the standard reference is Programming Ruby: The Pragmatic Programmer's Guide by Dave Thomas, Chad Fowler, and Andy Hunt (Pragmatic Programmers). The first edition is available online in HTML format (http://www.rubycentral.com/book/), but it's out of date. The second edition is much better and is available as a printed book or as PDF (http://www.pragmaticprogrammer.com/titles/ruby/). It's a much better idea to buy the second edition and use the first edition as a handy reference than to try to read the first edition.
　　"Why's (Poignant) Guide to Ruby," by "why the lucky stiff," teaches Ruby with stories, like an English primer. Excellent for creative beginners (http://poignantguide.net/ruby/).
　　For Rails, the standard book is Agile Web Development with Rails by Dave Thomas, David Hansson, Leon Breedt, and Mike Clark (Pragmatic Programmers). There are also two books like this one that focus exclusively on Rails: Rails Cookbook by Rob Orsini (O'Reilly) and Rails Recipes by Chad Fowler (Pragmatic Programmers).
　　Some common Ruby pitfalls are explained in the Ruby FAQ (http://www.rubycentral.com/faq/, starting in Section 4) and in "Things That Newcomers to Ruby Should Know" (http://www.glue.umd.edu/~billtj/ruby.html).
　　Many people come to Ruby already knowing one or more programming languages. You might find it frustrating to learn Ruby with a big book that thinks it has to teach you programming and Ruby. For such people, we recommend Ruby creator Yukihiro Matsumoto's "Ruby User's Guide" (http://www.ruby-doc.org/docs/UsersGuide/rg/). It's a short read, and it focuses on what makes Ruby different from other programming languages. Its terminology is a little out of date, and it presents its code samples through the obsolete eval.rb program (use irb instead), but it's the best short introduction we know of.
　　There are a few articles especially for Java programmers who want to learn Ruby: Jim Weirich's "10 Things Every Java Programmer Should Know About Ruby" (http://onestepback.org/articles/10things/), Francis Hwang's blog entry "Coming to Ruby from Java" (http://fhwang.net/blog/40.html), and Chris Williams's collection of links, "From Java to Ruby (With Love)" (http://cwilliams.textdriven.com/pages/java_to_ruby) Despite the names, C++ programmers will also benefit from much of what's in these pieces.
　　The Ruby Bookshelf (http://books.rubyveil.com/books/Bookshelf/Introduction/Bookshelf) has produced a number of free books on Ruby, including many of the ones mentioned above, in an easy-to-read HTML format.
　　Finally, Ruby's built-in modules, classes, and methods come with excellent documentation (much of it originally written for Programming Ruby). You can read this documentation online at http://www.ruby-doc.org/core/ and http://www.ruby-doc.org/stdlib/. You can also look it up on your own Ruby installation by using the ri command. Pass in the name of a class or method, and ri will give you the corresponding documentation. Here are a few examples:
　　$ ri Array # A class
　　$ ri Array.new # A class method
　　$ ri Array#compact # An instance method
　　Conventions Used in This Book
　　The following typographical conventions are used in this book:
　　Plain text
　　Indicates menu titles, menu options, menu buttons, and keyboard accelerators (such as Alt and Ctrl).
　　Italic
　　Indicates new terms, URLs, email addresses, and Unix utilities.
　　Constant width
　　Indicates commands, options, switches, variables, attributes, keys, functions, types, classes, namespaces, methods, modules, properties, parameters, values, objects, events, event handlers, XML tags, HTML tags, macros, programs, libraries, filenames, pathnames, directories, the contents of files, or the output from commands.
　　Constant width bold
　　Shows commands or other text that should be typed literally by the user.
　　Constant width italic
　　Shows text that should be replaced with user-supplied values.
　　Using Code Examples
　　This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you're reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O'Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product's documentation does require permission.
　　We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: "Ruby Cookbook, by Lucas Carlson and Leonard Richardson. Copyright 2006 O'Reilly Media, Inc., 0-596-52369-6."
　　If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at permissions@oreilly.com.
　　Comments and Questions
　　Please address comments and questions concerning this book to the publisher:
　　O'Reilly Media, Inc.
　　1005 Gravenstein Highway North
　　Sebastopol, CA 95472
　　800-998-9938 (in the United States or Canada)
　　707-829-0515 (international or local)
　　707-829-0104 (fax)
　　We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at:
　　http://www.oreilly.com/catalog/rubyckbk
　　To comment or ask technical questions about this book, send email to:
　　bookquestions@oreilly.com
　　For more information about our books, conferences, Resource Centers, and the O'Reilly Network, see our web site at:
　　http://www.oreilly.com
　　Acknowledgments
　　First we'd like to thank our editor, Michael Loukides, for his help and for acquiescing to our use of his name in recipe code samples, even when we turned him into a talking frog. The production editor, Colleen Gorman, was also very helpful.
　　This book would have taken longer to write and been less interesting without our contributing authors, who, collectively, wrote over 60 of these recipes. The roll of names includes: Steve Arniel, Ben Bleything, Antonio Cangiano, Mauro Cicio, Maurice Codik, Thomas Enebo, Pat Eyler, Bill Froelich, Rod Gaither, Ben Giddings, Michael Granger, James Edward Gray II, Stefan Lang, Kevin Marshall, Matthew Palmer Chetan Patil, Alun ap Rhisiart, Garrett Rooney, John-Mason Shackelford, Phil Tomson, and John Wells. They saved us time by lending their knowledge of various Ruby topics, and they enriched the book with their ideas.
　　This book would be of appallingly low quality were it not for our technical reviewers, who spotted dozens of bugs, platform-specific problems, and conceptual errors: John N. Alegre, Dave Burt, Bill Dolinar, Simen Edvardsen, Shane Emmons, Edward Faulkner, Dan Fitzpatrick, Bill Guindon, Stephen Hildrey, Meador Inge, Eric Jacoboni, Julian I. Kamil, Randy Kramer, Alex LeDonne, Steven Lumos, Keith Rosenblatt, Gene Tani, and R Vrajmohan.
　　Finally, to the programmers and writers of the Ruby community; from the celebrities like Yukihiro Matsumoto, Dave Thomas, Chad Fowler, and "why", to the hundreds of unsung heroes whose work went into the libraries we demonstrate throughout the book, and whose skill and patience bring more people into the Ruby community all the time....