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 ... Preface • xii Ruby Versions 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 (2013-02-24... version of the PickAxe, as Programming Ruby is known to Ruby programmers It is a tutorial and reference for versions 1.9 and 2.0 of the Ruby programming language Ruby 1.9 was a significant departure... character encodings, making Ruby one of the only programming languages to live fully in the whole world Ruby 2.0 is a (fairly minor) incremental improvement on Ruby 1.9 Why Ruby? When Andy and I wrote