www.it-ebooks.info www.it-ebooks.info 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 www.it-ebooks.info 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 w a s 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 w a s taken in the preparation of this book. However, the publisher assumes no re- sponsibility for errors or omissions, or for damages that may result from the use of information (in- cluding program listings) contained herein. Our Pragmatic courses, workshops, and other products can help y ou 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 www.it-ebooks.info Contents Foreword to the Third Edition . . . . . . . . . . ix Preface . . . . . . . . . . . . . . . . xi Road Map . . . . . . . . . . . . . . . xv Part I — Facets of Ruby 1. Getting Started . . . . . . . . . . . . . . 3 The Command Prompt 31.1 1.2 Installing Ruby 5 1.3 Running Ruby 9 1.4 Ruby Documentation: RDoc and ri 11 2. Ruby.new . . . . . . . . . . . . . . . 15 Ruby Is an Object-Oriented Language 152.1 2.2 Some Basic Ruby 17 2.3 Arrays and Hashes 20 2.4 Symbols 21 2.5 Control Structures 23 2.6 Regular Expressions 24 2.7 Blocks and Iterators 25 2.8 Reading and ’Riting 27 2.9 Command-Line Arguments 28 2.10 Onward and Upward 28 3. Classes, Objects, and Variables . . . . . . . . . . 29 Objects and Attributes 323.1 3.2 Classes Working with Other Classes 37 3.3 Access Control 40 3.4 Variables 43 4. Containers, Blocks, and Iterators . . . . . . . . . . 45 Arrays 454.1 4.2 Hashes 47 4.3 Blocks and Iterators 52 4.4 Containers Everywhere 68 www.it-ebooks.info 5. Sharing Functionality: Inheritance, Modules, and Mixins . . . . 69 Inheritance and Messages 695.1 5.2 Modules 73 5.3 Mixins 75 5.4 Iterators and the Enumerable Module 77 5.5 Composing Modules 77 5.6 Inheritance, Mixins, and Design 80 6. Standard Types . . . . . . . . . . . . . . 83 6.1 Numbers 83 6.2 Strings 86 6.3 Ranges 90 7. Regular Expressions . . . . . . . . . . . . . 93 What Regular Expressions Let Y o u Do 937.1 7.2 Ruby’s Regular Expressions 94 7.3 Digging Deeper 96 7.4 Advanced Regular Expressions 105 8. More About Methods . . . . . . . . . . . . 115 8.1 Defining a Method 115 8.2 Calling a Method 118 9. Expressions . . . . . . . . . . . . . . 125 Operator Expressions 1269.1 9.2 Miscellaneous Expressions 127 9.3 Assignment 128 9.4 Conditional Execution 132 9.5 case Expressions 136 9.6 Loops 138 9.7 Variable Scope, Loops, and Blocks 142 10. Exceptions, catch, and throw . . . . . . . . . . 145 The Exception Class 14510.1 10.2 Handling Exceptions 146 10.3 Raising Exceptions 150 10.4 catch and throw 151 11. Basic Input and Output . . . . . . . . . . . . 153 What Is an IO Object? 15311.1 11.2 Opening and Closing Files 153 11.3 Reading and Writing Files 154 11.4 Talking to Networks 158 11.5 Parsing HTML 159 12. Fibers, Threads, and Processes . . . . . . . . . . 161 Fibers 16112.1 12.2 Multithreading 163 12.3 Controlling the Thread Scheduler 167 Contents • iv www.it-ebooks.info 12.4 Mutual Exclusion 167 12.5 Running Multiple Processes 170 13. Unit Testing . . . . . . . . . . . . . . 175 The Testing Framework 17713.1 13.2 Structuring Tests 181 13.3 Organizing and Running Tests 183 13.4 RSpec and Shoulda 186 13.5 Test::Unit assertions 193 14. When Trouble Strikes! . . . . . . . . . . . . 195 Ruby Debugger 19514.1 14.2 Interactive Ruby 196 14.3 Editor Support 197 14.4 But It Doesn’t Work! 198 14.5 But It’s T o o Slow! 201 Part II — Ruby in Its Setting 15. Ruby and Its World . . . . . . . . . . . . 209 Command-Line Arguments 20915.1 15.2 Program Termination 214 15.3 Environment Variables 214 15.4 Where Ruby Finds Its Libraries 216 15.5 RubyGems Integration 217 15.6 The Rake Build Tool 222 15.7 Build Environment 224 16. Namespaces, Source Files, and Distribution . . . . . . . 225 16.1 Namespaces 225 16.2 Organizing Your Source 226 16.3 Distributing and Installing Your Code 233 17. Character Encoding . . . . . . . . . . . . 239 Encodings 24017.1 17.2 Source Files 240 17.3 Transcoding 245 17.4 Input and Output Encoding 246 17.5 Default External Encoding 248 17.6 Encoding Compatibility 249 17.7 Default Internal Encoding 250 17.8 Fun with Unicode 251 18. Interactive Ruby Shell . . . . . . . . . . . . 253 18.1 Command Line 253 18.2 Commands 260 19. Documenting Ruby . . . . . . . . . . . . 263 Adding RDoc to Ruby Code 26619.1 19.2 Adding RDoc to C Extensions 269 Contents • v www.it-ebooks.info 19.3 Running RDoc 271 19.4 Ruby source file documented with RDoc 272 19.5 C source file documented with RDoc 274 20. Ruby and the W e b . . . . . . . . . . . . . 277 Writing CGI Scripts 27720.1 20.2 Using cgi.rb 277 20.3 Templating Systems 280 20.4 Cookies 284 20.5 Choice of W e b Servers 286 20.6 Frameworks 287 21. Ruby and Microsoft Windows . . . . . . . . . . 289 21.1 Running Ruby Under Windows 289 21.2 Win32API 289 21.3 Windows Automation 290 Part III — Ruby Crystallized 22. The Ruby Language . . . . . . . . . . . . 297 Source File Encoding 29722.1 22.2 Source Layout 297 22.3 The Basic Types 299 22.4 Names 306 22.5 Variables and Constants 308 22.6 Expressions, Conditionals, and Loops 316 22.7 Method Definition 323 22.8 Invoking a Method 327 22.9 Aliasing 330 22.10 Class Definition 331 22.11 Module Definitions 333 22.12 Access Control 335 22.13 Blocks, Closures, and Proc Objects 335 22.14 Exceptions 339 22.15 catch and throw 341 23. Duck Typing . . . . . . . . . . . . . . 343 Classes Aren’t Types 34423.1 23.2 Coding like a Duck 348 23.3 Standard Protocols and Coercions 349 23.4 Walk the Walk, Talk the Talk 355 24. Metaprogramming . . . . . . . . . . . . . 357 Objects and Classes 35724.1 24.2 Singletons 360 24.3 Inheritance and Visibility 365 24.4 Modules and Mixins 366 24.5 Metaprogramming Class-Level Macros 372 24.6 T w o Other Forms of Class Definition 377 Contents • vi www.it-ebooks.info 24.7 instance_eval and class_eval 379 24.8 Hook Methods 383 24.9 One Last Example 388 24.10 Top-Level Execution Environment 390 24.11 The Turtle Graphics Program 391 25. Reflection, ObjectSpace, and Distributed Ruby . . . . . . 393 Looking at Objects 39325.1 25.2 Looking at Classes 394 25.3 Calling Methods Dynamically 396 25.4 System Hooks 398 25.5 Tracing Your Program’s Execution 400 25.6 Behind the Curtain: The Ruby VM 402 25.7 Marshaling and Distributed Ruby 403 25.8 Compile Time? Runtime? Anytime! 408 26. Locking Ruby in the Safe . . . . . . . . . . . 409 Safe Levels 41026.1 26.2 Tainted Objects 410 26.3 Trusted Objects 411 26.4 Definition of the safe levels 412 Part IV — Ruby Library Reference 27. Built-in Classes and Modules . . . . . . . . . . 417 28. Standard Library . . . . . . . . . . . . . 729 A1. Support . . . . . . . . . . . . . . . 829 W e b Sites 829A1.1 A1.2 Usenet Newsgroup 830 A1.3 Mailing Lists 830 A1.4 Bug Reporting 830 A2. Bibliography . . . . . . . . . . . . . . 831 Index . . . . . . . . . . . . . . . . 833 Contents • vii www.it-ebooks.info 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, w e 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 w a s 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 www.it-ebooks.info [...]... C:\Users\dave\.pik\rubies\JRuby-152\bin You now have two Ruby interpreters managed by pik You can switch between them at the command line: C:\>pik list 152: jruby 1.5.2 (ruby 1.8.7 patchlevel 249) (2010-08-20 1c5e29d) (Java H 193: ruby 1.9. 3p0 (2011-10-30) [i386-mingw32] www.it-ebooks.info report erratum • discuss Installing Ruby •7 C:\>pik use 152 C:\>jruby -v jruby 1.5.2 (ruby 1.8.7 patchlevel 249)... 20th birthday (it was created on February 24, 1993) The release of Ruby 2.0 is a celebration of that anniversary www.it-ebooks.info 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 (2013-02-24 revision 39474) [x86_64-darwin12.2.0] This... C:\>pik list 193: ruby 1.9. 3p0 (2011-10-30) [i386-mingw32] C:\>pik use 193 C:\ >ruby -v ruby 1.9. 3p0 (2011-10-30) [i386-mingw32] 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:... language now supports scores of 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 the first edition, we had to explain the background and appeal of Ruby Among other things, we wrote, “When we discovered Ruby, we realized that we’d found what we’d been looking...Preface This book is a new 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 from previous versions There are major changes in string handling, the scoping of block variables,... installed, tell pik to install the JRuby 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-152 done ** Adding: 152: jruby 1.5.2 (ruby 1.8.7 patchlevel 249) (2010-08-20 1c5e29d) (Java HotSpot(TM) Client... great things about Ruby is how well it integrates with its environment Part II, Ruby in Its Setting, investigates this Here you’ll find practical information on using Ruby: using the interpreter options, using irb, documenting your Ruby code, and packaging your Ruby gems so that others can enjoy them You’ll also find tutorials on some common Ruby tasks: using Ruby with the Web and using Ruby in a Microsoft... Running Ruby •9 The RubyGems that you install while you’re using an RVM-installed Ruby will be added to that version of Ruby and not installed globally Do not prepend the gem install command with a sudo—bad things will happen Why Stop with Ruby 2.0? As well as installing stable versions of the Matz Ruby interpreter, RVM will also manage interpreters from different sources (JRuby, Rubinius, Ruby Enterprise... that book Changes in the Ruby 2.0 Printing Compared to the major change that occurred between Ruby 1.8 and Ruby 1.9, the update to Ruby 2 is fairly gentle This book documents all the updated builtin class changes and the new keyword arguments It spends some time looking at lazy enumerators, and at the updates to the regular expression engine But, in general, users of Ruby 1.9 will feel right at home,... and Mac OS X includes Ruby (although the version of Ruby that comes with OS X is normally several releases behind the current Ruby version) Try typing ruby -v at a command prompt—you may be pleasantly surprised If you don’t already have Ruby on your system or if you’d like to upgrade to a newer version (remembering that this book describes Ruby 1.9 and Ruby 2.0), you can install it pretty simply What . Files 15 3 11 .3 Reading and Writing Files 15 4 11 .4 Talking to Networks 15 8 11 .5 Parsing HTML 15 9 12 . Fibers, Threads, and Processes . . . . . . . . . . 16 1 Fibers 16 1 12 .1 12. 2 Multithreading 16 3 12 .3. Frameworks 28 7 21 . Ruby and Microsoft Windows . . . . . . . . . . 2 89 21 . 1 Running Ruby Under Windows 2 89 21 . 2 Win32API 2 89 21 . 3 Windows Automation 29 0 Part III — Ruby Crystallized 22 . The Ruby Language. . . . . 29 7 Source File Encoding 29 7 22 .1 22 .2 Source Layout 29 7 22 .3 The Basic Types 29 9 22 .4 Names 306 22 .5 Variables and Constants 308 22 .6 Expressions, Conditionals, and Loops 316 22 .7 Method