Contents
This document was uploaded by user and they confirmed that they have the permission to share it. If you are author or own the copyright of this book, please report to us by using this DMCA report form. Report DMCA
Overview
Download & View Contents as PDF for free.
More details
- Words: 12,060
- Pages: 13
Extracted from:
Programming Ruby The Pragmatic Programmers’ Guide Second Edition
This PDF file contains pages extracted from Programming Ruby, published by The Pragmatic Bookshelf. For more information, visit http://www.pragmaticbookshelf.com. Note: This extract contains some colored text. is available only in online versions of the books. The printed versions are black and white. Pagination might vary between the online and printer versions; the content is otherwise identical. Copyright © 2004 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.
Contents F OREWORD F OREWORD P REFACE ROAD M AP
TO THE TO THE
F IRST E DITION S ECOND E DITION
xix xxi xxii xxviii
PART I—FACETS OF R UBY 1
G ETTING S TARTED Installing Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ruby Documentation: RDoc and ri . . . . . . . . . . . . . . . . . . . . .
2
RUBY. NEW Ruby Is an Object-Oriented Language Some Basic Ruby . . . . . . . . . . . Arrays and Hashes . . . . . . . . . . . Control Structures . . . . . . . . . . . Regular Expressions . . . . . . . . . . Blocks and Iterators . . . . . . . . . . Reading and ’Riting . . . . . . . . . . Onward and Upward . . . . . . . . . .
3
2 2 4 7
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
9 9 11 14 16 17 19 21 22
C LASSES , O BJECTS , AND VARIABLES Inheritance and Messages . . . . . . . . . . . . . Objects and Attributes . . . . . . . . . . . . . . . Class Variables and Class Methods . . . . . . . . Access Control . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
23 25 27 31 35 37
Prepared exclusively for a Pragmatic Client
. . . . . . . .
. . . . . . . .
vii
. . . . . . . .
. . . . . . . .
. . . . . . . .
4
C ONTAINERS , B LOCKS ,
I TERATORS
AND Containers . . . . . . . . . . . . . . Blocks and Iterators . . . . . . . . . Containers Everywhere . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40 40 46 54
S TANDARD T YPES Numbers . . . . . . . . Strings . . . . . . . . . Ranges . . . . . . . . . Regular Expressions . .
. . . .
. . . .
55 55 57 62 64
6
M ORE ABOUT M ETHODS Defining a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
74 74 76
7
E XPRESSIONS Operator Expressions . . . . . . . Miscellaneous Expressions . . . . Assignment . . . . . . . . . . . . Conditional Execution . . . . . . . Case Expressions . . . . . . . . . Loops . . . . . . . . . . . . . . . . Variable Scope, Loops, and Blocks
5
8
9
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
E XCEPTIONS , C ATCH , AND The Exception Class . . . . . . . . Handling Exceptions . . . . . . . . Raising Exceptions . . . . . . . . . Catch and Throw . . . . . . . . . .
. . . .
. . . . . . .
. . . . . . .
. . . .
. . . . . . .
. . . .
. . . . . . .
. . . .
. . . . . . .
. . . .
. . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
81 82 83 84 87 92 94 99
T HROW . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
101 101 102 106 108
M ODULES Namespaces . . . . . . . . . . . . . Mixins . . . . . . . . . . . . . . . . Iterators and the Enumerable Module Composing Modules . . . . . . . . . Including Other Files . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
110 110 111 113 113 116
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
119 119 120 121 125
10 BASIC I NPUT
AND O UTPUT What Is an IO Object? . . . . . . . Opening and Closing Files . . . . . Reading and Writing Files . . . . . Talking to Networks . . . . . . . .
. . . .
11 T HREADS
AND P ROCESSES Multithreading . . . . . . . . . . . Controlling the Thread Scheduler . Mutual Exclusion . . . . . . . . . Running Multiple Processes . . . .
. . . .
127 127 132 133 139
Test::Unit Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structuring Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Organizing and Running Tests . . . . . . . . . . . . . . . . . . . . . . . .
143 144 148 151
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
12 U NIT T ESTING
13 W HEN T ROUBLE S TRIKES Ruby Debugger . . . Interactive Ruby . . . Editor Support . . . . But It Doesn’t Work! . But It’s Too Slow! . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
155 155 156 157 159 162
PART II—R UBY IN I TS S ETTING AND I TS W ORLD Command-Line Arguments . . Program Termination . . . . . Environment Variables . . . . . Where Ruby Finds Its Modules Build Environment . . . . . . .
14 RUBY
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
167 167 170 171 172 173
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
174 174 179 183 185 185
. . . .
187 187 195 199 200
15 I NTERACTIVE RUBY S HELL Command Line . Configuration . Commands . . . Restrictions . . rtags and xmp .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
16 D OCUMENTING RUBY Adding RDoc to Ruby Code . Adding RDoc to C Extensions Running RDoc . . . . . . . . Displaying Program Usage .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
17 PACKAGE M ANAGEMENT
WITH Installing RubyGems . . . . . . . . . . Installing Application Gems . . . . . . . Installing and Using Gem Libraries . . . Creating Your Own Gems . . . . . . . . AND THE W EB Writing CGI Scripts . . . . Cookies . . . . . . . . . . Improving Performance . . Choice of Web Servers . . . SOAP and Web Services . . More Information . . . . .
RUBY G EMS . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
203 204 204 206 211
18 RUBY
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
222 222 231 234 234 236 240
Simple Tk Application . . . . . . . . . . Widgets . . . . . . . . . . . . . . . . . Binding Events . . . . . . . . . . . . . . Canvas . . . . . . . . . . . . . . . . . . Scrolling . . . . . . . . . . . . . . . . . Translating from Perl/Tk Documentation
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
241 241 242 246 247 249 251
AND M ICROSOFT W INDOWS Getting Ruby for Windows . . . . . . . . . . Running Ruby Under Windows . . . . . . . . Win32API . . . . . . . . . . . . . . . . . . . Windows Automation . . . . . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
253 253 254 254 255
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
261 261 264 270 279 280 282 287 290 291
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
19 RUBY T K
20 RUBY
21 E XTENDING RUBY Your First Extension . . . . . . . . Ruby Objects in C . . . . . . . . . The Jukebox Extension . . . . . . Memory Allocation . . . . . . . . Ruby Type System . . . . . . . . . Creating an Extension . . . . . . . Embedding a Ruby Interpreter . . . Bridging Ruby to Other Languages Ruby C Language API . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
PART III—R UBY C RYSTALLIZED 22 T HE RUBY L ANGUAGE . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
302 302 304 313 315 318 323 326 328 328 329 330 333 336 337 339 341 341 345 347
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
349 350 354 355 361
AND O BJECTS How Classes and Objects Interact . Class and Module Definitions . . . Top-Level Execution Environment Inheritance and Visibility . . . . . Freezing Objects . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
362 362 370 376 376 377
IN THE S AFE Safe Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tainted Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
379 380 381
Source Layout . . . . . . . . . . . The Basic Types . . . . . . . . . . Names . . . . . . . . . . . . . . . Variables and Constants . . . . . . Predefined Variables . . . . . Expressions . . . . . . . . . . . . Boolean Expressions . . . . . if and unless Expressions . . case Expressions . . . . . . . Loop Constructs . . . . . . . . Method Definition . . . . . . . . . Invoking a Method . . . . . . . . . Aliasing . . . . . . . . . . . . . . Class Definition . . . . . . . . . . Module Definitions . . . . . . . . Access Control . . . . . . . . . . . Blocks, Closures, and Proc Objects Exceptions . . . . . . . . . . . . . Catch and Throw . . . . . . . . . .
23 D UCK T YPING Classes Aren’t Types . . . . . . . Coding like a Duck . . . . . . . Standard Protocols and Coercions Walk the Walk, Talk the Talk . .
24 C LASSES
25 L OCKING RUBY
26 R EFLECTION , O BJECT S PACE , Looking at Objects . . . . . . . . . Looking at Classes . . . . . . . . . Calling Methods Dynamically . . . System Hooks . . . . . . . . . . . Tracing Your Program’s Execution Marshaling and Distributed Ruby . Compile Time? Runtime? Anytime!
. . . . . . .
. . . . . . .
AND D ISTRIBUTED RUBY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
384 385 386 388 391 393 395 400
PART IV—R UBY L IBRARY R EFERENCE 27 BUILT- IN C LASSES Alphabetical Listing Array . . . . . Bignum . . . . Binding . . . . Class . . . . . Comparable . . Continuation Dir . . . . . . Enumerable . . Errno . . . . . Exception . . FalseClass . . File . . . . . . File::Stat . . FileTest . . . Fixnum . . . . Float . . . . . GC . . . . . . . Hash . . . . . . Integer . . . . IO . . . . . . . Kernel . . . . Marshal . . . . MatchData . . Math . . . . . . Method . . . . Module . . . . NilClass . . . Numeric . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AND M ODULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
402 403 406 420 423 424 426 427 428 433 439 440 443 444 456 462 463 466 470 471 480 482 495 514 516 519 522 524 540 541
Object . . . . . . ObjectSpace . . . Proc . . . . . . . . Process . . . . . . Process::GID . . Process::Status Process::Sys . . Process::UID . . Range . . . . . . . Regexp . . . . . . Signal . . . . . . String . . . . . . Struct . . . . . . Struct::Tms . . . Symbol . . . . . . Thread . . . . . . ThreadGroup . . . Time . . . . . . . . TrueClass . . . . UnboundMethod . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
546 557 559 562 568 570 573 575 576 579 583 585 605 609 610 612 619 621 629 630
. . . . . . . . . . . . . . . . . . . . .
632 634 635 636 637 638 640 641 642 643 644 645 646 647 648 649 650 651 652 654 655 656
28 S TANDARD L IBRARY Abbrev . . . . Base64 . . . . Benchmark . . BigDecimal . . CGI . . . . . . CGI::Session Complex . . . . CSV . . . . . . Curses . . . . Date/DateTime DBM . . . . . . Delegator . . Digest . . . . DL . . . . . . . dRuby . . . . . English . . . . Enumerator . . erb . . . . . . Etc . . . . . . expect . . . . Fcntl . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
FileUtils . . Find . . . . . . Forwardable . ftools . . . . GDBM . . . . . . Generator . . GetoptLong . . GServer . . . . Iconv . . . . . IO/Wait . . . . IPAddr . . . . jcode . . . . . Logger . . . . Mail . . . . . . mathn . . . . . Matrix . . . . Monitor . . . . Mutex . . . . . Mutex_m . . . . Net::FTP . . . Net::HTTP . . Net::IMAP . . Net::POP . . . Net::SMTP . . Net::Telnet . NKF . . . . . . Observable . . open-uri . . . Open3 . . . . . OpenSSL . . . . OpenStruct . . OptionParser ParseDate . . Pathname . . . PP . . . . . . . PrettyPrint . Profile . . . . Profiler_ _ . PStore . . . . PTY . . . . . . Rational . . . readbytes . . Readline . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 673 674 675 676 677 678 680 681 682 683 684 685 686 687 688 689 690 692 693 694 695 696 697 698 699 700 701 702
Resolv . . . . REXML . . . . . Rinda . . . . . RSS . . . . . . Scanf . . . . . SDBM . . . . . . Set . . . . . . Shellwords . . Singleton . . SOAP . . . . . . Socket . . . . StringIO . . . StringScanner Sync . . . . . . Syslog . . . . Tempfile . . . Test::Unit . . thread . . . . ThreadsWait . Time . . . . . . Timeout . . . . Tk . . . . . . . tmpdir . . . . Tracer . . . . TSort . . . . . un . . . . . . . URI . . . . . . WeakRef . . . . WEBrick . . . . Win32API . . . WIN32OLE . . . XMLRPC . . . . YAML . . . . . . Zlib . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
703 704 706 707 708 709 710 711 712 713 714 715 716 717 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738
PART V—A PPENDIXES A S OCKET L IBRARY . . . . . . . . .
740 741 743 747 748 749 750 751 753 754
mkmf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
755 755
BasicSocket Socket . . . IPSocket . . TCPSocket . SOCKSSocket TCPServer . UDPSocket . UNIXSocket . UNIXServer .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
B MKMF R EFERENCE C S UPPORT Web Sites . . . . Download Sites . Usenet Newsgroup Mailing Lists . . .
. . . .
. . . .
. . . .
D B IBLIOGRAPHY
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
758 758 759 759 759 761
I NDEX
762
S UMMARY TABLES
797
List of Tables 2.1 5.1 7.1 11.1 13.1 14.1 15.1 17.1 18.1 21.1 22.1 22.2 22.3 22.4 25.1 27.1 27.2 27.3 27.4 27.5 27.6 27.7 27.8 27.9 27.10 27.11 27.12 27.13 27.14 27.15 28.1 28.2
Example variable and class names . . . . . . . . . . . . Character class abbreviations . . . . . . . . . . . . . . . Common comparison operators . . . . . . . . . . . . . . Two threads in a race condition . . . . . . . . . . . . . . Debugger commands . . . . . . . . . . . . . . . . . . . Environment variables used by Ruby . . . . . . . . . . . irb command-line options . . . . . . . . . . . . . . . . . Version operators . . . . . . . . . . . . . . . . . . . . . Command-line options for erb . . . . . . . . . . . . . . C/Ruby data type conversion functions and macros . . . General delimited input . . . . . . . . . . . . . . . . . . Substitutions in double-quoted strings . . . . . . . . . . Reserved words . . . . . . . . . . . . . . . . . . . . . . Ruby operators (high to low precedence) . . . . . . . . . Definition of the safe levels . . . . . . . . . . . . . . . . Class Array: pack directives . . . . . . . . . . . . . . . Class File: match-mode constants . . . . . . . . . . . . Class File: path separators . . . . . . . . . . . . . . . . Class File: open-mode constants . . . . . . . . . . . . . Class File: lock-mode constants . . . . . . . . . . . . . Class IO: mode strings . . . . . . . . . . . . . . . . . . Module Kernel: sprintf flag characters . . . . . . . . Module Kernel: sprintf field types . . . . . . . . . . . Module Kernel: file tests with a single argument . . . . Module Kernel: file tests with two arguments . . . . . . Class Numeric: methods and subclasses . . . . . . . . . Class Numeric: divmod, modulo, and remainder . . . . Class String: backslash sequences in substitution strings Class String: unpack directives . . . . . . . . . . . . . Class Time: strftime directives . . . . . . . . . . . . . Class ERB: inline directives . . . . . . . . . . . . . . . . Class OptionParser: option definitions . . . . . . . . .
Prepared exclusively for a Pragmatic Client
xvii
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15 68 89 135 165 172 175 206 230 266 304 306 314 324 383 414 447 449 451 455 483 510 511 512 512 543 544 593 603 627 653 691
List of Figures 3.1 4.1 8.1 12.1 12.2 13.1 13.2 16.1 16.2 16.3 16.4 16.5 16.6 16.7 16.8 17.1 18.1 18.2 19.1 21.1 21.2 22.1 24.1 24.2 24.3 24.4 27.1 27.2
Variables hold object references. . . . . . . . . . How arrays are indexed . . . . . . . . . . . . . . Ruby exception hierarchy . . . . . . . . . . . . . Roman numerals generation (with bugs) . . . . . Test::Unit assertions . . . . . . . . . . . . . . . . Sample irb session . . . . . . . . . . . . . . . . . Comparing variable access costs using benchmark Browse RDoc output for class counter . . . . . . Browse RDoc output when source has comments Using ri to read documentation . . . . . . . . . . Document for class Proc generated by RDoc/ri . Ruby source file documented with RDoc . . . . . C source file documented with RDoc . . . . . . . Sample program using RDoc::usage . . . . . . . Help generated by sample program . . . . . . . . MomLog package structure . . . . . . . . . . . . Sample CGI Form . . . . . . . . . . . . . . . . . Erb processing a file with loops . . . . . . . . . . Drawing on a Tk Canvas . . . . . . . . . . . . . Wrapping objects around C data types . . . . . . Building an extension . . . . . . . . . . . . . . . State transitions for boolean range . . . . . . . . A basic object, with its class and superclass . . . Adding a metaclass to Guitar . . . . . . . . . . Adding a virtual class to an object . . . . . . . . An included module and its proxy class . . . . . Standard exception hierarchy . . . . . . . . . . . Method#arity in action . . . . . . . . . . . . .
Prepared exclusively for a Pragmatic Client
xviii
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
39 42 103 145 154 158 163 188 189 190 191 196 198 201 202 220 225 232 248 272 283 327 363 364 367 369 441 523
Programming Ruby The Pragmatic Programmers’ Guide Second Edition
This PDF file contains pages extracted from Programming Ruby, published by The Pragmatic Bookshelf. For more information, visit http://www.pragmaticbookshelf.com. Note: This extract contains some colored text. is available only in online versions of the books. The printed versions are black and white. Pagination might vary between the online and printer versions; the content is otherwise identical. Copyright © 2004 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.
Contents F OREWORD F OREWORD P REFACE ROAD M AP
TO THE TO THE
F IRST E DITION S ECOND E DITION
xix xxi xxii xxviii
PART I—FACETS OF R UBY 1
G ETTING S TARTED Installing Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ruby Documentation: RDoc and ri . . . . . . . . . . . . . . . . . . . . .
2
RUBY. NEW Ruby Is an Object-Oriented Language Some Basic Ruby . . . . . . . . . . . Arrays and Hashes . . . . . . . . . . . Control Structures . . . . . . . . . . . Regular Expressions . . . . . . . . . . Blocks and Iterators . . . . . . . . . . Reading and ’Riting . . . . . . . . . . Onward and Upward . . . . . . . . . .
3
2 2 4 7
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
9 9 11 14 16 17 19 21 22
C LASSES , O BJECTS , AND VARIABLES Inheritance and Messages . . . . . . . . . . . . . Objects and Attributes . . . . . . . . . . . . . . . Class Variables and Class Methods . . . . . . . . Access Control . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
23 25 27 31 35 37
Prepared exclusively for a Pragmatic Client
. . . . . . . .
. . . . . . . .
vii
. . . . . . . .
. . . . . . . .
. . . . . . . .
4
C ONTAINERS , B LOCKS ,
I TERATORS
AND Containers . . . . . . . . . . . . . . Blocks and Iterators . . . . . . . . . Containers Everywhere . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40 40 46 54
S TANDARD T YPES Numbers . . . . . . . . Strings . . . . . . . . . Ranges . . . . . . . . . Regular Expressions . .
. . . .
. . . .
55 55 57 62 64
6
M ORE ABOUT M ETHODS Defining a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling a Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
74 74 76
7
E XPRESSIONS Operator Expressions . . . . . . . Miscellaneous Expressions . . . . Assignment . . . . . . . . . . . . Conditional Execution . . . . . . . Case Expressions . . . . . . . . . Loops . . . . . . . . . . . . . . . . Variable Scope, Loops, and Blocks
5
8
9
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
E XCEPTIONS , C ATCH , AND The Exception Class . . . . . . . . Handling Exceptions . . . . . . . . Raising Exceptions . . . . . . . . . Catch and Throw . . . . . . . . . .
. . . .
. . . . . . .
. . . . . . .
. . . .
. . . . . . .
. . . .
. . . . . . .
. . . .
. . . . . . .
. . . .
. . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
81 82 83 84 87 92 94 99
T HROW . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
101 101 102 106 108
M ODULES Namespaces . . . . . . . . . . . . . Mixins . . . . . . . . . . . . . . . . Iterators and the Enumerable Module Composing Modules . . . . . . . . . Including Other Files . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
110 110 111 113 113 116
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
119 119 120 121 125
10 BASIC I NPUT
AND O UTPUT What Is an IO Object? . . . . . . . Opening and Closing Files . . . . . Reading and Writing Files . . . . . Talking to Networks . . . . . . . .
. . . .
11 T HREADS
AND P ROCESSES Multithreading . . . . . . . . . . . Controlling the Thread Scheduler . Mutual Exclusion . . . . . . . . . Running Multiple Processes . . . .
. . . .
127 127 132 133 139
Test::Unit Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . Structuring Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Organizing and Running Tests . . . . . . . . . . . . . . . . . . . . . . . .
143 144 148 151
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
12 U NIT T ESTING
13 W HEN T ROUBLE S TRIKES Ruby Debugger . . . Interactive Ruby . . . Editor Support . . . . But It Doesn’t Work! . But It’s Too Slow! . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
155 155 156 157 159 162
PART II—R UBY IN I TS S ETTING AND I TS W ORLD Command-Line Arguments . . Program Termination . . . . . Environment Variables . . . . . Where Ruby Finds Its Modules Build Environment . . . . . . .
14 RUBY
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
167 167 170 171 172 173
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
174 174 179 183 185 185
. . . .
187 187 195 199 200
15 I NTERACTIVE RUBY S HELL Command Line . Configuration . Commands . . . Restrictions . . rtags and xmp .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
16 D OCUMENTING RUBY Adding RDoc to Ruby Code . Adding RDoc to C Extensions Running RDoc . . . . . . . . Displaying Program Usage .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
17 PACKAGE M ANAGEMENT
WITH Installing RubyGems . . . . . . . . . . Installing Application Gems . . . . . . . Installing and Using Gem Libraries . . . Creating Your Own Gems . . . . . . . . AND THE W EB Writing CGI Scripts . . . . Cookies . . . . . . . . . . Improving Performance . . Choice of Web Servers . . . SOAP and Web Services . . More Information . . . . .
RUBY G EMS . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
203 204 204 206 211
18 RUBY
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
222 222 231 234 234 236 240
Simple Tk Application . . . . . . . . . . Widgets . . . . . . . . . . . . . . . . . Binding Events . . . . . . . . . . . . . . Canvas . . . . . . . . . . . . . . . . . . Scrolling . . . . . . . . . . . . . . . . . Translating from Perl/Tk Documentation
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
241 241 242 246 247 249 251
AND M ICROSOFT W INDOWS Getting Ruby for Windows . . . . . . . . . . Running Ruby Under Windows . . . . . . . . Win32API . . . . . . . . . . . . . . . . . . . Windows Automation . . . . . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
253 253 254 254 255
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
261 261 264 270 279 280 282 287 290 291
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
19 RUBY T K
20 RUBY
21 E XTENDING RUBY Your First Extension . . . . . . . . Ruby Objects in C . . . . . . . . . The Jukebox Extension . . . . . . Memory Allocation . . . . . . . . Ruby Type System . . . . . . . . . Creating an Extension . . . . . . . Embedding a Ruby Interpreter . . . Bridging Ruby to Other Languages Ruby C Language API . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
PART III—R UBY C RYSTALLIZED 22 T HE RUBY L ANGUAGE . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . .
302 302 304 313 315 318 323 326 328 328 329 330 333 336 337 339 341 341 345 347
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
349 350 354 355 361
AND O BJECTS How Classes and Objects Interact . Class and Module Definitions . . . Top-Level Execution Environment Inheritance and Visibility . . . . . Freezing Objects . . . . . . . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
362 362 370 376 376 377
IN THE S AFE Safe Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tainted Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
379 380 381
Source Layout . . . . . . . . . . . The Basic Types . . . . . . . . . . Names . . . . . . . . . . . . . . . Variables and Constants . . . . . . Predefined Variables . . . . . Expressions . . . . . . . . . . . . Boolean Expressions . . . . . if and unless Expressions . . case Expressions . . . . . . . Loop Constructs . . . . . . . . Method Definition . . . . . . . . . Invoking a Method . . . . . . . . . Aliasing . . . . . . . . . . . . . . Class Definition . . . . . . . . . . Module Definitions . . . . . . . . Access Control . . . . . . . . . . . Blocks, Closures, and Proc Objects Exceptions . . . . . . . . . . . . . Catch and Throw . . . . . . . . . .
23 D UCK T YPING Classes Aren’t Types . . . . . . . Coding like a Duck . . . . . . . Standard Protocols and Coercions Walk the Walk, Talk the Talk . .
24 C LASSES
25 L OCKING RUBY
26 R EFLECTION , O BJECT S PACE , Looking at Objects . . . . . . . . . Looking at Classes . . . . . . . . . Calling Methods Dynamically . . . System Hooks . . . . . . . . . . . Tracing Your Program’s Execution Marshaling and Distributed Ruby . Compile Time? Runtime? Anytime!
. . . . . . .
. . . . . . .
AND D ISTRIBUTED RUBY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
384 385 386 388 391 393 395 400
PART IV—R UBY L IBRARY R EFERENCE 27 BUILT- IN C LASSES Alphabetical Listing Array . . . . . Bignum . . . . Binding . . . . Class . . . . . Comparable . . Continuation Dir . . . . . . Enumerable . . Errno . . . . . Exception . . FalseClass . . File . . . . . . File::Stat . . FileTest . . . Fixnum . . . . Float . . . . . GC . . . . . . . Hash . . . . . . Integer . . . . IO . . . . . . . Kernel . . . . Marshal . . . . MatchData . . Math . . . . . . Method . . . . Module . . . . NilClass . . . Numeric . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AND M ODULES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
402 403 406 420 423 424 426 427 428 433 439 440 443 444 456 462 463 466 470 471 480 482 495 514 516 519 522 524 540 541
Object . . . . . . ObjectSpace . . . Proc . . . . . . . . Process . . . . . . Process::GID . . Process::Status Process::Sys . . Process::UID . . Range . . . . . . . Regexp . . . . . . Signal . . . . . . String . . . . . . Struct . . . . . . Struct::Tms . . . Symbol . . . . . . Thread . . . . . . ThreadGroup . . . Time . . . . . . . . TrueClass . . . . UnboundMethod . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . .
546 557 559 562 568 570 573 575 576 579 583 585 605 609 610 612 619 621 629 630
. . . . . . . . . . . . . . . . . . . . .
632 634 635 636 637 638 640 641 642 643 644 645 646 647 648 649 650 651 652 654 655 656
28 S TANDARD L IBRARY Abbrev . . . . Base64 . . . . Benchmark . . BigDecimal . . CGI . . . . . . CGI::Session Complex . . . . CSV . . . . . . Curses . . . . Date/DateTime DBM . . . . . . Delegator . . Digest . . . . DL . . . . . . . dRuby . . . . . English . . . . Enumerator . . erb . . . . . . Etc . . . . . . expect . . . . Fcntl . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
FileUtils . . Find . . . . . . Forwardable . ftools . . . . GDBM . . . . . . Generator . . GetoptLong . . GServer . . . . Iconv . . . . . IO/Wait . . . . IPAddr . . . . jcode . . . . . Logger . . . . Mail . . . . . . mathn . . . . . Matrix . . . . Monitor . . . . Mutex . . . . . Mutex_m . . . . Net::FTP . . . Net::HTTP . . Net::IMAP . . Net::POP . . . Net::SMTP . . Net::Telnet . NKF . . . . . . Observable . . open-uri . . . Open3 . . . . . OpenSSL . . . . OpenStruct . . OptionParser ParseDate . . Pathname . . . PP . . . . . . . PrettyPrint . Profile . . . . Profiler_ _ . PStore . . . . PTY . . . . . . Rational . . . readbytes . . Readline . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 673 674 675 676 677 678 680 681 682 683 684 685 686 687 688 689 690 692 693 694 695 696 697 698 699 700 701 702
Resolv . . . . REXML . . . . . Rinda . . . . . RSS . . . . . . Scanf . . . . . SDBM . . . . . . Set . . . . . . Shellwords . . Singleton . . SOAP . . . . . . Socket . . . . StringIO . . . StringScanner Sync . . . . . . Syslog . . . . Tempfile . . . Test::Unit . . thread . . . . ThreadsWait . Time . . . . . . Timeout . . . . Tk . . . . . . . tmpdir . . . . Tracer . . . . TSort . . . . . un . . . . . . . URI . . . . . . WeakRef . . . . WEBrick . . . . Win32API . . . WIN32OLE . . . XMLRPC . . . . YAML . . . . . . Zlib . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
703 704 706 707 708 709 710 711 712 713 714 715 716 717 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738
PART V—A PPENDIXES A S OCKET L IBRARY . . . . . . . . .
740 741 743 747 748 749 750 751 753 754
mkmf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
755 755
BasicSocket Socket . . . IPSocket . . TCPSocket . SOCKSSocket TCPServer . UDPSocket . UNIXSocket . UNIXServer .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
B MKMF R EFERENCE C S UPPORT Web Sites . . . . Download Sites . Usenet Newsgroup Mailing Lists . . .
. . . .
. . . .
. . . .
D B IBLIOGRAPHY
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
758 758 759 759 759 761
I NDEX
762
S UMMARY TABLES
797
List of Tables 2.1 5.1 7.1 11.1 13.1 14.1 15.1 17.1 18.1 21.1 22.1 22.2 22.3 22.4 25.1 27.1 27.2 27.3 27.4 27.5 27.6 27.7 27.8 27.9 27.10 27.11 27.12 27.13 27.14 27.15 28.1 28.2
Example variable and class names . . . . . . . . . . . . Character class abbreviations . . . . . . . . . . . . . . . Common comparison operators . . . . . . . . . . . . . . Two threads in a race condition . . . . . . . . . . . . . . Debugger commands . . . . . . . . . . . . . . . . . . . Environment variables used by Ruby . . . . . . . . . . . irb command-line options . . . . . . . . . . . . . . . . . Version operators . . . . . . . . . . . . . . . . . . . . . Command-line options for erb . . . . . . . . . . . . . . C/Ruby data type conversion functions and macros . . . General delimited input . . . . . . . . . . . . . . . . . . Substitutions in double-quoted strings . . . . . . . . . . Reserved words . . . . . . . . . . . . . . . . . . . . . . Ruby operators (high to low precedence) . . . . . . . . . Definition of the safe levels . . . . . . . . . . . . . . . . Class Array: pack directives . . . . . . . . . . . . . . . Class File: match-mode constants . . . . . . . . . . . . Class File: path separators . . . . . . . . . . . . . . . . Class File: open-mode constants . . . . . . . . . . . . . Class File: lock-mode constants . . . . . . . . . . . . . Class IO: mode strings . . . . . . . . . . . . . . . . . . Module Kernel: sprintf flag characters . . . . . . . . Module Kernel: sprintf field types . . . . . . . . . . . Module Kernel: file tests with a single argument . . . . Module Kernel: file tests with two arguments . . . . . . Class Numeric: methods and subclasses . . . . . . . . . Class Numeric: divmod, modulo, and remainder . . . . Class String: backslash sequences in substitution strings Class String: unpack directives . . . . . . . . . . . . . Class Time: strftime directives . . . . . . . . . . . . . Class ERB: inline directives . . . . . . . . . . . . . . . . Class OptionParser: option definitions . . . . . . . . .
Prepared exclusively for a Pragmatic Client
xvii
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15 68 89 135 165 172 175 206 230 266 304 306 314 324 383 414 447 449 451 455 483 510 511 512 512 543 544 593 603 627 653 691
List of Figures 3.1 4.1 8.1 12.1 12.2 13.1 13.2 16.1 16.2 16.3 16.4 16.5 16.6 16.7 16.8 17.1 18.1 18.2 19.1 21.1 21.2 22.1 24.1 24.2 24.3 24.4 27.1 27.2
Variables hold object references. . . . . . . . . . How arrays are indexed . . . . . . . . . . . . . . Ruby exception hierarchy . . . . . . . . . . . . . Roman numerals generation (with bugs) . . . . . Test::Unit assertions . . . . . . . . . . . . . . . . Sample irb session . . . . . . . . . . . . . . . . . Comparing variable access costs using benchmark Browse RDoc output for class counter . . . . . . Browse RDoc output when source has comments Using ri to read documentation . . . . . . . . . . Document for class Proc generated by RDoc/ri . Ruby source file documented with RDoc . . . . . C source file documented with RDoc . . . . . . . Sample program using RDoc::usage . . . . . . . Help generated by sample program . . . . . . . . MomLog package structure . . . . . . . . . . . . Sample CGI Form . . . . . . . . . . . . . . . . . Erb processing a file with loops . . . . . . . . . . Drawing on a Tk Canvas . . . . . . . . . . . . . Wrapping objects around C data types . . . . . . Building an extension . . . . . . . . . . . . . . . State transitions for boolean range . . . . . . . . A basic object, with its class and superclass . . . Adding a metaclass to Guitar . . . . . . . . . . Adding a virtual class to an object . . . . . . . . An included module and its proxy class . . . . . Standard exception hierarchy . . . . . . . . . . . Method#arity in action . . . . . . . . . . . . .
Prepared exclusively for a Pragmatic Client
xviii
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
39 42 103 145 154 158 163 188 189 190 191 196 198 201 202 220 225 232 248 272 283 327 363 364 367 369 441 523
