prev - next - index

Ruby syntax



Lexical structure

The character set used in the ruby source files for the current implementation is based on ASCII. The case of characters in source files is significant. All syntactic constructs except identifiers and certain literals may be separated by an arbitrary number of whitespace characters and comments. The whitespace characters are space, tab, vertical tab, backspace, carriage return, and form feed. Newlines works as whitespace only when expressions obviously continues to the next line.

Identifiers

Examples:

foobar
ruby_is_simple

Ruby identifiers are consist of alphabets, decimal digits, and the underscore character, and begin with a alphabets(including underscore). There are no restrictions on the lengths of ruby identifiers.

Comment

Examples:

# this is a comment line

Ruby comments start with "#" outside of a string or character literal(?#) and all following text until the end of the line. the backslash (/) at the end of line continues a comment to the next line.

Reserved words

The reserved words are:

alias           else            nil             undef
and             elsif           not             unless
begin           end             or              until
case            ensure          rescue          when
class           for             return          while
def             if              self            yield
defined?        in              super           __END__
do              module          then

Program

Example:

print "hello world!\n"

Ruby programs are sequence of expressions. Each expression are delimited by semicolons(;) or newlines.

Expression

Examples:

TRUE
(1+2)*3
foo()
if test then ok else ng end

Ruby expressions can be grouped by parentheses.

String literals

Examples:

"this is a string expression\n"
"concat#{foobar}"
'concat#{foobar}'
%q!I said, "You said, 'She said it.'"!
%!I said, "You said, 'She said it.'"!
%Q('This is it.'\n)

String expressions begin and end with double or single quote marks. Double-quoted string expressions are subject to backslash escape and expression substitution. Single-quoted strings are not (except for \' and \\).

The string expressions begin with % are the special form to avoid putting too many backslashes into quoted strings. The %q/STRING/ expression is the generalized single quote. The %Q/STRING/ (or %/STRING/) expression is the generalized double quote. Any non-alphanumeric delimiter can be used in place of /, including newline. If the delimiter is an opening bracket or parenthesis, the final delimiter will be the corresponding closing bracket or parenthesis. (Embedded occurrences of the closing bracket need to be backslashed as usual.)

Backslash notation

\t
tab(0x09)
\n
newline(0x0a)
\r
carriage return(0x0d)
\f
form feed(0x0c)
\b
backspace(0x08)
\a
bell(0x07)
\e
escape(0x1b)
\nnn
character in octal value nnn
\xnn
character in hexadecimal value nn
\^x
control x
\cx
control x
\C-x
control x
\M-x
meta x (c | 0x80)
\M-\C-x
meta control x
\x
character x itself

The string literal expression yields new string object each time it evaluated.

Command output

Examples:

`date`
%x{ date }

Strings delimited by backquotes are performed by a subshell after escape sequences interpretation and expression substitution. The standard output from the commands are taken as the value. Commands performed each time they evaluated.

The %x/STRING/ is the another form of the command output expression.

Regular expression

Examples:

/^ruby the OOPL/
/ruby/i
/my name is #{myname}/o
%r|^/usr/local/.*|

Strings delimited by slashes are regular expressions. The characters right after latter slash denotes the option to the regular expression. Option i means that regular expression is case insensitive. Option o means that regular expression does expression substitution only once at the first time it evaluated.

The %r/STRING/ is the another form of the regular expression.

^
beginning of a line or string
$
end of a line or string
.
any character except newline
\w
word character[0-9A-Za-z_]
\W
non-word character
\s
whitespace character[ \t\n\r\f]
\S
non-whitespace character
\d
digit, same as[0-9]
\D
non-digit
\b
word boundary(outside[]only)
\B
non-word boundary
\b
backspace(0x08)(inside[]only)
[ ]
any single character of set
*
0 or more previous regular expression
+
1 or more previous regular expression
{m,n}
at least m but most n previous regular expression
?
0 or 1 previous regular expression
|
alternation
( )
grouping regular expressions

Backslash notation and expression substitution available in regular expressions.

Expression substitution in strings

Examples:

"my name is #{$ruby}"

In double-quoted strings, regular expressions, and command output expressions, the form like "#{expression}" extended to the evaluated result of that expression. If the expressions are the variables which names begin with the character either `$',`@', expressions are not needed to be surrounded by braces. The character `#' is interpreted literally if it it not followed by characters `{',`$',`@'.

Numeric literals

123
integer
-123
integer(signed)
1_234
integer(underscore within decimal numbers ignored)
123.45
floating point number
1.2e-3
floating point number
0xffff
hexadecimal integer
0377
octal integer
?a
ASCII code for character `a'(97)
?\C-a
Control-a(1)
?\M-a
Meta-a(225)
?\M-\C-a
Meta-Control-a(129)
:symbol
Integer corresponding identifiers, variable names, and operators.

In ?-representation all backslash notations are available.

Variables and constants

The variable in ruby programs can be distinguished by the first character of its name. They are either global variables, instance variables, local variables, and class constants. There are no restriction for variable name length (except heap size).

Global variables

Examples:

$foobar
$/

The variable which name begins with the character `$', has global scope, and can be accessed from any location of the program. Global variables are available as long as the program lives. Non-initialized global variables has value nil.

Instance variables

Examples:

@foobar

The variable which name begins which the character `@', is an instance variable of self. Instance variables are belong to the certain object. Non-initialized instance variables has value nil.

Constants

Examples:

FOOBAR

The identifier which name begins with upper case letters ([A-Z]) is an constant. The constant definitions are done by assignment in the class definition body. Assignment to the constants must be done once. Changing the constant value or accessing to the non-initialized constants raises a NameError exception.

The constants can be accessed from:

Class definition defines the constant automatically, all class names are constants.

To access constants defined in certain class/module, operator :: can be used.

Examples:

Foo::Bar

No assignment using operator `::' permitted.

Local variables

Examples:

foobar

The identifier which name begins with lower case character or underscore, is a local variable or a method invocation. The first assignment in the local scope (bodies of class, module, method definition) to such identifiers are declarations of the local variables. Non-declared identifiers are method invocation without arguments.

The local variables assigned first time in the iterator blocks are only valid in that block. They are called `dynamic variables.' For example:

i0 = 1
loop {
  i1 = 2
  print defined?(i0), "\n"	# TRUE
  print defined?(i1), "\n"	# TRUE
  break
}
print defined?(i0), "\n"	# TRUE
print defined?(i1), "\n"	# FALSE

Pseudo variables

There are 2 special variables called `pseudo variables'.

self
the receiver of the current method
nil
the sole instance of the Class Nil(represents false)

The values of the pseudo variables cannot be changed. Assignment to these variables causes exceptions.

Array expression

Examples:

[1, 2, 3]

Syntax:

[ expr,...]

Returns an array, which contains result of each expressions. Arrays are instances of the class Array.

Associative-array expression

Examples:

{1=>2, 2=>4, 3=>6}

Syntax:

{ expr => expr...}

Returns an associative-array, which maps each key to corresponding value. Associative-arrays are instances of the class Hash.

Method invocation

Examples:

foo.bar()
foo.bar
bar()
print "hello world\n"
print

Syntax:

[expr `.'] identifier [`(' expr...[`*' expr] `)']

Method invocation expression invokes the method of the receiver (right hand side expression of the dot) specified by the identifier. If no receiver specified, self is used as a receiver.

Identifier names are normal identifiers and identifier suffixed by character ? or !. As a convention, identifier? are used as predicate names, and identifier! are used for the more destructive (or more dangerous) methods than the method which have same name without !.

If last argument expression preceded by *, the value of the expression expanded to arguments, that means

foo(*[1,2,3])
equals
foo(1,2,3)

Some methods are private, and can be called from function form invocations (the forms that omits receiver).

super

Examples:

super
super(1,2,3)

Syntax:

super
super(expr,...)

the super invokes the method which the current method overrides. If no arguments given, arguments to the current method passed to the method.

Assignment

Examples:

foo = bar
foo[0] = bar
foo.bar = baz

Syntax:

variable '=' expr
constant '=' expr
expr`['expr..`]' '=' expr
expr`.'identifier '=' expr

Assignment expression are used to assign objects to the variables or such. Assignments sometimes work as declarations for local variables or class constants. The left hand side of the assignment expressions can be either:

self assignment

Examples:

foo += 12

Syntax:

expr op= expr     # left hand side must be assignable.

This form evaluated as expr = expr op expr. But right hand side expression evaluated once. op can be one of:

+, -, *, /, %, **, &, |, ^, <<, >>

There may be no space between operators and =.

Multiple assignment

Examples:

foo, bar, baz = 1, 2, 3
foo, = list()
foo, *rest = list2()

Syntax:

expr `,' [expr `,'...] [`*' expr] = expr [, expr...][`*' expr]
`*' expr = expr [, expr...][`*' expr]

Multiple assignment form performs multiple assignment from expressions or an array. Each left hand side expression must be assignable. If single right hand side expression given, the value of the expression converted into an array, then each element in array assigned one by one to the left hand side expressions. If number of elements in the array is greater than left hand sides, they are just ignored. If left hand sides are longer than the array, nil will be added to the locations.

Multiple assignment acts like this:

foo, bar = [1, 2]	# foo = 1; bar = 2
foo, bar = 1, 2		# foo = 1; bar = 2
foo, bar = 1		# foo = 1; bar = nil

foo, bar, baz = 1, 2	# foo = 1; bar = 2; baz = nil
foo, bar = 1, 2, 3	# foo = 1; bar = 2
foo,*bar = 1, 2, 3	# foo = 1; bar = [2, 3]

The value of the multiple assignment expressions are the array used to assign.

Operator expressions

Examples:

1+2*3/4

As a syntax sugar, several methods and control structures has operator form. Ruby has operators show below:

high   ::
       [], []
       **
       -(unary)  +(unary)  !  ~
       *  /  %
       +  -
       <<  >>
       &
       |  ^
       >  >=  <  <=
       <=> ==  === !=  =~  !~
       &&
       ||
       .. ...
       =(+=, -=...)
       not
low    and or

Most of operators are just method invocation in special form. But some operators are not methods, but control structures:

=, .., ..., !, not, &&, and, |, or, !=, !~ 

In addition, assignment operators(+= etc.) are not user-definable.

Control structure

Control structures in ruby are expressions, and have some value. Ruby has the loop abstraction feature called iterators. Iterators are user-definable loop structure.

if

Examples:

if age >= 12 then
  print "adult fee\n"
else
  print "child fee\n"
end
gender = if foo.gender == "male" then "male" else "female" end

Syntax:

if expr [then]
  expr...
[elsif expr [then]
  expr...]...
[else
  expr...]
end

if expressions are used for conditional execution. The values FALSE and nil are false, and everything else are true. Notice ruby uses elsif, not else if nor elif.

If conditional part of if is the regular expression literal, then it evaluated like:

$_ =~ /re/

if modifier

Examples:

print "debug\n" if $debug

Syntax:

expr if expr

executes left hand side expression, if right hand side expression is true.

unless

Examples:

unless $baby
  feed_meat
else
  feed_milk
end

Syntax:

unless expr [then]
  expr...
[else
  expr...]
end

unless expressions are used for reverse conditional execution. It is equivalent to:

if !(cond)
  ...
else
  ...
end

unless modifier

Examples:

print "stop\n" unless valid($passwd)

Syntax:

expr unless expr

executes left hand side expression, if right hand side expression is false.

case

Examples:

case $age
when 0 .. 2
  "baby"
when 3 .. 6
  "little child"
when 7 .. 12
  "child"
when 12 .. 18
  "youth"
else
  "adult"
end

Syntax:

case expr
[when expr [, expr]...[then]
  expr..]..
[else
  expr..]
end

the case expressions are also for conditional execution. Comparisons are done by operator ===. Thus:

case expr0
when expr1, expr2
  stmt1
when expr3, expr4
  stmt2
else
  stmt3
end

is basically same to below:

_tmp = expr0
if expr1 === _tmp || expr2 === _tmp
  stmt1
elsif expr3 === _tmp || expr4 === _tmp
  stmt2
else
  stmt3
end

and

Examples:

test && set
test and set

Syntax:

expr `&&' expr
expr `and' expr

Evaluates left hand side, then if the result is true, evaluates right hand side. and is lower precedence alias.

or

Examples:

demo || die
demo or die

Syntax:

expr `||' expr
expr or expr

Evaluates left hand side, then if the result is false, evaluates right hand side. or is lower precedence alias.

not

Examples:

! me
not me
i != you

Syntax:

`!' expr
not expr

Returns true if false, false if true.

expr `!=' expr

Syntax sugar for !(expr == expr).

expr `!~' expr

Syntax sugar for !(expr ~= expr).

Range expressions

Examples:

1 .. 20
/first/ ... /second/

Syntax:

expr `..' expr
expr `...' expr

If range expression appears in any other place than conditional expression, it returns range object from left hand side to right hand side.

If range expression appears in conditional expression, it gives false until left hand side returns true, it stays true until right hand side is true. .. acts like awk, ... acts like sed.

while

Examples:

while sunshine
  work()
end

Syntax:

while expr
  ...
end

Executes body while condition expression returns true.

while modifier

Examples:

sleep while idle

Syntax:

expr while expr

Repeats evaluation of left hand side expression, while right hand side is true. If left hand side is begin expression, while evaluates left hand side at lease once.

until

Examples:

until sunrise
  sleep
end

Syntax:

until expr
  ...
end

Executes body until condition expression returns true.

until modifier

Examples:

work until tired

Syntax:

expr until expr

Repeats evaluation of left hand side expression, until right hand side is true. If left hand side is begin expression, until evaluates left hand side at lease once.

Iterators

Examples:

[1,2,3].each do |i| print i*2, "\n" end
[1,2,3].each{|i| print i*2, "\n"}

Syntax:

method_call do [`|' expr...`|'] expr...end
method_call `{' [`|' expr...`|'] expr...`}'

The method may be invoked with the iterator block (do .. end or {..}). The method may be evaluate back that block from inside of the invocation. The methods that calls back the iterator blocks are called as iterators. The evaluation of the iterator block from iterator is done by yield.

The difference between do and braces are:

for

Examples:

for i in [1, 2, 3]
  print i*2, "\n"
end

Syntax:

for lhs... in expr
  expr..
end

Executes body for each element in the result of expression. for is the syntax sugar for:

(expr).each `{' `|' lhs..`|' expr.. `}'

yield

Examples:

yield data

Syntax:

yield `(' [expr [`,' expr...]])
yield [expr [`,' expr...]]

Evaluates the iterator block given to the current method with arguments, if no argument is given, nil is used as an argument. The argument assignment to the iterator variables is done just like multiple assignment. If the iterator block is not supplied for the current method, the exception is raised.

raise

Examples:

raise "you lose"  # raise RuntimeError
# both raises SyntaxError
raise SyntaxError, "invalid syntax"
raise SyntaxError.new("invalid syntax")
raise		  # re-raise last exception

Syntax:

raise
raise message/exception
raise error_type, message

Raises a exception. In first form, re-raises last exception. In second form, if the argument is the string, creates a new RuntimeError exception, and raises it. If the argument is the exception, raise raises it. In the third form, raise creates a new exception of type error_type, and raises it.

The exception is assigned to the variable $!, and the position in the source file is assigned to the $@.

The word `raise' is not the reserved word in ruby. raise is the method of the Kernel class. There is an alias named fail.

begin

Examples:

begin
  do_something
rescue
  recover
ensure
  must_to_do
end

Syntax:

begin
  expr..
[rescue [error_type,..]
  expr..]..
[ensure
  expr..]
end

begin expression executes its body and returns the value of the last evaluated expression.

If an exception occurs in the begin body, the rescue clause with the matching exception type is executed (if any). The match is done by the kind_of?. The default value of the rescue clause argument is the Exception, which matches all exceptions (not including non-local jumps like SystemExit or Interrupt).

For the rescue clauses, the error_type is evaluated just like the arguments to the method call, and the clause matches if the value of the variable $! is the instance of any one of the error_type of its subclass. If error_type is not class nor module, the rescue clause raises TypeError exception.

If ensure clause given ensure clause body executed whenever beginbody exits.

retry

Examples:

retry

Syntax:

retry

If retry appears in rescue clause of begin expression, restart from the beginning of the begin body.

begin
  do_something # exception raised
rescue
  # handles error
  retry  # restart from beginning
end

If retry appears in the iterator, the iterator block, or the body of the for expression, restarts the invocation of the iterator call. Arguments to the iterator is re-evaluated.

for i in 1..5
  retry if some_condition # restart from i == 1
end
# user defined "until loop"
def UNTIL(cond)
  yield
  retry if not cond
end

retry out of rescue clause or iterators raises exception.

The word `retry' is not the reserved word in ruby. retry is the method of the Kernel class. There is an alias named `retry!' in case retry is redefined.

return

Examples:

return
return 12
return 1,2,3

Syntax:

return [expr[`,' expr...]]

Exits from method with the return value. If more than two expressions are given, the array contains these values will be the return value. If no expression given, nil will be the return value.

break

Examples:

i=0
while i<3
  print i, "\n"
  break
end

Syntax:

break

Exits from the most internal loop. Notice break does not exit from case expression like C. The word `break' is not the reserved word in ruby. break is the method of the Kernel class. There is an alias named `break!' in case the break is redefined.

next

Examples:

next

Syntax:

next

Jumps to next iteration of the most internal loop. The word `next' is not the reserved word in ruby. next is the method of the Kernel class. There is an alias named `next!' in case next is redefined. There also be an alias continue for the C freaks.

redo

Examples:

redo

Syntax:

redo

Restarts this iteration of the most internal loop, without checking loop condition. The word `redo' is not the reserved word in ruby. redo is the method of the Kernel class. There is an alias named `redo!' in case redo is redefined.

Class definitions

Examples:

class Foo < Super
  def test
     :
  end
     :
end

Syntax:

class identifier [`<' superclass ]
  expr..
end

Defines the new class. The class names are identifiers begin with uppercase character.

Singleton-class definitions

Examples:

class << obj
  def test
     :
  end
     :
end

Syntax:

class `<<' expr
  expr..
end

Defines the class attribute for certain object. The definitions within this syntax only affect the specified object.

Module definitions

Examples:

module Foo
  def test
     :
  end
     :
end

Syntax:

module identifier
  expr..
end

Defines the new module The module names are identifiers begin with uppercase character.

Method definitions

Examples:

def fact(n)
  if n == 1 then
     1 
  else
    n * fact(n-1)
  end
end

Syntax:

def identifier [`(' [arg ['=' default]]...[`,' `*' arg ]`)']
  expr..
end

Defines the new method. Notice the method is not available before the definition. For example:

foo def foo print "foo\n" end
will raise an exception for undefined method invoking.

The argument with default expression is optional. The evaluation of the default expression is done at the method invocation time. If the last argument preceded by *, actual parameters which don't have corresponding formal arguments are assigned in this argument as an array.

The method definitions can not be nested.

The return value of the method is the value given to the return, or that of the last evaluated expression.

Some methods are marked as `private', and must be called in the function form.

When the method is defined outside of the class definition, the method is marked as private by default. On the other hand, the newly defined method is marked as public by default in the class definition. When redefining the methods, the private mark is inherited from the overriding method of the superclass.

The `private' mark of the methods can be changed by public or private of the Module.

Singleton-method definitions

Examples:

def foo.test
  print "this is foo\n"
end

Syntax:

def expr `.' identifier [`(' [arg [`=' default]]...[`,' `*' arg ]`)']
  expr..
end

The singleton-method is the method which belongs to certain object. The singleton-method definitions can be nested.

The singleton-methods of classes inherited to its subclasses. The singleton-methods of classes are acts like class methods in other object-oriented languages.

alias

Examples:

alias foo bar
alias $MATCH $&

Syntax:

alias method-name method-name
alias global-variable-name global-variable-name

Gives alias to methods or global variables. Aliases can not be defined within the method body.

The aliase of the method keep the current definition of the method, even when methods are overridden.

Making aliases for the numbered global variables ($1, $2,...) is prohibited. Overriding the builtin global variables may cause serious problems.

undef

Examples:

undef bar

Syntax:

undef method-name

Cancels the method definition. Undef can not appear in the method body. By using undef and alias, the interface of the class can be modified independently from the superclass, but notice it may be broke programs by the internal method call to self.

defined?

Examples:

defined? print
defined? File.print
defined?(foobar)
defined?($foobar)
defined?(@foobar)
defined?(Foobar)

Syntax:

defined? expr

Returns false if the expression is not defined. Returns the string that describes a kind of the expression.


prev - next - index

matz@caelum.co.jp