Prelude

Ruby is a succinct, powerful, enjoyable language. That said, it must be noted that Ruby is not identical across platforms, newer versions are not always upwardly compatible with older versions, and resources are not always in complete agreement about the syntax, semantics, and conventions of the language. Nonetheless, any errors in this document are my responsibility.

Ruby is extremely dynamic. Anything the programmer has done, the programmer can revise, add to, or undo at any time. A primary design goal of Ruby is that it be fun to program in. This document describes the syntax of Ruby, but is too brief to convey good idiomatic usage of Ruby.

My main references are Ruby in a Nutshell: A Desktop Quick Reference by Yukihiro Matsumoto ("Matz"), and Programming Ruby: The Pragmatic Programmers' Guide by Dave Thomas. Ruby is the creation of Matz, but Dave Thomas is the main advocate and documenter.

Tools

Command-line Tools

ruby

This will read in and execute a program from the console. Not recommended.

irb

A complete Ruby shell; great for trying things interactively. You can use load "filename" to load predefined code, such as function definitions.

ri ClassName

Displays documentation for the class (in vi; to quit vi, type :q and hit Enter).

Other tools

RDoc

Produces documentation for your program.

RubyGems

Packs code for distribution

FreeRIDE

Simple IDE for Ruby development

RDT, Ruby Development Tools

Ruby plugin for Eclipse

RDT, Ruby Development Tools

Ruby plugin for Eclipse

NetBeans 6 mod 9

Full version includes Ruby IDE and JRuby

Objects and classes

Ruby is a completely object-oriented language--all values are objects. Hence messages such as -5.abs are legal.

A class defines a new type of object. Classes are defined as:

    class NameOfClass
      # variable and method definitions go here
    end

Class names must be capitalized.

If this same class is defined again, any new definitions are added to the class.

To create a new object of a given class, use object = NameOfClass.new. If the class has a method named initialize, that method will be called just after the object has been created. Parameters may be given to the new method, and those same parameters will be passed along to the initialize method.

Methods

Instance methods are defined as

    def method_name(parameter1, ..., parameterN)
        # statements
    end 

and called with

    instance.method_name(parameter1, ..., parameterN)

Class methods are defined as

    def NameOfClass.method_name(parameter1, ..., parameterN)
        # statementsend 

and called with

    NameOfClass.method_name(parameter1, ..., parameterN)

In all of the above, the parentheses are optional; however, in complex expressions the parentheses may be required for disambiguation.

There may be only one method with a given name in the same class. If a named method is defined more than once, the new definition replaces the old one.

A method may contain explicit return or return value statements. If a method terminates by reaching the end of the method, the value returned is the last value computed (which, for many types of statements, is nil).

Layout

Ruby is line-oriented: Each statement goes on a separate line. If a statement ends with an operator, comma, or backslash, it is continued on the next line. Semicolons can be used to separate multiple statements on a single line.

Standard indentation in Ruby is two spaces, not four as in Java.

If a line contains exactly the character sequence __END__ (two underlines on each side), with no whitespace, it ends the program. Any additional lines are data.

Comments

Comments start with a pound sign (#) and continue to the end of the line. Multiline comments are enclosed by =begin (starting in column 1) and =end (starting in column 1).

Names and scope of names

Variables and constants hold references to objects. Variables and constants do not have types; any variable name can reference any type of object. Capitalization conventions given below are enforced by Ruby.

"Constants" can be altered (!); doing so yields a warning message.

Reserved words

Numbers

Integers are decimal by default, but may begin with a base indicator: 0 for octal, 0b for binary, 0x for hexadecimal, or 0d for decimal. Integers may be any size (limited by available memory).

Prefixing a single character with ? gives that character's numeric value. For example, ?a is 97.

Floating-point (real) numbers contain a decimal point, an exponent (following an e), or both. There must be at least one digit before the decimal point and before the e.

For readability, numbers may contain underscores.

Strings

Strings contain ASCII, not Unicode, characters. Newlines may occur within strings. Adjacent strings are concatenated. There are a variety of ways to write literal strings.

Singly-quoted strings

Strings may be enclosed in single quotes ('). Within a singly-quoted string, the only escaped character is \' (single quote). Substitutions are not performed.

Strings may be enclosed with any almost any punctuation mark as a delimiter, prefixed by %q. Example: %q!Hello!. However, if the opening delimiter is (, [, {, or <, the closing delimiter is ), ], }, or >, respectively. These strings act as singly-quoted strings.

Doubly-quoted strings

Strings may be enclosed in double quotes ("). Within a doubly-quoted string, all escaped characters are recognized, and actual values are substituted for the general forms #{expression}and #{expression}. If the expression is a single variable beginning with $ or @, the braces may be omitted: #$var and #@var.

Strings may be enclosed with delimiters, prefixed by %Q. Example: %Q!Hello!. Delimiters are the same as for %q. These strings act as doubly-quoted strings.

Shell commands

Strings may be enclosed in backquotes (`), or any delimiter prefixed by %x. Delimiters are the same as for %q. Escaped characters and substitutions are allowed. The string is evaluated as a command to the underlying operating system, and the result of the command is returned as a string.

Here documents

"Here documents" are for multiline strings. A string may begin with <<delimiter, where the delimiter is any sequence not containing whitespace, and ends with the delimiter in the same column. A string may begin with <<-delimiter, in which case the closing delimiter may be indented.

The initial delimiter may be enclosed in single quotes, double quotes or backquotes, to specify how the string is to be treated. The default is to treat the string as doubly-quoted.

A few String methods

"Characters" are ASCII, not Unicode.

Pseudo-variables

self

Same as self in C++ or this in Java.

true, false

Same as in Java.

nil

Same as null in Java.

__FILE__

The name of the current source file.

__LINE__

The current line number in __FILE__.

Operators

Highest precedence operators are at the top.

Most operators are methods, hence can be redefined. This feature should be used with extreme care and forethought. "Nonmethods" cannot be redefined.

Statement types

Brackets, [ ], indicate that the enclosed part is optional. An ellipsis, ... , means that the preceding element may be repeated.

Many methods are practically indistinguishable from statements. Some of these are included in the following table.

begin
  [code]
[rescue [exception, ...]
  [code]]
[ensure   # may be more than one
  [code]] 
end

begin
  eval string
rescue SyntaxError,
       NameError => boom
  print "Can't compile:" + boom
rescue StandardError => bang
  print "Script error:" + bang
end

break [expression]

break

case expression
[when expression[, expression...][then]
  code]...
[else
  code]
end

case i
when 1, 3, 5 then puts "odd"
when 2, 4
  puts "even"
else puts "too big"
end

class ClassName [< SuperClass]
  code
end

class Something
  puts "whatever"
end

method_call do [|parameter, ...|]|
  [code]
end

array.each do |element|
  puts element
end 

method_call { [|parameter, ...|] [code] }

array.each { |e| puts e } 

my_set.each do |element|
  puts element
end 

for var[, var...] in expression [do]
  code
end

for i in 1..10
  puts "#{i} --> #{i * i}"
end

if condition [then]
  code
[elsif condition [then]
  code]
[else
  code]
end

if count == 0   
  puts 'yes'
elsif count > 0 
  puts 'no'
else
  puts 'maybe'
end

if count==0; puts 'yes'; end

statement if condition

puts 'yes' if count == 0

loop do
  c *= 2
  break if c > 1000
end 

next

next

redo

redo

rescue ExceptionType, ... [=> variable]

retry

retry

unless condition [then]
  code
[else
  code]
end

unless foo == ''
  puts foo
end

statement unless condition

puts foo unless foo == ''

until condition [do]
  code
end

until count > 100 do
  count *= 2
end

statement until condition

count *= 2 until count > 100

begin
  code
end untilcondition

begin
  count *= 2
end until count > 100

while condition [do]
  code
end

while count < 100
  count *= 2
end

statement while condition

count *= 2 while count < 100

begin
  code
end while condition

begin
  count *= 2
end while count < 100

yield [value, ...]

yield result

Ranges

Arrays

An array is a sequence of values indexed by integers; the first location in the array is location 0 (zero). Negative integers can be used to index the array from the other end; -1 is the last location in the array. The values in an array may be of different types. Example:

Arrays may be created by enclosing comma-separated values in square brackets; a final trailing comma is ignored. For example, you can create the above array with

my_array = [ "ace", 250, 3.14, "hi!", :abc ]

An easy way to create an array of strings is with %w (for singly-quoted strings) or %W (for doubly quoted strings). Example:

words = %w( apple banana cherry )

You can also create an array with Array.new.

Any (reasonable) integer can be used as an array index. If you read from an array location that hasn't been used, you get nil; if you write to a previously unused location, it will be created. For example, the following sequence is perfectly legal, and prints three nils and an abc.:

a = Array.new; a[3] = "abc"; a.each { |v| puts v }

If you index into an array with a pair of numbers, a[start, count], you get a new array of count values copied from a, starting from start. If you index with a range, a[min..max], you get a new array of those values copied from a.

Some of the more useful array methods are each, push, pop, sort, sort!, and join.

Hashes

A hash is a mapping of keys to values. Any object that responds to the hash and eql? messages can be used as a key; objects that are eql? must have the same hash code. Immutable objects, such as symbols, make the best keys..

A hash may be created by enclose comma-separated key => value pairs inside braces; for example,

my_hash = { :ace => 1, :jack => 11, :queen => 12, :king => 13 }

Hashes may be "indexed" by a key within brackets, for example, my_hash[:jack] gives 11. If the key does not exist in the hash, nil is returned as the value. New key-value pairs may be added to hashes, for example, my_hash[:foo] = :bar.

The order of key-value pairs in a hash is essentially random.

Modules

A module is defined like a class, and may define class methods, instance methods, instance variables, and constants:

module ModuleName
  expressions
end

Unlike a class, you cannot create an instance of a module.

There are two ways to use modules:

• If you load the module with a require statement, you can reference module methods with ModuleName.method, and constants with ModuleName::Constant. You cannot access instance variables or methods.
• As a mixin: If you include the module in a class, it is as if everything defined in the module is defined in the class.

Input/Output

Interactive I/O

print

Prints its argument without a newline. Example: print 'Enter a number: '

puts

Prints its argument with a newline. Example: puts "I read: #{input}"

printf

The first argument is a format string (as in C), while the remaining arguments are values to be inserted into the format string. Example: printf("Float: %5.2f, int: %i, string: %s", 3.1416, 17, 'foo')

STDOUT.flush

A method used to flush output. Should be used before interactive input. Example: print 'Gimme a number: '; STDOUT.flush; number = gets

file.sync = true

Turns on autoflushing for the specified file.

gets

Reads a line of input from the console, as a string.

 

File I/O

Command line arguments:

• ARGV is an array of command-line arguments.
• ARGF treats the command-line arguments as a virtual concatenation of the named files.

Directory functions:

• Dir.pwd returns the current working directory.
• Dir.chdir(path) changes the current working directory to the given (existing) directory.
• Dir.mkdir(path) creates a new directory.
• Dir.mkdir(path, permissions) creates a new directory with the given Unix permissions (as an octal number).
• Dir.rmdir(path) removes a directory.
• Dir.entries(path) and Dir.foreach(path) return a listing of all the file in the given directory.
• d = Dir.open(path) opens a directory stream. Then...
  • d.path returns the path.
  • d.tell returns the current directory entry.
  • d.read reads the next directory entry.
  • d.rewind goes back to the beginning of the stream.
  • d.each iterates through the directory entries
  • d.close closes the directory stream.

File functions:

• File.new(name, mode) creates a new file. The mode may be:
  • "r" --read from beginning of file.
  • "w" -- write from beginning of existing or new file; old content is discarded.
  • "a" -- append to the end of an existing file, or create a new file.
  • "r+" -- read and/or write, from beginning of file.
  • "w+" -- read and/or write from beginning of existing or new file; old content is discarded.
  • "a+" -- read/write to the end of an existing or new file.
• f = File.open(path) opens a file. Then...
  • f.each iterates through the lines of a (text) file.
  • f.chmod(permissions) changes the Unix permissions of the file.
  • f.close closes the file.
  • f.closed? tests if the file is closed.
  • File.file?(path) tests if the file is a plain file.
  • File.directory?(path) tests if the file is a directory.
  • File.readable?(path) , File.writable?(path), and file.executable?(path) test the status of the file.
• File.rename(old_name, new_name) renames a file.
• File.delete(name) deletes a file.

Examples:

ARGV.each { |arg| puts "arg -> #{arg}" }
puts "pwd -> #{Dir.pwd}"
Dir.foreach(".")  { |file| puts "file -> #{file}" }
Dir.mkdir("goofus", 0755) unless File.exists?  "goofus"

if File.exists?  "goofus"
  Dir.chdir("goofus")
  puts "pwd -> #{Dir.pwd}"
    
  puts "  File 'goofus' created"
  puts "  readable? #{File.readable? "goofus"}"
  puts "  writable? #{File.writable? "goofus"}"
  puts "  executable? #{File.executable? "goofus"}"
  puts "  file? #{File.file? "goofus"}"
  puts "  directory? #{File.directory? "goofus"}"
  
  f = File.new("doofus", "w")
  f.puts "Line one", "Line two"
  f.close # it's important to close the file!

  File.open "doofus" do |f2|
    f2.each_line { |line| puts line }
  end # the block form automatically closes the file

  File.delete("doofus")
  puts "  'doofus' deleted" unless File.exists?  "doofus"
end
 
Dir.chdir("..")
puts "pwd -> #{Dir.pwd}"

Dir.rmdir("goofus") if File.exists?  "goofus"
puts "  'goofus' deleted" unless File.exists?  "goofus"

arg ->arg -> hello
arg -> 123
pwd -> C:/Workspace/RubyTests
file -> .
file -> ..
file -> .loadpath
file -> .project
file -> io_tests.rb
pwd -> C:/Workspace/RubyTests/goofus
  File 'goofus' created
  readable? false
  writable? false
  executable? false
  file? false
  directory? false
Line one
Line two
  'doofus' deleted
pwd -> C:/Workspace/RubyTests
  'goofus' deleted