Programming Ruby: The Pragmatic Programmer's Guide

# Programming Ruby ### The Pragmatic Programmer's Guide
Previous < | Contents ^ | Next >

# The Ruby Language

This chapter is a bottom-up look at the Ruby language. Unlike the previous tutorial, here we're concentrating on presenting facts, rather than motivating some of the language design features. We also ignore the built-in classes and modules where possible. These are covered in depth starting on page 275.

If the content of this chapter looks familiar, it's because it should; we've covered just about all of this in the earlier tutorial chapters. Consider this chapter to be a self-contained reference to the core Ruby language.

## Source Layout

Ruby programs are written in 7-bit ASCII.[Ruby also has extensive support for Kanji, using the EUC, SJIS, or UTF-8 coding system. If a code set other than 7-bit ASCII is used, the `KCODE` option must be set appropriately, as shown on page 137.]

Ruby is a line-oriented language. Ruby expressions and statements are terminated at the end of a line unless the statement is obviously incomplete---for example if the last token on a line is an operator or comma. A semicolon can be used to separate multiple expressions on a line. You can also put a backslash at the end of a line to continue it onto the next. Comments start with `#' and run to the end of the physical line. Comments are ignored during compilation.

    a = 1

    b = 2; c = 3

    d = 4 + 5 +      # no '\' needed
        6 + 7

    e = 8 + 9   \
        + 10         # '\' needed

Physical lines between a line starting with =begin and{=begin...=end@``{=begin documentation} a line starting with =end are ignored by the compiler and may be used for embedded documentation (see Appendix A, which begins on page 511).

Ruby reads its program input in a single pass, so you can pipe programs to the compiler's `stdin`.

    echo 'print "Hello\n"' | ruby

If the compiler comes across a line anywhere in the source containing just ```__END__`'', with no leading or trailing whitespace, it treats that line as the end of the program---any subsequent lines will not be compiled. However, these lines can be read into the running program using the global `IO` object `DATA`, described on page 217.

### BEGIN and END Blocks

Every Ruby source file can declare blocks of code to be run as the file is being loaded (the `BEGIN` blocks) and after the program has finished executing (the `END` blocks).

    BEGIN {
      begin code
    }

    END {
      end code
    }

A program may include multiple `BEGIN` and `END` blocks. `BEGIN` blocks are executed in the order they are encountered. `END` blocks are executed in reverse order.

### General Delimited Input

There are alternative forms of literal strings, arrays, regular expressions, and shell commands that are specified using a generalized delimited syntax. All these literals start with a percent character, followed by a single character that identifies the literal's type. These characters are summarized in Table 18.1 on page 200; the actual literals are described in the corresponding sections later in this chapter.

General delimited input
Type | Meaning | See Page
`%q` | Single-quoted string | 202
`%Q`, `%` | Double-quoted string | 202
`%w` | Array of tokens | 204
`%r` | Regular expression pattern | 205
`%x` | Shell command | 218

Following the type character is a delimiter, which can be any character. If the delimiter is one of the characters ```(`'', ```[`'', ```{`'', or ```<`'', the literal consists of the characters up to the matching closing delimiter, taking account of nested delimiter pairs. For all other delimiters, the literal comprises the characters up to the next occurrence of the delimiter character.

    %q/this is a string/
    %q-string-
    %q(a (nested) string)

Delimited strings may continue over multiple lines.

    %q{def fred(a)
         a.each { |i| puts i }
       end}

## The Basic Types

The basic types in Ruby are numbers, strings, arrays, hashes, ranges, symbols, and regular expressions.

### Integer and Floating Point Numbers

Ruby integers are objects of class `Fixnum` or `Bignum`. `Fixnum` objects hold integers that fit within the native machine word minus 1 bit. Whenever a `Fixnum` exceeds this range, it is automatically converted to a `Bignum` object, whose range is effectively limited only by available memory. If an operation with a `Bignum` result has a final value that will fit in a `Fixnum`, the result will be returned as a `Fixnum`.

Integers are written using an optional leading sign, an optional base indicator (`0` for octal, `0x` for hex, or `0b` for binary), followed by a string of digits in the appropriate base. Underscore characters are ignored in the digit string.

You can get the integer value corresponding to an ASCII character by preceding that character with a question mark. Control and meta combinations of characters can also be generated using ?\C-x, ?\M-x, and ?\M-\C-x. The control version of `ch` is `ch&0x9f`, and the meta version is `ch | 0x80`. You can get the integer value of a backslash character using the sequence `?\\`.

    123456                    # Fixnum
    123_456                   # Fixnum (underscore ignored)
    -543                      # Negative Fixnum
    123_456_789_123_345_789   # Bignum
    0xaabb                    # Hexadecimal
    0377                      # Octal
    -0b1010                   # Binary (negated)
    0b001_001                 # Binary
    ?a                        # character code
    ?A                        # upper case
    ?\C-a                     # control a = A - 0x40
    ?\C-A                     # case ignored for control chars
    ?\M-a                     # meta sets bit 7
    ?\M-\C-a                  # meta and control a

A numeric literal with a decimal point and/or an exponent is turned into a `Float` object, corresponding to the native architecture's `double` data type. You must follow the decimal point with a digit, as `1.e3` tries to invoke the method `e3` in class `Fixnum`.

`12.34` | » | `12.34`
`-.1234e2` | » | `-12.34`
`1234e-2` | » | `12.34`

### Strings

Ruby provides a number of mechanisms for creating literal strings. Each generates objects of type `String`. The different mechanisms vary in terms of how a string is delimited and how much substitution is done on the literal's content.

Single-quoted string literals (`'` stuff `'` and %q/stuff/) undergo the least substitution. Both convert the sequence
into a single backslash, and the form with single quotes converts \' into a single quote.

`'hello'` | » | `hello`
`'a backslash \'\\\''` | » | `a backslash '\'`
`%q/simple string/` | » | `simple string`
`%q(nesting (really) works)` | » | `nesting (really) works`
`%q no_blanks_here ;` | » | `no_blanks_here`

Double-quoted strings ("stuff", %Q/stuff/, and %/stuff/) undergo additional substitutions, shown in Table 18.2 on page 203.

Substitutions in double-quoted strings

\a | Bell/alert (0x07) | \nnn | Octal nnn
\b | Backspace (0x08) | \xnn | Hex nn
\e | Escape (0x1b) | \cx | Control-x
\f | Formfeed (0x0c) | \C-x | Control-x
\n | Newline (0x0a) | \M-x | Meta-x
\r | Return (0x0d) | \M-\C-x | Meta-control-x
\s | Space (0x20) | \x | x
\t | Tab (0x09) | #{expr} | Value of expr
\v | Vertical tab (0x0b)

`a = 123`
`"\123mile"` | » | `Smile`
`"Say \"Hello\""` | » | `Say "Hello"`
`%Q!"I said 'nuts'," I said!` | » | `"I said 'nuts'," I said`
`%Q{Try #{a + 1}, not #{a - 1}}` | » | `Try 124, not 122`
`%<Try #{a + 1}, not #{a - 1}>` | » | `Try 124, not 122`
`"Try #{a + 1}, not #{a - 1}"` | » | `Try 124, not 122`

Strings can continue across multiple input lines, in which case they will contain newline characters. It is also possible to use here documents to express long string literals. Whenever Ruby parses the sequence <<identifier or <<quoted string, it replaces it with a string literal built from successive logical input lines. It stops building the string when it finds a line that starts with the identifier or the quoted string. You can put a minus sign immediately after the << characters, in which case the terminator can be indented from the left margin. If a quoted string was used to specify the terminator, its quoting rules will be applied to the here document; otherwise, double-quoting rules apply.

    a = 123
    print <<HERE
    Double quoted \
    here document.
    Sum = #{a + 1}
    HERE

    print <<-'THERE'
        This is single quoted.
        The above used #{a + 1}
        THERE

produces:

    Double quoted here document.
    Sum = 124
        This is single quoted.
        The above used #{a + 1}

Adjacent single- and double-quoted strings in the input are concatenated to form a single `String` object.

`'Con' "cat" 'en' "ate"` | » | `"Concatenate"`

Strings are stored as sequences of 8-bit bytes,[For use in Japan, the `jcode` library supports a set of operations of strings written with EUC, SJIS, or UTF-8 encoding. The underlying string, however, is still accessed as a series of bytes.] and each byte may contain any of the 256 8-bit values, including null and newline. The substitution mechanisms in Table 18.2 on page 203 allow nonprinting characters to be inserted conveniently and portably.

Every time a string literal is used in an assignment or as a parameter, a new `String` object is created.

    for i in 1..3
      print 'hello'.id, " "
    end

produces:

    537763324 537763034 537763004

The documentation for class `String` starts on page 363.

### Ranges

Outside the context of a conditional expression, expr `..` expr and expr `...` expr construct `Range` objects. The two-dot form is an inclusive range; the one with three dots is a range that excludes its last element. See the description of class `Range` on page 359 for details. Also see the description of conditional expressions on page 222 for other uses of ranges.

### Arrays

Literals of class `Array` are created by placing a comma-separated series of object references between square brackets. A trailing comma is ignored.

    arr = [ fred, 10, 3.14, "This is a string", barney("pebbles"), ]

Arrays of strings can be constructed using a shortcut notation, `%w`, which extracts space-separated tokens into successive elements of the array. A space can be escaped with a backslash. This is a form of general delimited input, described on pages 200--201.

`arr = %w( fred wilma barney betty great\ gazoo )`
`arr` | » | `["fred", "wilma", "barney", "betty", "great gazoo"]`

### Hashes

A literal Ruby `Hash` is created by placing a list of key/value pairs between braces, with either a comma or the sequence `=>` between the key and the value. A trailing comma is ignored.

    colors = { "red"   => 0xf00,
               "green" => 0x0f0,
               "blue"  => 0x00f
             }

There is no requirement for the keys and/or values in a particular hash to have the same type.

### Requirements for a Hash Key

The only restriction for a hash key is that it must respond to the message `hash` with a hash value, and the hash value for a given key must not change. This means that certain classes (such as `Array` and `Hash`, as of this writing) can't conveniently be used as keys, because their hash values can change based on their contents.

If you keep an external reference to an object that is used as a key, and use that reference to alter the object and change its hash value, the hash lookup based on that key may not work.

Because strings are the most frequently used keys, and because string contents are often changed, Ruby treats string keys specially. If you use a `String` object as a hash key, the hash will duplicate the string internally and will use that copy as its key. Any changes subsequently made to the original string will not affect the hash.

If you write your own classes and use instances of them as hash keys, you need to make sure that either (a) the hashes of the key objects don't change once the objects have been created or (b) you remember to call the `Hash#rehash` method to reindex the hash whenever a key hash is changed.

### Symbols

A Ruby symbol is the internal representation of a name. You construct the symbol for a name by preceding the name with a colon. A particular name will always generate the same symbol, regardless of how that name is used within the program.

    :Object
    :myVariable

Other languages call this process ``interning,'' and call symbols ``atoms.''

### Regular Expressions

Regular expression literals are objects of type `Regexp`. They can be created by explicitly calling the `Regexp.new` constructor, or by using the literal forms, /pattern/ and `%r{` pattern `}`. The `%r` construct is a form of general delimited input (described on pages 200--201).

    /pattern/
    /pattern/options
    %r{pattern}
    %r{pattern}options
    Regexp.new( 'pattern' [, options
                ] )

### Regular Expression Options

A regular expression may include one or more options that modify the way the pattern matches strings. If you're using literals to create the `Regexp` object, then the options comprise one or more characters placed immediately after the terminator. If you're using `Regexp.new`, the options are constants used as the second parameter of the constructor.

`i` | Case Insensitive. The pattern match will ignore the case of letters in the pattern and string. Matches are also case-insensitive if the global variable `$=` is set.
`o` | Substitute Once. Any `#{...}` substitutions in a particular regular expression literal will be performed just once, the first time it is evaluated. Otherwise, the substitutions will be performed every time the literal generates a `Regexp` object.
`m` | Multiline Mode. Normally, ``.'' matches any character except a newline. With the `/m` option, ``.'' matches any character.
`x` | Extended Mode. Complex regular expressions can be difficult to read. The `x' option allows you to insert spaces, newlines, and comments in the pattern to make it more readable.

### Regular Expression Patterns

regular characters
  All characters except ., |, (, ), [, \, ^, {, +, $, *, and ? match themselves. To match one of these characters, precede it with a backslash.

`^`
  Matches the beginning of a line.

`$`
  Matches the end of a line.

`\A`
  Matches the beginning of the string.

`\z`
  Matches the end of the string.

`\Z`
  Matches the end of the string unless the string ends with a ``\n'', in which case it matches just before the ``\n''.

`\b`, `\B`
  Match word boundaries and nonword boundaries respectively.

`[` characters `]`
  A character class matches any single character between the brackets. The characters `|, (, ), [, ^, $, *,` and `?`, which have special meanings elsewhere in patterns, lose their special significance between brackets. The sequences `\` nnn, `\x` nn, `\c` x, `\C-` x, `\M-` x, and `\M-\C-` x have the meanings shown in Table 18.2 on page 203. The sequences `\d`, `\D`, `\s`, `\S`, `\w`, and `\W` are abbreviations for groups of characters, as shown in Table 5.1 on page 59. The sequence c1-c2 represents all the characters between c1 and c2, inclusive. Literal `]` or `-` characters must appear immediately after the opening bracket. An uparrow (^) immediately following the opening bracket negates the sense of the match---the pattern matches any character that isn't in the character class.

`\d`, `\s`, `\w`
  Are abbreviations for character classes that match digits, whitespace, and word characters, respectively. \D, \S, and \W match characters that are not digits, whitespace, or word characters. These abbreviations are summarized in Table 5.1 on page 59.

`.` (period)
  Appearing outside brackets, matches any character except a newline. (With the `/m` option, it matches newline, too).

re `*`
  Matches zero or more occurrences of re.

re `+`
  Matches one or more occurrences of re.

re `{m,n}`
  Matches at least ``m'' and at most ``n'' occurrences of re.

re `?`
  Matches zero or one occurrence of re. The `*`, `+`, and `{m,n}` modifiers are greedy by default. Append a question mark to make them minimal.

re1 `|` re2
  Matches either re1 or re2. `|` has a low precedence.

`(...)`
  Parentheses are used to group regular expressions. For example, the pattern `/abc+/` matches a string containing an ``a,'' a ``b,'' and one or more ``c''s. `/(abc)+/` matches one or more sequences of ``abc''. Parentheses are also used to collect the results of pattern matching. For each opening parenthesis, Ruby stores the result of the partial match between it and the corresponding closing parenthesis as successive groups. Within the same pattern, `\1` refers to the match of the first group, `\2` the second group, and so on. Outside the pattern, the special variables `$1`, `$2`, and so on, serve the same purpose.

### Substitutions

`#{...}`
  Performs an expression substitution, as with strings. By default, the substitution is performed each time a regular expression literal is evaluated. With the `/o` option, it is performed just the first time.

`\0, \1, \2, ... \9, \&, \`, \', \+`
  Substitutes the value matched by the nth grouped subexpression, or by the entire match, pre- or postmatch, or the highest group.

### Extensions

In common with Perl and Python, Ruby regular expressions offer some extensions over traditional Unix regular expressions. All the extensions are entered between the characters `(?` and `)`. The parentheses that bracket these extensions are groups, but they do not generate backreferences: they do not set the values of `\1` and `$1` etc.

`(?# comment)`
  Inserts a comment into the pattern. The content is ignored during pattern matching.

`(?:re)`
  Makes re into a group without generating backreferences. This is often useful when you need to group a set of constructs but don't want the group to set the value of `$1` or whatever. In the example that follows, both patterns match a date with either colons or spaces between the month, day, and year. The first form stores the separator character in `$2` and `$4`, while the second pattern doesn't store the separator in an external variable.

  `date = "12/25/01"`
  `date =~ %r{(\d+)(/|:)(\d+)(/|:)(\d+)}`
  `[$1,$2,$3,$4,$5]` | » | `["12", "/", "25", "/", "01"]`
  `date =~ %r{(\d+)(?:/|:)(\d+)(?:/|:)(\d+)}`
  `[$1,$2,$3]` | » | `["12", "25", "01"]`

`(?=re)`
  Matches re at this point, but does not consume it (also known charmingly as ``zero-width positive lookahead''). This lets you look forward for the context of a match without affecting `$&`. In this example, the `scan` method matches words followed by a comma, but the commas are not included in the result.

  `str = "red, white, and blue"`
  `str.scan(/[a-z]+(?=,)/)` | » | `["red", "white"]`

`(?!re)`
  Matches if re does not match at this point. Does not consume the match (zero-width negative lookahead). For example, `/hot(?!dog)(\w+)/` matches any word that contains the letters ``hot'' that aren't followed by ``dog'', returning the end of the word in `$1`.

`(?>re)`
  Nests an independent regular expression within the first regular expression. This expression is anchored at the current match position. If it consumes characters, these will no longer be available to the higher-level regular expression. This construct therefore inhibits backtracking, which can be a performance enhancement. For example, the pattern `/a.*b.*a/` takes exponential time when matched against a string containing an ``a'' followed by a number of ``b''s, but with no trailing ``a.'' However, this can be avoided by using a nested regular expression `/a(?>.*b).*a/`. In this form, the nested expression consumes all the the input string up to the last possible ``b'' character. When the check for a trailing ``a'' then fails, there is no need to backtrack, and the pattern match fails promptly.

      require "benchmark"
      include Benchmark
      str = "a" + ("b" * 5000)
      bm(8) do |test|
        test.report("Normal:") { str =~ /a.*b.*a/ }
        test.report("Nested:") { str =~ /a(?>.*b).*a/ }
      end

  produces:

                    user     system      total        real
      Normal:   4.170000   0.000000   4.170000 (  4.150970)
      Nested:   0.000000   0.000000   0.000000 (  0.001529)

`(?imx)`
  Turns on the corresponding ``i,'' ``m,'' or ``x'' option. If used inside a group, the effect is limited to that group.

`(?-imx)`
  Turns off the ``i,'' ``m,'' or ``x'' option.

`(?imx:re)`
  Turns on the ``i,'' ``m,'' or ``x'' option for re.

`(?-imx:re)`
  Turns off the ``i,'' ``m,'' or ``x'' option for re.

## Names

Ruby names are used to refer to constants, variables, methods, classes, and modules. The first character of a name helps Ruby to distinguish its intended use. Certain names, listed in Table 18.3 on page 210, are reserved words and should not be used as variable, method, class, or module names.

Reserved words

__FILE__ | and | def | end | in | or | self | unless
__LINE__ | begin | defined? | ensure | module | redo | super | until
BEGIN | break | do | false | next | rescue | then | when
END | case | else | for | nil | retry | true | while
alias | class | elsif | if | not | return | undef | yield

In these descriptions, lowercase letter means the characters ``a'' though ``z'', as well as ``_'', the underscore. Uppercase letter means ``A'' though ``Z,'' and digit means ``0'' through ``9.'' Name characters means any combination of upper- and lowercase letters and digits.

A local variable name consists of a lowercase letter followed by name characters.

    fred  anObject  _x  three_two_one

An instance variable name starts with an ``at'' sign (```@`'') followed by an upper- or lowercase letter, optionally followed by name characters.

    @name  @_  @Size

A class variable name starts with two ``at'' signs (```@@`'') followed by an upper- or lowercase letter, optionally followed by name characters.

    @@name  @@_  @@Size

A constant name starts with an uppercase letter followed by name characters. Class names and module names are constants, and follow the constant naming conventions. By convention, constant variables are normally spelled using uppercase letters and underscores throughout.

    module Math
      PI = 3.1415926
    end
    class BigBlob

Global variables, and some special system variables, start with a dollar sign (```$`'') followed by name characters. In addition, there is a set of two-character variable names in which the second character is a punctuation character. These predefined variables are listed starting on page 213. Finally, a global variable name can be formed using ```$-`'' followed by any single character.

    $params  $PROGRAM  $!  $_  $-a  $-.

Method names are described in the section beginning on page 225.

### Variable/Method Ambiguity

When Ruby sees a name such as ``a'' in an expression, it needs to determine if it is a local variable reference or a call to a method with no parameters. To decide which is the case, Ruby uses a heuristic. As Ruby reads a source file, it keeps track of symbols that have been assigned to. It assumes that these symbols are variables. When it subsequently comes across a symbol that might be either a variable or a method call, it checks to see if it has seen a prior assignment to that symbol. If so, it treats the symbol as a variable; otherwise it treats it as a method call. As a somewhat pathological case of this, consider the following code fragment, submitted by Clemens Hintze.

    def a
      print "Function 'a' called\n"
      99
    end

    for i in 1..2
      if i == 2
        print "a=", a, "\n"
      else
        a = 1
        print "a=", a, "\n"
      end
    end

produces:

    a=1
    Function 'a' called
    a=99

During the parse, Ruby sees the use of ``a'' in the first print statement and, as it hasn't yet seen any assignment to ``a,'' assumes that it is a method call. By the time it gets to the second print statement, though, it has seen an assignment, and so treats ``a'' as a variable.

Note that the assignment does not have to be executed---Ruby just has to have seen it. This program does not raise an error.

    a = 1 if false; a

## Variables and Constants

Ruby variables and constants hold references to objects. Variables themselves do not have an intrinsic type. Instead, the type of a variable is defined solely by the messages to which the object referenced by the variable responds.[When we say that a variable is not typed, we mean that any given variable can at different times hold references to objects of many different types.]

A Ruby constant is also a reference to an object. Constants are created when they are first assigned to (normally in a class or module definition). Ruby, unlike less flexible languages, lets you alter the value of a constant, although this will generate a warning message.

    MY_CONST = 1
    MY_CONST = 2   # generates a warning

produces:

    prog.rb:2: warning: already initialized constant MY_CONST

Note that although constants should not be changed, you can alter the internal states of the objects they reference.

`MY_CONST = "Tim"`
`MY_CONST[0] = "J" # alter string referenced by constant`
`MY_CONST` | » | `"Jim"`

Assignment potentially aliases objects, giving the same object different names.

### Scope of Constants and Variables

Constants defined within a class or module may be accessed unadorned anywhere within the class or module. Outside the class or module, they may be accessed using the scope operator, ```::`'' prefixed by an expression that returns the appropriate class or module object. Constants defined outside any class or module may be accessed unadorned or by using the scope operator ```::`'' with no prefix. Constants may not be defined in methods.

`OUTER_CONST = 99`
`class Const`
`def getConst`
`CONST`
`end`
`CONST = OUTER_CONST + 1`
`end`
`Const.new.getConst` | » | `100`
`Const::CONST` | » | `100`
`::OUTER_CONST` | » | `99`

Global variables are available throughout a program. Every reference to a particular global name returns the same object. Referencing an uninitialized global variable returns `nil`.

Class variables are available throughout a class or module body. Class variables must be initialized before use. A class variable is shared among all instances of a class and is available within the class itself.

    class Song
      @@count = 0
      def initialize
        @@count += 1
      end
      def Song.getCount
        @@count
      end
    end

Class variables belong to the innermost enclosing class or module. Class variables used at the top level are defined in `Object`, and behave like global variables. Class variables defined within singleton methods belong to the receiver if the receiver is a class or a module; otherwise, they belong to the class of the receiver.

    class Holder
      @@var = 99
      def Holder.var=(val)
        @@var = val
      end
    end

    a = Holder.new
    def a.var
      @@var
    end

`Holder.var = 123`
`a.var` | » | `123`

Instance variables are available within instance methods throughout a class body. Referencing an uninitialized instance variable returns `nil`. Each instance of a class has a unique set of instance variables. Instance variables are not available to class methods.

Local variables are unique in that their scopes are statically determined but their existence is established dynamically.

A local variable is created dynamically when it is first assigned a value during program execution. However, the scope of a local variable is statically determined to be: the immediately enclosing block, method definition, class definition, module definition, or top-level program. Referencing a local variable that is in scope but that has not yet been created generates a `NameError` exception.

Local variables with the same name are different variables if they appear in disjoint scopes.

Method parameters are considered to be variables local to that method.

Block parameters are assigned values when the block is invoked.

    a = [ 1, 2, 3 ]
    a.each { |i|  puts i  }  # i local to block
    a.each { |$i| puts $i }  # assigns to global $i
    a.each { |@i| puts @i }  # assigns to instance variable @i
    a.each { |I|  puts I  }  # generates warning assigning to constant
    a.each { |b.meth| }      # invokes meth= in object b
    sum = 0
    var = nil
    a.each { |var| sum += var }  # uses sum and var from enclosing scope

If a local variable (including a block parameter) is first assigned in a block, it is local to the block. If instead a variable of the same name is already established at the time the block executes, the block will inherit that variable.

A block takes on the set of local variables in existence at the time that it is created. This forms part of its binding. Note that although the binding of the variables is fixed at this point, the block will have access to the current values of these variables when it executes. The binding preserves these variables even if the original enclosing scope is destroyed.

The bodies of `while`, `until`, and `for` loops are part of the scope that contains them; previously existing locals can be used in the loop, and any new locals created will be available outside the bodies afterward.

### Predefined Variables

Predefined Variables

The following variables are predefined in the Ruby interpreter. In these descriptions, the notation {} indicates that the variables are read-only; an error will be raised if a program attempts to modify a read-only variable. After all, you probably don't want to change the meaning of `true` halfway through your program (except perhaps if you're a politician). Entries marked {} are thread local.

Many global variables look something like Snoopy swearing: `$_`, `$!`, `$&`, and so on. This is for ``historical'' reasons, as most of these variable names come from Perl. If you find memorizing all this punctuation difficult, you might want to have a look at the library file called ``English,'' documented on page 445, which gives the commonly used global variables more descriptive names.

In the tables of variables and constants that follow, we show the variable name, the type of the referenced object, and a description.

### Exception Information

$! | Exception | The exception object passed to `raise`. {}

$@ | Array | The stack backtrace generated by the last exception. See `Kernel#caller` on page 413 for details. {}

### Pattern Matching Variables

These variables (except `$=`) are set to `nil` after an unsuccessful pattern match.

$& | String | The string matched by the last successful pattern match. This variable is local to the current scope. {}

$+ | String | The contents of the highest-numbered group matched in the last successful pattern match. Thus, in `"cat" =~/(c|a)(t|z)/`, `$+` will be set to ``t''. This variable is local to the current scope. {}

$` | String | The string preceding the match in the last successful pattern match. This variable is local to the current scope. {}

$' | String | The string following the match in the last successful pattern match. This variable is local to the current scope. {}

$= | Object | If set to any value apart from `nil` or `false`, all pattern matches will be case insensitive, string comparisons will ignore case, and string hash values will be case insensitive.

$1 to $9 | String | The contents of successive groups matched in the last successful pattern match. In `"cat" =~/(c|a)(t|z)/`, `$1` will be set to ``a'' and `$2` to ``t''. This variable is local to the current scope. {}

$~ | MatchData | An object that encapsulates the results of a successful pattern match. The variables `$&`, `$``, `$'`, and `$1` to `$9` are all derived from `$~`. Assigning to `$~` changes the values of these derived variables. This variable is local to the current scope. {}

### Input/Output Variables

$/ | String | The input record separator (newline by default). This is the value that routines such as `Kernel#gets` use to determine record boundaries. If set to `nil`, `gets` will read the entire file.

$-0 | String | Synonym for `$/`.

$\ | String | The string appended to the output of every call to methods such as `Kernel#print` and `IO#write` . The default value is `nil`.

$, | String | The separator string output between the parameters to methods such as `Kernel#print` and `Array#join` . Defaults to `nil`, which adds no text.

$. | Fixnum | The number of the last line read from the current input file.

$; | String | The default separator pattern used by `String#split` . May be set from the command line using the `-F` flag.

$< | Object | An object that provides access to the concatenation of the contents of all the files given as command-line arguments, or `$stdin` (in the case where there are no arguments). `$<` supports methods similar to a `File` object: `binmode`, `close`, `closed?`, `each`, `each_byte`, `each_line`, `eof`, `eof?`, `file`, `filename`, `fileno`, `getc`, `gets`, `lineno`, `lineno=`, `pos`, `pos=`, `read`, `readchar`, `readline`, `readlines`, `rewind`, `seek`, `skip`, `tell`, `to_a`, `to_i`, `to_io`, `to_s`, along with the methods in `Enumerable`. The method `file` returns a `File` object for the file currently being read. This may change as `$<` reads through the files on the command line. {}

$> | IO | The destination of output for `Kernel#print` and `Kernel#printf` . The default value is `$stdout`.

$_ | String | The last line read by `Kernel#gets` or `Kernel#readline` . Many string-related functions in the `Kernel` module operate on `$_` by default. The variable is local to the current scope. {}

$defout | IO | Synonym for `$>`.

$-F | String | Synonym for `$;`.

$stderr | IO | The current standard error output.

$stdin | IO | The current standard input.

$stdout | IO | The current standard output.

### Execution Environment Variables

$0 | String | The name of the top-level Ruby program being executed. Typically this will be the program's filename. On some operating systems, assigning to this variable will change the name of the process reported (for example) by the `ps(1)` command.

$* | Array | An array of strings containing the command-line options from the invocation of the program. Options used by the Ruby interpreter will have been removed. {}

$" | Array | An array containing the filenames of modules loaded by `require`. {}

$$ | Fixnum | The process number of the program being executed. {}

$? | Fixnum | The exit status of the last child process to terminate. {}

$: | Array | An array of strings, where each string specifies a directory to be searched for Ruby scripts and binary extensions used by the `load` and `require` methods. The initial value is the value of the arguments passed via the `-I` command-line option, followed by an installation-defined standard library location, followed by the current directory (``.''). This variable may be set from within a program to alter the default search path; typically, programs use `$: << dir` to append `dir` to the path. {}

$-a | Object | True if the `-a` option is specified on the command line. {}

$-d | Object | Synonym for `$DEBUG`.

$DEBUG | Object | Set to `true` if the `-d` command-line option is specified.

__FILE__ | String | The name of the current source file. {}

$F | Array | The array that receives the split input line if the `-a` command-line option is used.

$FILENAME | String | The name of the current input file. Equivalent to `$<.filename`. {}

$-i | String | If in-place edit mode is enabled (perhaps using the `-i` command-line option), `$-i` holds the extension used when creating the backup file. If you set a value into `$-i`, enables in-place edit mode. See page 136.

$-I | Array | Synonym for `$:`. {}

$-K | String | Sets the multibyte coding system for strings and regular expressions. Equivalent to the `-K` command-line option. See page 137.

$-l | Object | Set to `true` if the `-l` option (which enables line-end processing) is present on the command line. See page 137. {}

__LINE__ | String | The current line number in the source file. {}

$LOAD_PATH | Array | A synonym for `$:`. {}

$-p | Object | Set to `true` if the `-p` option (which puts an implicit `while gets` ... `end` loop around your program) is present on the command line. See page 137. {}

$SAFE | Fixnum | The current safe level (see page 254). This variable's value may never be reduced by assignment. {}

$VERBOSE | Object | Set to `true` if the `-v`, `--version`, or `-w` option is specified on the command line. Setting this option to `true` causes the interpreter and some library routines to report additional information.

$-v | Object | Synonym for `$VERBOSE`.

$-w | Object | Synonym for `$VERBOSE`.

### Standard Objects

ARGF | Object | A synonym for `$<`.

ARGV | Array | A synonym for `$*`.

ENV | Object | A hash-like object containing the program's environment variables. An instance of class `Object`, `ENV` implements the full set of `Hash` methods. Used to query and set the value of an environment variable, as in `ENV["PATH"]` and `ENV['term']="ansi"`.

false | FalseClass | Singleton instance of class `FalseClass`. {}

nil | NilClass | The singleton instance of class `NilClass`. The value of uninitialized instance and global variables. {}

self | Object | The receiver (object) of the current method. {}

true | TrueClass | Singleton instance of class `TrueClass`. {}

### Global Constants

The following constants are defined by the Ruby interpreter.

DATA | IO | If the the main program file contains the directive `__END__`, then the constant `DATA` will be initialized so that reading from it will return lines following `__END__` from the source file.

FALSE | FalseClass | Synonym for `false`.

NIL | NilClass | Synonym for `nil`.

RUBY_PLATFORM | String | The identifier of the platform running this program. This string is in the same form as the platform identifier used by the GNU configure utility (which is not a coincidence).

RUBY_RELEASE_DATE | String | The date of this release.

RUBY_VERSION | String | The version number of the interpreter.

STDERR | IO | The actual standard error stream for the program. The initial value of `$stderr`.

STDIN | IO | The actual standard input stream for the program. The initial value of `$stdin`.

STDOUT | IO | The actual standard output stream for the program. The initial value of `$stdout`.

TOPLEVEL_BINDING | Binding | A `Binding` object representing the binding at Ruby's top level---the level where programs are initially executed.

TRUE | TrueClass | Synonym for `true`.

## Expressions

### Single Terms

Single terms in an expression may be any of the following.

- Literal. Ruby literals are numbers, strings, arrays, hashes, ranges, symbols, and regular expressions. There are described starting on page 201.

- Shell Command. A shell command is a string enclosed in backquotes, or in a general delimited string (page 200) starting with `%x`. The value of the string is the standard output of running the command represented by the string under the host operating system's standard shell. The execution also sets the `$?` variable with the command's exit status.

      filter = "*.c"
      files = `ls #{filter}`
      files = %x{ls #{filter}}

- Symbol Generator. A `Symbol` object is created by prefixing an operator, variable, constant, method, class, or module name with a colon. The symbol object will be unique for each different name but does not refer to a particular instance of the name, so the symbol for (say) `:fred` will be the same regardless of context. A symbol is similar to the concept of atoms in other high-level languages.

- Variable Reference or Constant Reference. A variable is referenced by citing its name. Depending on scope (see page 211), a constant is referenced either by citing its name or by qualifying the name, using the name of the class or module containing the constant and the scope operator (```::`'').

      barney    # variable reference
      APP_NAMR  # constant reference
      Math::PI  # qualified constant reference

- Method Invocation. The various ways of invoking a method are described starting on page 227.

### Operator Expressions

Ruby operators (high to low precedence)
Method | Operator | Description
Y | `[ ]` 0`[ ]=` | Element reference, element set
Y | `**` | Exponentiation
Y | `!` 0`~` 0`+` 0`--` | Not, complement, unary plus and minus (method names for the last two are `+@` and `-@`)
Y | `*` 0`/` 0`%` | Multiply, divide, and modulo
Y | `+` 0`--` | Plus and minus
Y | `>>` 0`<<` | Right and left shift
Y | `&` | Bitwise `and'
Y | `^` 0`|` | Bitwise exclusive `or' and regular `or'
Y | `<=` 0`<` 0`>` 0`>=` | Comparison operators
Y | `<=>` 0`==` 0`===` 0`!=` 0`=~` 0`!~` | Equality and pattern match operators (`!=` and `!~` may not be defined as methods)
| `&&` | Logical `and'
| `||` | Logical `or'
| `..` 0`...` | Range (inclusive and exclusive)
| `? :` | Ternary if-then-else
| `=` 0`%=` 0``{ `/=` 0`--=` 0`+=` 0`|=` `&=` 0`>>=` 0`<<=` 0`*=` 0`&&=` 0`||=` 0`**=` | Assignment
| `defined?` | Check if symbol defined
| `not` | Logical negation
| `or` 0`and` | Logical composition
| `if` 0`unless` 0`while` 0`until` | Expression modifiers
| `begin/end` | Block expression

Expressions may be combined using operators. Table 18.4 on page 219 lists the Ruby operators in precedence order. The operators with a Y in the method column are implemented as methods, and may be overridden.

### More on Assignment

The assignment operator assigns one or more rvalues to one or more lvalues. What is meant by assignment depends on each individual lvalue.

If an lvalue is a variable or constant name, that variable or constant receives a reference to the corresponding rvalue.

    a, b, c = 1, "cat", [ 3, 4, 5 ]

If the lvalue is an object attribute, the corresponding attribute setting method will be called in the receiver, passing as a parameter the rvalue.

    anObj = A.new
    anObj.value = "hello"   # equivalent to anObj.value=("hello")

If the lvalue is an array element reference, Ruby calls the element assignment operator (```[]=`'') in the receiver, passing as parameters any indices that appear between the brackets followed by the rvalue. This is illustrated in Table 18.5 on page 220.

Mapping from element reference to method call
Element Reference | Actual Method Call
`anObj[] = "one"` | `anObj.[]=("one")`
`anObj[1] = "two"` | `anObj.[]=(1, "two")`
`anObj["a", /^cat/] = "three"` | `anObj.[]=("a", /^cat/, "three")`

### Parallel Assignment

An assignment expression may have one or more lvalues and one or more rvalues. This section explains how Ruby handles assignment with different combinations of arguments.

1. If the last rvalue is prefixed with an asterisk and is an object of class `Array`, the rvalue is replaced with the elements of the array, with each element forming its own rvalue.
2. If the assignment contains multiple lvalues and one rvalue, the rvalue is converted into an `Array`, and this array is expanded into a set of rvalues as described in (1).
3. Successive rvalues are assigned to the lvalues. This assignment effectively happens in parallel, so that (for example) `a,b=b,a` swaps the values in ``a'' and ``b.''
4. If there are more lvalues than rvalues, the excess will have `nil` assigned to them.
5. If there are more rvalues that lvalues, the excess will be ignored.
6. These rules are modified slightly if the last lvalue is preceded with an asterisk. This lvalue will always receive an array during the assignment. The array will consist of whatever rvalue would normally have been assigned to this lvalue, followed by the excess rvalues (if any).
7. If an lvalue is a parenthesized list, it is treated as a nested assignment statement, and the list is assigned from the corresponding rvalue as described by these rules.

The tutorial has examples starting on page 75.

### Block Expressions

    begin
      body
    end

Expressions may be grouped between `begin` and `end`. The value of the block expression is the value of the last expression executed.

Block expressions also play a role in exception handling, which is discussed starting on page 235.

### Boolean Expressions

Boolean Expressions

Boolean expressions evaluate to a truth value. Some Ruby constructs (particularly ranges) behave differently when evaluated in a boolean expression.

### Truth Values

Ruby predefines the globals `false` and `nil`. Both of these values are treated as being false in a boolean context. All other values are treated as being true.

### And, Or, Not, and Defined?

The `and` and `&&` operators evaluate their first operand. If false, the expression returns false; otherwise, the expression returns the value of the second operand.

    expr1  and  expr2
    expr1  &&   expr2

The `or` and `||` operators evaluate their first operand. If true, the expression returns true; otherwise, the expression returns the value of the second operand.

    expr1  or  expr2
    expr1  ||  expr2

The `not` and `!` operators evaluate their operand. If true, the expression returns false. If false, the expression returns true.

The word forms of these operators (`and`, `or`, and `not`) have a lower precedence than the corresponding symbol forms (`&&`, `||`, and `!`). See Table 18.4 on page 219 for details.

The `defined?` operator returns `nil` if its argument, which can be an arbitrary expression, is not defined. Otherwise, it returns a description of that argument. For examples, see page 78 in the tutorial.

### Comparison Operators

The Ruby syntax defines the comparison operators `==`, `===`, `<=>`, `<`, `<=`, `>`, `>=`, `=~`, and the standard methods `eql?` and `equal?` (see Table 7.1 on page 79). All of these operators are implemented as methods. Although the operators have intuitive meaning, it is up to the classes that implement them to produce meaningful comparison semantics. The library reference starting on page 275 describes the comparison semantics for the built-in classes. The module `Comparable` provides support for implementing the operators `==`, `<`, `<=`, `>`, `>=`, and the method `between?` in terms of `<=>`. The operator `===` is used in `case` expressions, described on page 223.

Both `==` and `=~` have negated forms, `!=` and `!~`. Ruby converts these during syntax analysis: `a!=b` is mapped to `!(a==b)`, and `a!~b` is mapped to `!(a =~b)`. There are no methods corresponding to `!=` and `!~`.

### Ranges in Boolean Expressions

    if  expr1 .. expr2
    while  expr1 ... expr2

A range used in a boolean expression acts as a flip-flop. It has two states, set and unset, and is initially unset. On each call, the range cycles through the state machine shown in Figure 18.1 on page 223. The range returns `true` if it is in the set state at the end of the call, and `false` otherwise.

The two-dot form of a range behaves slightly differently than the three-dot form. When the two-dot form first makes the transition from unset to set, it immediately evaluates the end condition and makes the transition accordingly. This means that if expr1 and expr2 both evaluate to `true` on the same call, the two-dot form will finish the call in the unset state. However, it still returns `true` for this call.

The difference is illustrated by the following code:

`a = (11..20).collect {|i| (i%4 == 0)..(i%3 == 0) ? i : nil}`
`a` | » | `[nil, 12, nil, nil, nil, 16, 17, 18, nil, 20]`
``
`a = (11..20).collect {|i| (i%4 == 0)...(i%3 == 0) ? i : nil}`
`a` | » | `[nil, 12, 13, 14, 15, 16, 17, 18, nil, 20]`

Figure not available...

### Regular Expressions in Boolean Expressions

If a single regular expression appears as a boolean expression, it is matched against the current value of the variable `$_`.

    if /re/ ...

is equivalent to

    if $_ =~ /re/ ...

### If and Unless Expressions

`if` and `unless` Expressions

    if boolean-expression [then]
      body
    elsif boolean-expression [then]
      body
    else
      body
    end

    unless boolean-expression [then]
      body
    else
      body
    end

The `then` keyword separates the body from the condition. It is not required if the body starts on a new line. The value of an `if` or `unless` expression is the value of the last expression evaluated in whichever body is executed.

### If and Unless Modifiers

    expression if     boolean-expression
    expression unless boolean-expression

evaluates expression only if boolean-expression is `true` (`false` for `unless`).

### Ternary Operator

    boolean-expression ? expr1 : expr2

returns expr1 if boolean expression is true and expr2 otherwise.

### Case Expressions

`case` Expressions

    case target
      when [
                comparison
                ]+
                 [then]
        body
      when [
                comparison
                ]+
                 [then]
        body
      ...
    [ else
        body ]
     end

A case expression searches for a match by starting at the first (top left) comparison, performing comparison `===` target. When a comparison returns true, the search stops, and the body associated with the comparison is executed. `case` then returns the value of the last expression executed. If no comparison matches: if an `else` clause is present, its body will be executed; otherwise, `case` silently returns `nil`.

The `then` keyword separates the `when` comparisons from the bodies, and is not needed if the body starts on a new line.

### Loops

Loop Constructs

    while boolean-expression [do]
      body
    end

executes body zero or more times as long as boolean-expression is true.

    until boolean-expression [do]
      body
    end

executes body zero or more times as long as boolean-expression is false.

In both forms, the `do` separates boolean-expression from the body, and may be omitted when the body starts on a new line.

    for [
                name
                ]+
                 in expression [do]
      body
    end

The `for` loop is executed as if it were the following `each` loop, except that local variables defined in the body of the `for` loop will be available outside the loop, while those defined within an iterator block will not.

    expression.each do | [
                name
                ]+
                 |
      body
    end

`loop`, which iterates its associated block, is not a language construct---it is a method in module `Kernel`.

### While and Until Modifiers

    expression while boolean-expression
    expression until boolean-expression

If expression is anything other than a `begin/end` block, executes expression zero or more times while boolean-expression is `true` (`false` for `until`).

If expression is a `begin/end` block, the block will always be executed at least one time.

### Break, Redo, Next, and Retry

`break`, `redo`, `next`, and `retry` alter the normal flow through a `while`, `until`, `for`, or iterator controlled loop.

`break` terminates the immediately enclosing loop---control resumes at the statement following the block. `redo` repeats the loop from the start, but without reevaluating the condition or fetching the next element (in an iterator). `next` skips to the end of the loop, effectively starting the next iteration. `retry` restarts the loop, reevaluating the condition.

## Method Definition

      def defname [( [
                arg [=val
                ]
                ]*
                 [, *vararg
                ] [, &blockarg
                ] )]
        body
      end

defname is both the name of the method and optionally the context in which it is valid.

    defname
                     <-
                     methodname

                     expr.methodname

A methodname is either a redefinable operator (see Table 18.4 on page 219) or a name. If methodname is a name, it should start with a lowercase letter (or underscore) optionally followed by upper- and lowercase letters, underscores, and digits. A methodname may optionally end with a question mark (```?`''), exclamation point (```!`''), or equals sign (```=`''). The question mark and exclamation point are simply part of the name. The equals sign is also part of the name but additionally signals that this method is an attribute setter (described on page 23).

A method definition using an unadorned method name within a class or module definition creates an instance method. An instance method may be invoked only by sending its name to a receiver that is an instance of the class that defined it (or one of that class's subclasses).

Outside a class or module definition, a definition with an unadorned method name is added as a private method to class `Object`, and hence may be called in any context without an explicit receiver.

A definition using a method name of the form expr.methodname creates a method associated with the object that is the value of the expression; the method will be callable only by supplying the object referenced by the expression as a receiver. Other Ruby documentation calls these methods singleton methods.

    class MyClass
      def MyClass.method      # definition
      end
    end

    MyClass.method            # call

    anObject = Object.new
    def anObject.method       # definition
    end
    anObject.method           # call

    def (1.class).fred        # receiver may be an expression
    end
    Fixnum.fred               # call

Method definitions may not contain class, module, or instance method definitions. They may contain nested singleton method definitions. The body of a method acts as if it were a `begin`/`end` block, in that it may contain exception handling statements (`rescue`, `else`, and `ensure`).

### Method Arguments

A method definition may have zero or more regular arguments, an optional array argument, and an optional block argument. Arguments are separated by commas, and the argument list may be enclosed in parentheses.

A regular argument is a local variable name, optionally followed by an equals sign and an expression giving a default value. The expression is evaluated at the time the method is called. The expressions are evaluated from left to right. An expression may reference a parameter that precedes it in the argument list.

`def options(a=99, b=a+1)`
`[ a, b ]`
`end`
`options` | » | `[99, 100]`
`options 1` | » | `[1, 2]`
`options 2, 4` | » | `[2, 4]`

The optional array argument must follow any regular arguments and may not have a default.

When the method is invoked, Ruby sets the array argument to reference a new object of class `Array`. If the method call specifies any parameters in excess of the regular argument count, all these extra parameters will be collected into this newly created array.

`def varargs(a, *b)`
`[ a, b ]`
`end`
`varargs 1` | » | `[1, []]`
`varargs 1, 2` | » | `[1, [2]]`
`varargs 1, 2, 3` | » | `[1, [2, 3]]`

If an array argument follows arguments with default values, parameters will first be used to override the defaults. The remainder will then be used to populate the array.

`def mixed(a, b=99, *c)`
`[ a, b, c]`
`end`
`mixed 1` | » | `[1, 99, []]`
`mixed 1, 2` | » | `[1, 2, []]`
`mixed 1, 2, 3` | » | `[1, 2, [3]]`
`mixed 1, 2, 3, 4` | » | `[1, 2, [3, 4]]`

The optional block argument must be the last in the list. Whenever the method is called, Ruby checks for an associated block. If a block is present, it is converted to an object of class `Proc` and assigned to the block argument. If no block is present, the argument is set to `nil`.

## Invoking a Method

      [
                      receiver. ] name  [ parameters ] [ block ]

                      [
                      receiver::] name [ parameters ] [ block ]

                      parameters
                     <-
                     ( [
                      param
                      ]*
                       [, hashlist
                      ] [*array
                      ] [&aProc
                      ] )

                      block
                     <-
                     { blockbody }

                     do blockbody end

Initial parameters are assigned to the actual arguments of the method. Following these parameters may be a list of key `=>` value pairs. These pairs are collected into a single new `Hash` object and passed as a single parameter.

Following these parameters may be a single parameter prefixed with an asterisk. If this parameter is an array, Ruby replaces it with zero or more parameters corresponding to the elements of the array.

    def regular(a, b, *c)
      # ..
    end
    regular 1, 2, 3, 4
    regular(1, 2, 3, 4)
    regular(1, *[2, 3, 4])

A block may be associated with a method call using either a literal block (which must start on the same source line as the last line of the method call) or a parameter containing a reference to a `Proc` or `Method` object prefixed with an ampersand character. Regardless of the presence of a block argument, Ruby arranges for the value of the global function `Kernel::block_given?` to reflect the availability of a block associated with the call.

    aProc   = proc { 99 }
    anArray = [ 98, 97, 96 ]

    def block
      yield
    end
    block { }
    block do
          end
    block(&aProc)

    def all(a, b, c, *d, &e)
      puts "a = #{a}"
      puts "b = #{b}"
      puts "c = #{c}"
      puts "d = #{d}"
      puts "block = #{yield(e)}"
    end

    all('test', 1 => 'cat', 2 => 'dog', *anArray, &aProc)

produces:

    a = test
    b = {1=>"cat", 2=>"dog"}
    c = 98
    d = [97, 96]
    block = 99

A method is called by passing its name to a receiver. If no receiver is specified, `self` is assumed.

The receiver checks for the method definition in its own class and then sequentially in its ancestor classes. The instance methods of included modules act as if they were in anonymous superclasses of the class that includes them. If the method is not found, Ruby invokes the method `method_missing` in the receiver. The default behavior defined in `Kernel::method_missing` is to report an error and terminate the program.

When a receiver is explicitly specified in a method invocation, it may be separated from the method name using either a period ```.`'' or two colons ```::`''. The only difference between these two forms occurs if the method name starts with an uppercase letter. In this case, Ruby will assume that a `receiver::Thing` method call is actually an attempt to access a constant called `Thing` in the receiver unless the method invocation has a parameter list between parentheses.

    Foo.Bar()         #  method call
    Foo.Bar           #  method call
    Foo::Bar()        #  method call
    Foo::Bar          #  constant access

The return value of a method is the value of the last expression executed.

    return [
                expr
                ]*

A `return` expression immediately exits a method. The value of a `return` is `nil` if it is called with no parameters, the value of its parameter if it is called with one parameter, or an array containing all of its parameters if it is called with more than one parameter.

### super

    super  [ ( [
                param
                ]*
                 [*array
                ] ) ]  [
                block
                ]

Within the body of a method, a call to `super` acts just like a call to that original method, except that the search for a method body starts in the superclass of the object that was found to contain the original method. If no parameters (and no parentheses) are passed to `super`, the original method's parameters will be passed; otherwise, the parameters to `super` will be passed.

### Operator Methods

    expr1 operator
    operator expr1
    expr1 operator expr2

If the operator in an operator expression corresponds to a redefinable method (see the Table 18.4 on page 219), Ruby will execute the operator expression as if it had been written

    (expr1).operator(expr2)

### Attribute Assignment

    receiver.attrname = rvalue

When the form receiver.attrname appears as an lvalue, Ruby invokes a method named attrname= in the receiver, passing rvalue as a single parameter.

### Element Reference Operator

    receiver [
                  expr
                  ]+

    receiver [
                  expr
                  ]+
                    = rvalue

When used as an rvalue, element reference invokes the method `[]` in the receiver, passing as parameters the expressions between the brackets.

When used as an lvalue, element reference invokes the method `[]=` in the receiver, passing as parameters the expressions between the brackets, followed by the rvalue being assigned.

## Aliasing

    alias newName oldName

creates a new name that refers to an existing method, operator, global variable, or regular expression backreference (`$&`, `$'`, `$'`, and `$+`). Local variables, instance variables, class variables, and constants may not be aliased. The parameters to `alias` may be names or symbols.

`class Fixnum`
`alias plus +`
`end`
`1.plus(3)` | » | `4`
``
`alias $prematch $``
`"string" =~ /i/` | » | `3`
`$prematch` | » | `"str"`
``
`alias :cmd :``
`cmd "date"` | » | `"Sun Nov 25 23:44:19 CST 2001\n"`

When a method is aliased, the new name refers to a copy of the original method's body. If the method is subsequently redefined, the aliased name will still invoke the original implementation.

`def meth`
`"original method"`
`end`
``
`alias original meth`
``
`def meth`
`"new and improved"`
`end`
`meth` | » | `"new and improved"`
`original` | » | `"original method"`

## Class Definition

    class classname  [< superexpr
                ]
      body
    end

    class << anObject
      body
    end

A Ruby class definition creates or extends an object of class `Class` by executing the code in body. In the first form, a named class is created or extended. The resulting `Class` object is assigned to a global constant named classname. This name should start with an uppercase letter. In the second form, an anonymous (singleton) class is associated with the specific object.

If present, superexpr should be an expression that evaluates to a `Class` object that will be installed as the superclass of the class being defined. If omitted, it defaults to class `Object`.

Within body, most Ruby expressions are simply executed as the definition is read. However:

- Method definitions will register the methods in a table in the class object.
- Nested class and module definitions will be stored in constants within the class, not as global constants. These nested classes and modules can be accessed from outside the defining class using ```::`'' to qualify their names.

      module NameSpace
        class Example
          CONST = 123
        end
      end
      obj = NameSpace::Example.new
      a = NameSpace::Example::CONST

- The `Module#include` method will add the named modules as anonymous superclasses of the class being defined.

It is worth emphasizing that a class definition is executable code. Many of the directives used in class definition (such as `attr` and `include`) are actually simply private instance methods of class `Module` (documented starting on page 344).

Chapter 19, which begins on page 237, describes in more detail how `Class` objects interact with the rest of the environment.

### Creating Objects from Classes

    obj = classexpr.new [ ( [
                args
                ]*
                 ) ]

Class `Class` defines the instance method `Class#new` , which:

- Creates an object of the class of the receiver (classexpr in the syntax example).
- Sets that object's type to be the receiver.
- Invokes the instance method `initialize` in the newly created object, passing it any arguments originally passed to `new`.

If a class definition overrides the class method `new` without calling `super`, no objects of that class can be created.

### Class Attribute Declarations

Class attribute declarations are technically not part of the Ruby language: they are simply methods defined in class `Module` that create accessor methods automatically.

    class name
      attr attribute  [, writable
                ]
      attr_reader     [
                attribute
                ]+

      attr_writer     [
                attribute
                ]+

      attr_accessor   [
                attribute
                ]+

    end

## Module Definitions

    module name
      body
    end

A module is basically a class that cannot be instantiated. Like a class, its body is executed during definition and the resulting `Module` object is stored in a constant. A module may contain class and instance methods and may define constants and class variables. As with classes, module methods are invoked using the `Module` object as a receiver, and constants are accessed using the ```::`'' scope resolution operator.

    module Mod
      CONST = 1
      def Mod.method1    # module method
        CONST + 1
      end
    end

`Mod::CONST` | » | `1`
`Mod.method1` | » | `2`

### Mixins---Including Modules

    class|module name
      include expr
    end

A module may be included within the definition of another module or class using the `include` method. The module or class definition containing the `include` gains access to the constants, class variables, and instance methods of the module it includes.

If a module is included within a class definition, the module's constants, class variables, and instance methods are effectively bundled into an anonymous (and inaccessible) superclass for that class. In particular, objects of the class will respond to messages sent to the module's instance methods.

A module may also be included at the top level, in which case the module's constants, class variables, and instance methods become available at the top level.

### Module Functions

Although `include` is useful for providing mixin functionality, it is also a way of bringing the constants, class variables, and instance methods of a module into another namespace. However, functionality defined in an instance method will not be available as a module method.

    module Math
      def sin(x)
        #
      end
    end

    # Only way to access Math.sin is...
    include Math
    sin(1)

The method `Module#module_function` solves this problem by taking one or more module instance methods and copying their definitions into corresponding module methods.

    module Math
      def sin(x)
        #
      end
      module_function :sin
    end

    Math.sin(1)
    include Math
    sin(1)

The instance method and module method are two different methods: the method definition is copied by `module_function`, not aliased.

## Access Control

Ruby defines three levels of protection for module and class constants and methods:

- Public. Accessible to anyone.
- Protected. Can be invoked only by objects of the defining class and its subclasses.
- Private. Can be called only in functional form (that is, with an implicit `self` as the receiver). Private methods therefore can be called only in the defining class and by direct descendents within the same object.

    private    [
                aSymbol
                ]*

    protected  [
                aSymbol
                ]*

    public     [
                aSymbol
                ]*

Each function can be used in two different ways.

1. If used with no arguments, the three functions set the default access control of subsequently defined methods.
2. With arguments, the functions set the access control of the named methods and constants.

Access control is enforced when a method is invoked.

## Blocks, Closures, and Proc Objects

A code block is a set of Ruby statements and expressions between braces or a `do`/`end` pair. The block may start with an argument list between vertical bars. A code block may appear only immediately after a method invocation. The start of the block must be on the same logical line as the end of the invocation.

    invocation  do  | a1, a2, ... |
    end

    invocation  {   | a1, a2, ... |
    }

Braces have a high precedence; `do` has a low precedence. If the method invocation has parameters that are not enclosed in parentheses, the brace form of a block will bind to the last parameter, not to the overall invocation. The `do` form will bind to the invocation.

Within the body of the invoked method, the code block may be called using the `yield` method. Parameters passed to the `yield` will be assigned to arguments in the block using the rules of parallel assignment described starting on page 219. The return value of the `yield` is the value of the last expression evaluated in the block.

A code block remembers the environment in which it was defined, and it uses that environment whenever it is called.

### Proc Objects

Code blocks are converted into objects of class `Proc` using the methods `Proc.new` and `Kernel#proc` , or by associating the block with a method's block argument.

The `Proc` constructor takes an associated block and wraps it with enough context to be able to re-create the block's environment when it is subsequently called. The `Proc#call` instance method then allows you to invoke the original block, optionally passing in parameters. The code in the block (and the associated closure) remains available for the lifetime of the `Proc` object.

If the last argument in a method's argument list is prefixed with an ampersand (```&`''), any block associated with calls to that method will be converted to a `Proc` object and assigned to that parameter.

## Exceptions

Ruby exceptions are objects of class `Exception` and its descendents (a full list of the built-in exceptions is given in Figure 22.1 on page 299).

### Raising Exceptions

The `Kernel::raise` method raises an exception.

    raise
    raise aString
    raise thing [, aString [
                aStackTrace
                ]
                ]

The first form reraises the exception in `$!` or a new `RuntimeError` if `$!` is `nil`. The second form creates a new `RuntimeError` exception, setting its message to the given string. The third form creates an exception object by invoking the method `exception` on its first argument. It then sets this exception's message and backtrace to its second and third arguments. Class `Exception` and objects of class `Exception` contain factory methods called `exception`, so an exception class name or instance can be used as the first parameter to `raise`.

When an exception is raised, Ruby places a reference to the `Exception` object in the global variable `$!`.

### Handling Exceptions

Exceptions may be handled within the scope of a `begin`/`end` block.

      begin
        code...
        code...
    [rescue  [parm]*
                 [=> var
                ] [then]
        error handling code... ]*

    [else
        no exception code...
                ]
    [ensure
        always executed code...
                ]
      end

A block may have multiple `rescue` clauses, and each `rescue` clause may specify zero or more parameters. A `rescue` clause with no parameter is treated as if it had a parameter of `StandardError`.

When an exception is raised, Ruby scans up the call stack until it finds an enclosing `begin`/`end` block. For each `rescue` clause in that block, Ruby compares the raised exception against each of the rescue clause's parameters in turn; each parameter is tested using `$!.kind_of?(parameter)`. If the raised exception matches a `rescue` parameter, Ruby executes the body of the `rescue` and stops looking. If a matching `rescue` clause ends with `=>` and a variable name, the variable is set to `$!`.

Although the parameters to the `rescue` clause are typically the names of `Exception` classes, they can actually be arbitrary expressions (including method calls) that return an appropriate class.

If no rescue clause matches the raised exception, Ruby moves up the stack frame looking for a higher-level `begin`/`end` block that matches. If an exception propagates to the top level without being rescued, the program terminates with a message.

If an `else` clause is present, its body is executed if no exceptions were raised in initial code. Exceptions raised during the execution of the `else` clause are not captured by `rescue` clauses in the same block as the `else`.

If an `ensure` clause is present, its body is always executed as the block is exited (even if an uncaught exception is in the process of being propagated).

### Retrying a Block

The `retry` statement can be used within a `rescue` clause to restart the enclosing `begin`/`end` block from the beginning.

## Catch and Throw

The method `Kernel::catch` executes its associated block.

    catch ( aSymbol | aString )  do
      block...
    end

The method `Kernel::throw` interrupts the normal processing of statements.

    throw( aSymbol | aString [, anObject
                ] )

When a `throw` is executed, Ruby searches up the call stack for the first `catch` block with a matching symbol or string. If it is found, the search stops, and execution resumes past the end of the `catch`'s block. If the `throw` was passed a second parameter, that value is returned as the value of the `catch`. Ruby honors the `ensure` clauses of any block expressions it traverses while looking for a corresponding `catch`.

If no `catch` block matches the `throw`, Ruby raises a `NameError` exception at the location of the `throw`.

Previous < | Contents ^ | Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2000 Addison Wesley Longman, Inc. Released under the terms of the Open Publication License V1.0.
This reference is available for download.