Programming Ruby 1.9 & 2.0 The Pragmatic Programmers’ Guide Dave Thomas with Chad Fowler Andy Hunt The Pragmatic Bookshelf Dallas, Texas • Raleigh, North Carolina 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 The Pragmatic Starter Kit, The Pragmatic Programmer, Pragmatic Programming, Pragmatic Bookshelf, PragProg and the linking g device are trademarks of The Pragmatic Programmers, LLC 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 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 http://pragprog.com The team that produced this book includes: Janet Furlow (producer) Juliet Benda (rights) Ellie Callahan (support) Copyright © 2013 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 America ISBN-13: 978-1-93778-549-9 Encoded using the finest acid-free high-entropy binary digits Book version: P1.0—June, 2013 Contents Foreword to the Third Edition ix Preface xi Road Map xv Part I — Facets of Ruby Getting Started 1.1 The Command Prompt 1.2 Installing Ruby 1.3 Running Ruby 1.4 Ruby Documentation: RDoc and ri Ruby.new 2.1 Ruby Is an Object-Oriented Language 2.2 Some Basic Ruby 2.3 Arrays and Hashes 2.4 Symbols 2.5 Control Structures 2.6 Regular Expressions 2.7 Blocks and Iterators 2.8 Reading and ’Riting 2.9 Command-Line Arguments 2.10 Onward and Upward 15 15 17 20 21 23 24 25 27 28 28 Classes, Objects, and Variables 3.1 Objects and Attributes 3.2 Classes Working with Other Classes 3.3 Access Control 3.4 Variables 29 32 37 40 43 Containers, Blocks, and Iterators 4.1 Arrays 4.2 Hashes 4.3 Blocks and Iterators 4.4 Containers Everywhere 45 45 47 52 68 3 11 Contents • iv Sharing Functionality: Inheritance, Modules, and Mixins 5.1 Inheritance and Messages 5.2 Modules 5.3 Mixins 5.4 Iterators and the Enumerable Module 5.5 Composing Modules 5.6 Inheritance, Mixins, and Design 69 69 73 75 77 77 80 Standard Types 6.1 Numbers 6.2 Strings 6.3 Ranges Regular Expressions 7.1 What Regular Expressions Let You Do 7.2 Ruby’s Regular Expressions 7.3 Digging Deeper 7.4 Advanced Regular Expressions More About Methods 8.1 Defining a Method 8.2 Calling a Method 115 115 118 Expressions 9.1 Operator Expressions 9.2 Miscellaneous Expressions 9.3 Assignment 9.4 Conditional Execution 9.5 case Expressions 9.6 Loops 9.7 Variable Scope, Loops, and Blocks 125 126 127 128 132 136 138 142 10 Exceptions, catch, and throw 10.1 The Exception Class 10.2 Handling Exceptions 10.3 Raising Exceptions 10.4 catch and throw 145 145 146 150 151 11 Basic Input and Output 11.1 What Is an IO Object? 11.2 Opening and Closing Files 11.3 Reading and Writing Files 11.4 Talking to Networks 11.5 Parsing HTML 153 153 153 154 158 159 12 Fibers, Threads, and Processes 12.1 Fibers 12.2 Multithreading 12.3 Controlling the Thread Scheduler 161 161 163 167 83 83 86 90 93 93 94 96 105 Contents 12.4 12.5 Mutual Exclusion Running Multiple Processes •v 167 170 13 Unit Testing 13.1 The Testing Framework 13.2 Structuring Tests 13.3 Organizing and Running Tests 13.4 RSpec and Shoulda 13.5 Test::Unit assertions 175 177 181 183 186 193 14 When Trouble Strikes! 14.1 Ruby Debugger 14.2 Interactive Ruby 14.3 Editor Support 14.4 But It Doesn’t Work! 14.5 But It’s Too Slow! 195 195 196 197 198 201 Part II — Ruby in Its Setting 15 Ruby and Its World 15.1 Command-Line Arguments 15.2 Program Termination 15.3 Environment Variables 15.4 Where Ruby Finds Its Libraries 15.5 RubyGems Integration 15.6 The Rake Build Tool 15.7 Build Environment 16 209 209 214 214 216 217 222 224 Namespaces, Source Files, and Distribution 16.1 Namespaces 16.2 Organizing Your Source 16.3 Distributing and Installing Your Code 225 225 226 233 17 Character Encoding 17.1 Encodings 17.2 Source Files 17.3 Transcoding 17.4 Input and Output Encoding 17.5 Default External Encoding 17.6 Encoding Compatibility 17.7 Default Internal Encoding 17.8 Fun with Unicode 239 240 240 245 246 248 249 250 251 18 Interactive Ruby Shell 18.1 Command Line 18.2 Commands 253 253 260 19 Documenting Ruby 19.1 Adding RDoc to Ruby Code 19.2 Adding RDoc to C Extensions 263 266 269 Contents 19.3 19.4 19.5 Running RDoc Ruby source file documented with RDoc C source file documented with RDoc • vi 271 272 274 20 Ruby and the Web 20.1 Writing CGI Scripts 20.2 Using cgi.rb 20.3 Templating Systems 20.4 Cookies 20.5 Choice of Web Servers 20.6 Frameworks 277 277 277 280 284 286 287 21 Ruby and Microsoft Windows 21.1 Running Ruby Under Windows 21.2 Win32API 21.3 Windows Automation 289 289 289 290 Part III — Ruby Crystallized 22 The Ruby Language 22.1 Source File Encoding 22.2 Source Layout 22.3 The Basic Types 22.4 Names 22.5 Variables and Constants 22.6 Expressions, Conditionals, and Loops 22.7 Method Definition 22.8 Invoking a Method 22.9 Aliasing 22.10 Class Definition 22.11 Module Definitions 22.12 Access Control 22.13 Blocks, Closures, and Proc Objects 22.14 Exceptions 22.15 catch and throw 297 297 297 299 306 308 316 323 327 330 331 333 335 335 339 341 23 Duck Typing 23.1 Classes Aren’t Types 23.2 Coding like a Duck 23.3 Standard Protocols and Coercions 23.4 Walk the Walk, Talk the Talk 343 344 348 349 355 24 Metaprogramming 24.1 Objects and Classes 24.2 Singletons 24.3 Inheritance and Visibility 24.4 Modules and Mixins 24.5 Metaprogramming Class-Level Macros 24.6 Two Other Forms of Class Definition 357 357 360 365 366 372 377 Contents 24.7 24.8 24.9 24.10 24.11 instance_eval and class_eval Hook Methods One Last Example Top-Level Execution Environment The Turtle Graphics Program • vii 379 383 388 390 391 25 Reflection, ObjectSpace, and Distributed Ruby 25.1 Looking at Objects 25.2 Looking at Classes 25.3 Calling Methods Dynamically 25.4 System Hooks 25.5 Tracing Your Program’s Execution 25.6 Behind the Curtain: The Ruby VM 25.7 Marshaling and Distributed Ruby 25.8 Compile Time? Runtime? Anytime! 393 393 394 396 398 400 402 403 408 26 Locking Ruby in the Safe 26.1 Safe Levels 26.2 Tainted Objects 26.3 Trusted Objects 26.4 Definition of the safe levels 409 410 410 411 412 Part IV — Ruby Library Reference 27 Built-in Classes and Modules 417 28 Standard Library 729 A1 Support A1.1 Web Sites A1.2 Usenet Newsgroup A1.3 Mailing Lists A1.4 Bug Reporting 829 829 830 830 830 A2 Bibliography 831 Index 833 Foreword to the Third Edition I wrote forewords to the previous two editions of this book For the first edition, I wrote about motivation For the second edition, I wrote about miracles For this third edition, I’d like to write about courage I always admire brave people People around Ruby seem to be brave, like the authors of this book They were brave to jump in to a relatively unknown language like Ruby They were brave to try new technology They could have happily stayed with an old technology, but they didn’t They built their own world using new bricks and mortar They were adventurers, explorers, and pioneers By their effort, we have a fruitful result—Ruby Now, I feel that I’ve created my own universe with help from those brave people At first, I thought it was a miniature universe, like the one in “Fessenden’s Worlds.” But now it seems like a real universe Countless brave people are now working with Ruby They challenge new things every day, trying to make the world better and bigger I am very glad I am part of the Ruby world I suppose that even the world itself could not contain the books that should be written But now we have the first book, updated to the most recent Enjoy Yukihiro Matsumoto, aka “Matz” Japan, February 2009 report erratum • discuss Index and proc, 410 setting using -T, 212 and tainting, 410 $SAFE variable, 212, 314, 410, 608, 750 safe_level method, class Thread, 708 sample method, class Array, 435 Sandbox, 410–411 chroot, 456 scan method, class String, 48, 89, 683, 809 scanf library, 802 scanf method class Array, 802 class Object, 802 class String, 802 Scheduler, thread, 167 Schwartzian transform, 476 Scope, of monkeypatching, 369 Scope of variables, 53, 142, 308 SCRIPT_LINES constant, 316, 402 SDBM class, 803 Search path, 216 sec method, class Time, 717 SecureRandom module, 803 SecurityError exception, 409 seed method, class Random, 655 seek method class Dir, 460 class IO, 553 Seguin, Wayne E., Seki, Masatoshi, 407 select method class Hash, 529 class IO, 351, 542 class Object, 624 module Enumerable, 474 select! method class Array, 435 class Hash, 529 self method, class TracePoint, 724 self variable, 78, 118, 315, 329, 358 and instance variables, 358 and method calls, 358 in class definition, 359 Send message, 16 send method, class Object, 396, 607 send method, class BasicObject, 441 Sequence, infinite, 59 Server, 762 Session leader process, 641 Session module, 794 Session, HTTP, 285 Set class, 422, 424, 804 set_backtrace method, class Exception, 484 set_encoding method, class IO, 553 set_trace_func method class Object, 400, 447, 624, 819 class Thread, 708 setbyte method, class String, 684 setegid method, module Process::Sys, 647 seteuid method, module Process::Sys, 647 setgid, setuid, 410 setgid method, module Process::Sys, 647 setgid? method class File, 497 class File::Stat, 507 setpgid method, module Process, 641 setpgrp method, module Process, 641 setpriority method, module Process, 641 setregid method, module Process::Sys, 647 setresgid method, module Process::Sys, 648 setresuid method, module Process::Sys, 648 setreuid method, module Process::Sys, 648 setrgid method, module Process::Sys, 648 setrlimit method, module Process, 641 setruid method, module Process::Sys, 648 setsid method, module Process, 641 setuid method, module Process::Sys, 648 setuid? method class File, 498 class File::Stat, 507 setup method, 182 SHA1/2 hash, 747 Shallow copy, 601 Shared library, accessing, 756 Shebang (#!), 11 set encoding using, 241 SHELL (environment variable), 215 shell library, 730 Shell prompt, Shellwords module, 805 shift method class Array, 47, 435 class Hash, 530 Shoulda, 191 shuffle method, class Array, 436 shuffle! method, class Array, 436 • 857 sid_available? method module Process::GID, 644 module Process::UID, 649 Signal handling, 172 sending, 640 SIGALRM, 624 SIGCLD, 172 Signal module, 630, 664 list, 664 signame, 665 trap, 665 signaled? method, class Process::Status, 646 signame method, module Signal, 665 simplecov (code coverage), 204 SimpleDelegator class, 746 sin method, module Math, 564, 738 Single inheritance, 77 Single-quoted string, 86, 300 SingleForwardable module, 759 Singleton module, 806 Singleton pattern, 806 singleton_class method, class Object, 607 singleton_method_added method, class BasicObject, 442 singleton_method_removed method, class BasicObject, 442 singleton_method_undefined method, class BasicObject, 443 singleton_methods method, class Object, 608 sinh method, module Math, 564, 738 site_ruby directory, 216 size method class Array, 436 class Bignum, 446 class Enumerator, 481 class File, 498, 502 class File::Stat, 507 class Fixnum, 512 class Hash, 530 class MatchData, 561 class Range, 653 class String, 684 class Struct, 696 class Symbol, 700 size? method class File, 498 class File::Stat, 507 SizedQueue class, 813 SJIS, 97 sleep method class Mutex, 169, 588 class Object, 624 slice method class Array, 436 Index class String, 684 class Symbol, 701 slice! method class Array, 436 class String, 684 slice_before method, module Enumerable, 474 Smalltalk, 16 soap library, 730 Socket class, 807 socket? method class File, 498 class File::Stat, 507 SOCKSSocket class, 807 sort method class Hash, 530 module Enumerable, 475 sort! method, class Array, 437 sort, Schwartzian transform, 476 Sort, topological, 820 sort_by method class Hash, 49 module Enumerable, 475 sort_by! method, class Array, 437 Source code from book, coverage, 740 layout, 297 reflecting on, 401 source method, class Regexp, 663 source_location method class Method, 567 class Proc, 636 class UnboundMethod, 727 spawn method, 794 class Object, 625 module Process, 641 Splat (in assignment), 130 Splat argument, 116, 120 split method class File, 498 class Object, 210 class String, 88, 685 Spolsky, Joel, 240 sprintf method class Object, 626 field types, 627 flag characters, 626 sqrt method, module Math, 564, 738 squeeze method, class String, 89, 685 squeeze! method, class String, 686 srand method class Object, 628 class Random, 655 Stack, unwinding, 148, 152, 340 Stack frame, 195 Stack size, 215 Standard Library, 729–829 StandardError exception, 145, 148, 340 start method class Thread, 704 module GC, 517 start_with? method, class String, 686 :startdoc: (RDoc), 269 stat method class File, 498 class IO, 554 module GC, 517 Statement modifier if/unless, 136, 321 rescue, 340 while/until, 138, 323 status method, 781 class Exception, 484 class Thread, 709 STDERR constant, 316 $stderr variable, 313 STDIN constant, 316, 620 $stdin variable, 313 STDOUT constant, 316, 620–621 $stdout variable, 313 step method class Numeric, 139, 598 class Range, 654 Stephenson, Neal, 209 sticky? method class File, 498 class File::Stat, 508 stop method, class Thread, 704 stop? method, class Thread, 709 :stopdoc: (RDoc), 269 StopIteration exception, 58, 479, 620 stopped? method, class Process::Status, 646 stopsig method, class Process::Status, 646 store method, class Hash, 530 stress method, module GC, 517 stress= method, module GC, 518 strftime method, class Time, 718 String, 86 #{ }, 86 % delimiters, 298 control characters \n etc., 300 conversion for output, 157, 621 encoding, 243 expression interpolation, 18 here document, 87, 301 literal, 18, 86, 300 literal concatenation, 301 String class, 86, 88, 300, 351, 666, 802 %, 666 *, 667 +, 667 [...]... C:\Users\dave\.pik\rubies\JRuby -15 2\ bin You now have two Ruby interpreters managed by pik You can switch between them at the command line: C:\>pik list 15 2: jruby 1. 5 .2 (ruby 1. 8.7 patchlevel 2 49) (2 01 0 -08 - 20 1c5e29d) (Java H 19 3: ruby 1. 9. 3p0 (2 01 1 - 10 - 30) [i386-mingw 32] report erratum • discuss Installing Ruby •7 C:\>pik use 15 2 C:\>jruby -v jruby 1. 5 .2 (ruby 1. 8.7 patchlevel 2 49) (2 01 0 -08 - 20 1c5e29d) (Java HotSpot(TM)... chapter: Chapter 18 , Interactive Ruby Shell, on page 25 3.) You run irb from the command line Once it starts, just type in Ruby code It will show you the value of each expression as it evaluates it Exit an irb session by typing exit or by using the Ctrl+D $ irb 2. 0. 0 :0 01 > 2. 0. 0 :0 02 ? > 2. 0. 0 :00 3?> => nil 2. 0. 0 :00 4 > => 7 2. 0. 0 :00 5 > => "catdog" 2. 0. 0 :00 6 > def sum(n1, n2) n1 + n2 end sum(3,4) sum("cat",... interpreter: C:\> pik install jruby ** Downloading: http://jruby.org downloads /1. 5 .2/ jruby-bin -1. 5 .2. zip to: C:\Users\dave\.pik\downloads\jruby-bin -1. 5 .2. zip ** Extracting: C:\Users\dave\.pik\downloads\jruby-bin -1. 5 .2. zip to: C:\Users\dave\.pik\rubies\JRuby -15 2 done ** Adding: 15 2: jruby 1. 5 .2 (ruby 1. 8.7 patchlevel 2 49) (2 01 0 -08 - 20 1c5e29d) (Java HotSpot(TM) Client VM 1. 6 .0_ 21 ) [x86-java] Located at: C:\Users\dave\.pik\rubies\JRuby -15 2\ bin... happened on Ruby s 20 th birthday (it was created on February 24 , 19 93 ) The release of Ruby 2. 0 is a celebration of that anniversary report erratum • discuss Preface • xii Ruby Versions 1 This version of the PickAxe documents both Ruby 2. 0 and Ruby 1. 9. 3 Exactly what version of Ruby did I use to write this book? Let’s ask Ruby: $ ruby -v ruby 2. 0. 0p0 (2 01 3 - 02 - 24 revision 394 74) [x86_64-darwin 12. 2 .0] This... C:\>pik list 19 3: ruby 1. 9. 3p0 (2 01 1 - 10 - 30) [i386-mingw 32] C:\>pik use 19 3 C:\ >ruby -v ruby 1. 9. 3p0 (2 01 1 - 10 - 30) [i386-mingw 32] Having gotten one Ruby registered with pik, let’s install another We’ll play with JRuby, an implementation of Ruby written in Java Before doing this, you’ll need to download the Java runtime (Google is your friend) Once Java is installed, tell pik to install the JRuby interpreter:... downloads the appropriate source code and builds Ruby 2. 0 It also installs a few tools (including irb, RDoc, ri, and RubyGems) Be patient—the process may take five minutes or so Once it finishes, you’ll have Ruby 2. 0 installed To use it, type the following: dave@ubuntu:~$ rvm use 2. 0. 0 info: Using ruby 2. 0. 0 dave@ubuntu:~$ ruby -v ruby 2. 0. 0p0 (2 01 3 - 02 - 24 revision 394 74) [i686-linux] This is probably more... But, before we go any further, let’s 7 test to see whether Ruby is installed Bring up a fresh command prompt, and type this: $ ruby -v ruby 2. 0. 0p0 (2 01 3 - 02 - 24 revision 394 74) [x86_64-darwin 12. 2 .0] If you believe that you should have Ruby installed and yet you get an error saying something like ruby: command not found,” then it is likely that the Ruby program is not in your path —the list of places that... Ruby command prompt (Start Command Prompt with Ruby) , and type the following at the prompt: C:\Users\dave> pik add ** Adding: 19 3: ruby 1. 9. 3p0 (2 01 1 - 10 - 30) [i386-mingw 32] You’ve now registered that Ruby interpreter with pik At any other command prompt, you can use the pik command to list the Ruby interpreters pik knows about and to tell pik to make a particular interpreter current: C:\>pik list 19 3:... report erratum • discuss Installing Ruby •7 C:\>pik use 15 2 C:\>jruby -v jruby 1. 5 .2 (ruby 1. 8.7 patchlevel 2 49) (2 01 0 -08 - 20 1c5e29d) (Java HotSpot(TM) Client VM 1. 6 .0_ 21 ) [x86-java] C:\>pik use 19 3 C:\ >ruby -v ruby 1. 9. 3p0 (2 01 1 - 10 - 30) [i386-mingw 32] If you plan on installing gems that have native code components (that is, they interface to existing Windows libraries using C code), you’ll need a C development... between curly braces, not parentheses.) You can run a Ruby program from a file as you would any other shell script, Perl program, or Python program Simply run the Ruby interpreter, giving it the script name as an argument: $ ruby myprog.rb Hello, Ruby Programmer It is now 2 01 3 -05 -27 12 : 30: 36 -05 00 report erratum • discuss Ruby Documentation: RDoc and ri • 11 8 On Unix systems, you can use the “shebang” notation ... exit or by using the Ctrl+D $ irb 2. 0. 0 :0 01 > 2. 0. 0 :0 02? > 2. 0. 0 :00 3?> => nil 2. 0. 0 :00 4 > => 2. 0. 0 :00 5 > => "catdog" 2. 0. 0 :00 6 > def sum(n1, n2) n1 + n2 end sum(3,4) sum("cat", "dog") exit... 12 5 12 6 12 7 12 8 13 2 13 6 13 8 14 2 10 Exceptions, catch, and throw 10 .1 The Exception Class 10 .2 Handling Exceptions 10 .3 Raising Exceptions 10 .4 catch and throw 14 5 14 5 14 6 15 0 15 1 11 ... Definitions 22 . 12 Access Control 22 .13 Blocks, Closures, and Proc Objects 22 .14 Exceptions 22 .15 catch and throw 29 7 29 7 29 7 29 9 306 308 316 323 327 3 30 3 31 333 335 335 3 39 3 41 23 Duck Typing