Programming Ruby 1.9The Pragmatic Programmers Guide

Dave Thomas

with Chad Fowler

and Andy Hunt

The Pragmatic BookshelfRaleigh, North Carolina Dallas, Texas

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.

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.

This book is a heavily revised version of the book Programming Ruby, originally published by Addison Wesley.

This book is printed with their permission.

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://www.pragmaticprogrammer.com

Copyright 2009 The Pragmatic Programmers, LLC. All rights reserved. No part of this publication may be repro-

duced, stored in a retrieval system, or transmitted, in any form, or by any means, electronic, mechanical, photocopy-

ing, recording, or otherwise, without the prior consent of the publisher.

Printed in the United States of America.

ISBN: 1-934356-08-5

ISBN-13: 978-1-934356-08-1

Printing: P2.00, April 2009

Version: 2009-4-18

Text printed on acid-free paper.

http://www.pragmaticprogrammer.com

Contents

FOREWORD 16

PREFACE 17

ROAD MAP 22

PART IFACETS OF RUBY

1 GETTING STARTED 25The Command Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Installing Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Running Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Ruby Documentation: RDoc and ri . . . . . . . . . . . . . . . . . . . . . . . . 32

2 RUBY.NEW 35Ruby Is an Object-Oriented Language . . . . . . . . . . . . . . . . . . . . . . 35

Some Basic Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Arrays and Hashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Blocks and Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Reading and Riting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Command-Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Onward and Upward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

3 CLASSES, OBJECTS, AND VARIABLES 50Objects and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Classes Working with Other Classes . . . . . . . . . . . . . . . . . . . . . . . 58

Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Report erratum4

http://books.pragprog.com/titles/ruby3/errata/add?pdf_page=4

CONTENTS 5

4 CONTAINERS, BLOCKS, AND ITERATORS 67Blocks and Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Containers Everywhere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

5 SHARING FUNCTIONALITY: INHERITANCE, MODULES, AND MIXINS 91Inheritance and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Mixins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Iterators and the Enumerable Module . . . . . . . . . . . . . . . . . . . . . . . 100

Composing Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Inheritance, Mixins, and Design . . . . . . . . . . . . . . . . . . . . . . . . . 104

6 STANDARD TYPES 106Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

7 REGULAR EXPRESSIONS 117What Regular Expressions Let You Do . . . . . . . . . . . . . . . . . . . . . . 117

Rubys Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Digging Deeper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Pattern-Based Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Advanced Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 130

8 MORE ABOUT METHODS 137Defining a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Calling a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

9 EXPRESSIONS 146Operator Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Miscellaneous Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Conditional Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Case Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Variable Scope, Loops, and Blocks . . . . . . . . . . . . . . . . . . . . . . . . 165

10 EXCEPTIONS, CATCH, AND THROW 167The Exception Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Handling Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Raising Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Catch and Throw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

11 BASIC INPUT AND OUTPUT 176What Is an IO Object? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Opening and Closing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Reading and Writing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Talking to Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Report erratum

http://books.pragprog.com/titles/ruby3/errata/add?pdf_page=5

CONTENTS 6

12 FIBERS, THREADS, AND PROCESSES 184Fibers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Multithreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Controlling the Thread Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . 190

Mutual Exclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Running Multiple Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

13 UNIT TESTING 198The Testing Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Structuring Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Organizing and Running Tests . . . . . . . . . . . . . . . . . . . . . . . . . . 206

RSpec and Shoulda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

14 WHEN TROUBLE STRIKES 220Ruby Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Interactive Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Editor Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

But It Doesnt Work! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

But Its Too Slow! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

PART IIRUBY IN ITS SETTING

15 RUBY AND ITS WORLD 233Command-Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Program Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Where Ruby Finds Its Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 238

RubyGems Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

The Rake Build Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Build Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

16 NAMESPACES, SOURCE FILES, AND DISTRIBUTION 249Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Organizing Your Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Distributing and Installing Your Code . . . . . . . . . . . . . . . . . . . . . . 258

17 CHARACTER ENCODING 264Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Transcoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Input and Output Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Default External Encoding . . . . . .