scala_ref.txt

*Preface



Scala is a Java-like programming language which unifies
object-oriented and functional programming.  It is a pure
object-oriented language in the sense that every value is an
object. Types and behavior of objects are described by
classes. Classes can be composed using mixin composition.  Scala is
designed to work seamlessly with two less pure but mainstream
object-oriented languages -- Java and C.

Scala is a functional language in the sense that every function is a
value. Nesting of function definitions and higher-order functions are
naturally supported. Scala also supports a general notion of pattern
matching which can model the algebraic types used in many functional
languages.

Scala has been designed to interoperate seamlessly with Java (an
alternative implementation of Scala also works for .NET). Scala
classes can call Java methods, create Java objects, inherit from Java
classes and implement Java interfaces. None of this requires interface
definitions or glue code.

Scala has been developed from 2001 in the programming methods
laboratory at EPFL. Version 1.0 was released in November 2003. This
document describes the second version of the language, which was
released in March 2006. It acts a reference for the language
definition and some core library modules. It is not intended to teach
Scala or its concepts; for this there are other documents




.

Scala has been a collective effort of many people. The design and the
implementation of version 1.0 was completed by Philippe Altherr,
Vincent Cremet, Gilles Dubochet, Burak Emir, Stephane Micheloud,
Nikolay Mihaylov, Michel Schinz, Erik Stenman, Matthias Zenger, and
the author. Iulian Dragos, Gilles Dubochet, Philipp Haller, Sean
McDirmid, Lex Spoon, and Geoffrey Washburn joined in the effort to
develop the second version of the language and tools.  Gilad Bracha,
Craig Chambers, Erik Ernst, Matthias Felleisen, Shriram Krishnamurti,
Gary Leavens, Sebastian Maneth, Erik Meijer, Klaus Ostermann, Didier
Remy, Mads Torgersen, and Philip Wadler have shaped the design of
the language through lively and inspiring discussions and comments on
previous versions of this document.  The contributors to the Scala
mailing list have also given very useful feedback that helped us
improve the language and its tools.

Lexical Syntax

Scala programs are written using the Unicode Basic Multilingual Plane
(bmp) character set; Unicode supplementary characters are not
presently supported.  This chapter defines the two modes of Scala's
lexical syntax, the Scala mode and the xml mode. If not
otherwise mentioned, the following descriptions of Scala tokens refer
to Scala mode, and literal characters `c' refer to the ASCII fragment
0000007F.

In Scala mode, Unicode escapes are replaced by the corresponding
Unicode character with the given hexadecimal code.

UnicodeEscape ::= uu hexDigit hexDigit hexDigit hexDigit
hexDigit      ::= `0'    `9'  `A'    `F'  `a'    `f'

To construct tokens, characters are distinguished according to the following classes
(Unicode general category given in parentheses):

Whitespace characters. 0020  0009  000D  000A
Letters, which include lower case letters(Ll), upper case letters(Lu), titlecase letters(Lt), other letters(Lo), letter numerals(Nl) and the
two characters 0024  and 005F  which
both count as upper case letters
Digits     `9'@.
Parentheses   `)'  `['  `]'  `'  `'@.
Delimiter characters   `''  `"'  `.'  `;'  `,'@.
Operator characters. These consist of all printable ASCII characters 0020007F.
which are in none of the sets above, mathematical symbols(Sm) and other symbols(So).


Identifiers

lstlisting
op       ::=  opchar opchar
varid    ::=  lower idrest
plainid  ::=  upper idrest
             varid
             op
id       ::=  plainid
             `' stringLit `'
idrest   ::=  letter  digit [`_' op]


There are three ways to form an identifier. First, an identifier can
start with a letter which can be followed by an arbitrary sequence of
letters and digits. This may be followed by underscore `_@'
characters and another string composed of either letters and digits or
of operator characters.  Second, an identifier can start with an operator
character followed by an arbitrary sequence of operator characters.
The preceding two forms are called plain identifiers.  Finally,
an identifier may also be formed by an arbitrary string between
back-quotes (host systems may impose some restrictions on which
strings are legal for identifiers).  The identifier then is composed
of all characters excluding the backquotes themselves.

As usual, a longest match rule applies. For instance, the string


big_bob++=`def`


decomposes into the three identifiers _bob@, ++=@, and
def.  The rules for pattern matching further distinguish between
variable identifiers, which start with a lower case letter, and
constant identifiers, which do not.


The `[mathescape=false]@ character is reserved
for compiler-synthesized identifiers.  User programs should not define
identifiers which contain `[mathescape=false]@
characters.

The following names are reserved words instead of being members of the
syntactic class id of lexical identifiers.


abstract    case        catch       class       def
do          else        extends     false       final
finally     for         forSome     if          implicit
import      lazy        match       new         null
object      override    package     private     protected
return      sealed      super       this        throw
trait       try         true        type        val
var         while       with        yield
_    :    =    =>    <-    <:    <


The Unicode operators 21D2 `' and 2190
`', which have the ASCII equivalents `and
`<-@', are also reserved.


Here are examples of identifiers:

    x         Object        maxIndex   p2p      empty_?
    +         `yield`            _y       dot_product_*
    __system  _MAX_LEN_


Backquote-enclosed strings are a solution when one needs to
access Java identifiers that are reserved words in Scala. For
instance, the statement  .yield()@ is illegal, since
yield is a reserved word in Scala. However, here's a
work-around:

Thread.`yield`()


Newline Characters

lstlisting
semi ::= `;'   nl nl


Scala is a line-oriented language where statements may be terminated by
semi-colons or newlines. A newline in a Scala source text is treated
as the special token ``if the three following
criteria are satisfied:


The token immediately preceding the newline can terminate a statement.

The token immediately following the newline can begin a statement.

The token appears in a region where newlines are enabled.


The tokens that can terminate a statement are: literals, identifiers
and the following delimiters and reserved words:

this    null    true    false    return    type    <xml-start>
_       )       ]


The tokens that can begin a statement are all Scala tokens except
the following delimiters and reserved words:

catch    else    extends    finally    forSome    match
with    yield    ,    .    ;    :    =    =>    <-    <:    <
>:    #    [    )    ]

A token can begin a statement only if followed by a
or token.

Newlines are enabled in:


all of a Scala source file, except for nested regions where newlines
are disabled, and

the interval between matching @ and @ brace tokens,
except for nested regions where newlines are disabled.


Newlines are disabled in:


the interval between matching (@ and )@ parenthesis tokens, except for nested regions where newlines are enabled, and

the interval between matching [@ and ]@ bracket tokens,
except for nested regions where newlines are enabled.

The interval between a token and its matching
token, except for nested regions where newlines are
enabled.
Any regions analyzed in XML mode (sec::xmlMode).

Note that the brace characters of ...@ escapes in XML and
string literals are not tokens,
and therefore do not enclose a region where newlines
are enabled.

Normally, only a single nl token is inserted between two
consecutive non-newline tokens which are on different lines, even if there are multiple lines
between the two tokens. However, if two tokens are separated by at
least one completely blank line (i.e a line which contains no
printable characters), then two nl tokens are inserted.

The Scala grammar (given in full in Appendix )
contains productions where optional nl tokens, but not
semicolons, are accepted. This has the effect that a newline in one of these
positions does not terminate an expression or statement. These positions can
be summarized as follows:

Multiple newline tokens are accepted in the following places (note
that a semicolon in place of the newline would be illegal in every one
of these cases):

[--]
between the condition of an conditional expression
(sec:cond) or while loop (sec:while) and the next
following expression,
[--]
between the enumerators of a for-comprehension (sec:for-comprehensions)
and the next following expression, and
[--]
after the initial keyword in a type definition or
declaration (sec:typedcl).

A single new line token is accepted

[--]
  in front of an opening brace ``'', if that brace is a legal
  continuation of the current statement or expression,
[--]
  after an infix operator, if the first token on the next line can
  start an expression (sec:infix-operations),
[--]
  in front of a parameter clause (sec:funsigs), and
[--]
  after an annotation (sec:annotations).


The following code contains four well-formed statements, each
on two lines. The newline tokens between the two lines are not
treated as statement separators.

if (x > 0)
  x = x - 1

while (x > 0)
  x  = x / 2

for (x <- 1 to 10)
  println(x)

type
  IntList = List[Int]


The following code designates an anonymous class

new Iterator[Int]

  private var x = 0
  def hasNext = true
  def next =  x += 1; x



With an additional newline character, the same code is interpreted as
an object creation followed by a local block:


new Iterator[Int]


  private var x = 0
  def hasNext = true
  def next =  x += 1; x



The following code designates a single expression:


  x < 0
  x > 10


With an additional newline character, the same code is interpreted as
two expressions:


  x < 0

  x > 10


The following code designates a single, curried function definition:


  def func(x: Int)
          (y: Int) = x + y


With an additional newline character, the same code is interpreted as
an abstract function definition and a syntactically illegal statement:


  def func(x: Int)

          (y: Int) = x + y


The following code designates an attributed definition:


  @serializable
  protected class Data  ...


With an additional newline character, the same code is interpreted as
an attribute and a separate statement (which is syntactically
illegal).


  @serializable

  protected class Data  ...



Literals

There are literals for integer numbers, floating point numbers,
characters, booleans, symbols, strings.  The syntax of these literals is in
each case as in Java.

say that we take values from Java, give examples of some lits in
  particular float and double.

lstlisting
Literal  ::=  [`-'] integerLiteral
             [`-'] floatingPointLiteral
             booleanLiteral
             characterLiteral
             stringLiteral
             symbolLiteral
             `null'


Integer Literals

lstlisting
integerLiteral  ::=  (decimalNumeral  hexNumeral  octalNumeral) [`L'  `l']
decimalNumeral  ::=  `0'  nonZeroDigit digit
hexNumeral      ::=  `0' `x' hexDigit hexDigit
octalNumeral    ::=  `0' octalDigit octalDigit
digit           ::=  `0'  nonZeroDigit
nonZeroDigit    ::=  `1'    `9'
octalDigit      ::=  `0'    `7'

Integer literals are usually of type , or of type
when followed by a or
suffix. Values of type are all integer
numbers between  and , inclusive.  Values of
type are all integer numbers between  and
, inclusive. A compile-time error occurs if an integer literal
denotes a number outside these ranges.

However, if the expected type  (sec:expr-typing) of a literal
in an expression is either Byte, Short, or Char
and the integer number fits in the numeric range defined by the type,
then the number is converted to type  and the literal's type
is . The numeric ranges given by these types are:

p2cml
&  to
&  to
&  to




Here are some integer literals:

0          21          0xFFFFFFFF       0777L


Floating Point Literals

lstlisting
floatingPointLiteral  ::=  digit digit `.' digit [exponentPart] [floatType]
                          `.' digit digit [exponentPart] [floatType]
                          digit digit exponentPart [floatType]
                          digit digit [exponentPart] floatType
exponentPart          ::=  (`E'  `e') [`+'  `-'] digit digit
floatType             ::=  `F'  `f'  `D'  `d'

Floating point literals are of type when followed by
a floating point type suffix or , and are
of type otherwise.  The type
consists of all IEEE 754 32-bit single-precision binary floating point
values, whereas the type consists of all IEEE 754
64-bit double-precision binary floating point values.

If a floating point literal in a program is followed by a token
starting with a letter, there must be at least one intervening
whitespace character between the two tokens.


Here are some floating point literals:

0.0        1e30f      3.14159f      1.0e-100      .1



The phrase `1.toString@' parses as three different tokens:
``.@', and `On the
other hand, if a space is inserted after the period, the phrase
`1. toString@' parses as the floating point literal
`1.@' followed by the identifier `






Boolean Literals

lstlisting
booleanLiteral  ::=  `true'  `false'


The boolean literals and are
members of type .

Character Literals

lstlisting
characterLiteral  ::=  `' printableChar `'
                      `' charEscapeSeq `'


A character literal is a single character enclosed in quotes.
The character is either a printable unicode character or is described
by an escape sequence (sec:escapes).


Here are some character literals:

'a'    '''

Note that `is not a valid character literal because
Unicode conversion is done before literal parsing and the Unicode
character 000A@ (line feed) is not a printable
character. One can use instead the escape sequence `or
the octal escape `2@' (sec:escapes).

String Literals

lstlisting
stringLiteral  ::=  `' stringElement `'
stringElement  ::=  printableCharNoDoubleQuote    charEscapeSeq


A string literal is a sequence of characters in double quotes.  The
characters are either printable unicode character or are described by
escape sequences (sec:escapes). If the string literal
contains a double quote character, it must be escaped,
i.e. @. The value of a string literal is an instance of
class .


Here are some string literals:

"Hello,!"
"This string contains a  character."


*Multi-Line String Literals

lstlisting
stringLiteral   ::=  `"""' multiLineChars `"""'
multiLineChars  ::=  ['"'] ['"'] charNoDoubleQuote `"'


A multi-line string literal is a sequence of characters enclosed in
triple quotes  """ ... """@. The sequence of characters is
arbitrary, except that it may contain three or more consuctive quote characters
only at the very end. Characters
must not necessarily be printable; newlines or other
control characters are also permitted.  Unicode escapes work as everywhere else, but none
of the escape sequences in (sec:escapes) is interpreted.

Here is a multi-line string literal:

  """the present string
     spans three
     lines."""

This would produce the string:

the present string
     spans three
     lines.

The Scala library contains a utility method
which can be used to strip leading whitespace from multi-line strings.
The expression

 """the present string
   spans three
   lines.""".stripMargin

evaluates to

the present string
spans three
lines.

Method is defined in class
.collection.immutable.StringLike@.
Because there is a predefined
implicit conversion (sec:impl-conv) from String to
StringLike, the method is applicable to all strings.

Escape Sequences

The following escape sequences are recognized in character and string
literals.

p2cmll
& 0008@: backspace BS
& 0009@: horizontal tab HT
& 000a@: linefeed LF
& 000c@: form feed FF
& 000d@: carriage return CR
@ & 0022@: double quote "
@ & 0027@: single quote '
@ & 005c@: backslash


A character with Unicode between 0 and 255 may also be represented by
an octal escape, i.e. a backslash `followed by a
sequence of up to three octal characters.

It is a compile time error if a backslash character in a character or
string literal does not start a valid escape sequence.

Symbol literals

lstlisting
symbolLiteral  ::=  `'' plainid


A symbol literal  is a shorthand for the expression
 .Symbol("")@. is a case class
(sec:case-classes), which is defined as follows.

package scala
final case class Symbol private (name: String)
  override def toString: String = "'" + name


The method of companion object
caches weak references to , thus ensuring that
identical symbol literals are equivalent with respect to reference
equality.

Whitespace and Comments

Tokens may be separated by whitespace characters
and/or comments. Comments come in two forms:

A single-line comment is a sequence of characters which starts with
//@ and extends to the end of the line.

A multi-line comment is a sequence of characters between
/*@ and */@. Multi-line comments may be nested,
but are required to be properly nested.  Therefore, a comment like
/* /* */@ will be rejected as having an unterminated
comment.

XML mode

In order to allow literal inclusion of XML fragments, lexical analysis
switches from Scala mode to XML mode when encountering an opening
angle bracket '<' in the following circumstance: The '<' must be
preceded either by whitespace, an opening parenthesis or an opening
brace and immediately followed by a character starting an XML name.

lstlisting
 ( whitespace  `('  `' ) `<' (XNameStart  `!'  `?')

  XNameStart ::= `_'  BaseChar  Ideographic  `:'


The scanner switches from XML mode to Scala mode if either

the XML expression or the XML pattern started by the initial '<' has been
successfully parsed, or if

the parser encounters an embedded Scala expression or pattern and
forces the Scanner
back to normal mode, until the Scala expression or pattern is
successfully parsed. In this case, since code and XML fragments can be
nested, the parser has to maintain a stack that reflects the nesting
of XML and Scala expressions adequately.


Note that no Scala tokens are constructed in XML mode, and that comments are interpreted
as text.


The following value definition uses an XML literal with two embedded
Scala expressions

val b = <book>
          <title>The Scala Language Specification</title>
          <version>scalaBook.version</version>
          <authors>scalaBook.authors.mkList("", ", ", "")</authors>
        </book>


Identifiers, Names and Scopes

Names in Scala identify types, values, methods, and classes which are
collectively called entities. Names are introduced by local
definitions and declarations (sec:defs), inheritance (sec:members),
import clauses (sec:import), or package clauses
(sec:packagings) which are collectively called
bindings.

Bindings of different kinds have a precedence defined on them:

Definitions and declarations that are local, inherited, or made
available by a package clause in the same compilation unit where the
definition occurs have highest precedence.
Explicit imports have next highest precedence.
Wildcard imports  have next highest precedence.
Definitions made available by a package clause not in the
compilation unit where the definition occurs have lowest precedence.


There are two different name spaces, one for types (sec:types)
and one for terms (sec:exprs).  The same name may designate a
type and a term, depending on the context where the name is used.

A binding has a scope in which the entity defined by a single
name can be accessed using a simple name. Scopes are nested.  A binding
in some inner scope shadows bindings of lower precedence in the
same scope as well as bindings of the same or lower precedence in outer
scopes.

Note that shadowing is only a partial order. In a situation like

val x = 1;
 import p.x;
  x

neither binding of x shadows the other. Consequently, the
reference to x in the third line above would be ambiguous.

A reference to an unqualified (type- or term-) identifier  is bound
by the unique binding, which

defines an entity with name  in the same namespace as the
identifier, and
shadows all other bindings that define entities with name  in that namespace.

It is an error if no such binding exists.  If  is bound by an
import clause, then the simple name  is taken to be equivalent to
the qualified name to which  is mapped by the import clause. If
is bound by a definition or declaration, then  refers to the entity
introduced by that binding. In that case, the type of  is the type
of the referenced entity.

Assume the following two definitions of a objects named in packages and .


package P
  object X  val x = 1; val y = 2



package Q
  object X  val x = true; val y = ""


The following program illustrates different kinds of bindings and
precedences between them.

package P                   // `X' bound by package clause
import Console._             // `println' bound by wildcard import
object A
  println("L4: "+X)          // `X' refers to `P.X' here
  object B
    import Q._               // `X' bound by wildcard import
    println("L7: "+X)        // `X' refers to `Q.X' here
    import X._               // `x' and `y' bound by wildcard import
    println("L8: "+x)        // `x' refers to `Q.X.x' here
    object C
      val x = 3              // `x' bound by local definition
      println("L12: "+x)     // `x' refers to constant `3' here
       import Q.X._         // `x' and `y' bound by wildcard import
//      println("L14: "+x)   // reference to `x' is ambiguous here
        import X.y           // `y' bound by explicit import
        println("L16: "+y)   // `y' refers to `Q.X.y' here
         val x = "abc"      // `x' bound by local definition
          import P.X._       // `x' and `y' bound by wildcard import
//        println("L19: "+y) // reference to `y' is ambiguous here
          println("L20: "+x) // `x' refers to string ``abc'' here



A reference to a qualified (type- or term-) identifier  refers to
the member of the type  of  which has the name  in the same
namespace as the identifier. It is an error if  is not a value type
(sec:value-types). The type of  is the member type of the
referenced entity in .

Types

lstlisting
  Type              ::=  FunctionArgTypes `=>' Type
                        InfixType [ExistentialClause]
  FunctionArgTypes  ::= InfixType
                       `(' [ ParamType `,' ParamType  ] `)'
  ExistentialClause ::=  `forSome' `' ExistentialDcl semi ExistentialDcl `'
  ExistentialDcl    ::=  `type' TypeDcl
                        `val' ValDcl
  InfixType         ::=  CompoundType id [nl] CompoundType
  CompoundType      ::=  AnnotType `with' AnnotType [Refinement]
                        Refinement
  AnnotType         ::=  SimpleType Annotation
  SimpleType        ::=  SimpleType TypeArgs
                        SimpleType `#' id
                        StableId
                        Path `.' `type'
                        `(' Types ')'
  TypeArgs          ::=  `[' Types `]'
  Types             ::=  Type `,' Type


We distinguish between first-order types and type constructors, which
take type parameters and yield types. A subset of first-order types
called value types represents sets of (first-class) values.
Value types are either concrete or abstract.

Every concrete value type can be represented as a class type, i.e. a
type designator (sec:type-desig) that refers to a
a class or a trait We assume that objects and packages also implicitly
define a class (of the same name as the object or package, but
inaccessible to user programs). (sec:class-defs), or as a
compound type (sec:compound-types) representing an
intersection of types, possibly with a refinement
(sec:refinements) that further constrains the types of its
members.
A shorthand exists for denoting function types (sec:function-types).
Abstract value types are introduced by type parameters (sec:type-params)
and abstract type bindings (sec:typedcl). Parentheses in types can be used for
grouping.


Non-value types capture properties of identifiers that are not values
(sec:synthetic-types). For example, a type constructor (sec:higherkinded-types) does not directly specify a type of values. However, when a type constructor is applied to the correct type arguments, it yields a first-order type, which may be a value type.

Non-value types are expressed indirectly in Scala. E.g., a method type is described by writing down a method signature, which in itself is not a real type, although it  gives rise to a corresponding method type (sec:method-types). Type constructors are another example, as one can write Swap[m[_, _], a,b] = m[b, a]@, but there is no syntax to write the corresponding anonymous type function directly.

Paths

lstlisting
  Path            ::=  StableId
                      [id `.'] this
  StableId        ::=  id
                      Path `.' id
                      [id '.'] `super' [ClassQualifier] `.' id
  ClassQualifier  ::= `[' id `]'


Paths are not types themselves, but they can be a part of named types
and in that function form a central role in Scala's type system.

A path is one of the following.


The empty path  (which cannot be written explicitly in user programs).

.this@, where  references a class.
The path this is taken as a shorthand for .this@ where
 is the name of the class directly enclosing the reference.

.@ where  is a path and  is a stable member of .
Stable members are packages or members introduced by object definitions or
by value definitions of non-volatile types
(sec:volatile-types).


.super.@ or .super[].@
where  references a class and  references a
stable member of the super class or designated parent class  of .
The prefix super is taken as a shorthand for .super@ where
 is the name of the class directly enclosing the reference.

A stable identifier is a path which ends in an identifier.

Value Types

Every value in Scala has a type which is of one of the following
forms.

Singleton Types



lstlisting
  SimpleType  ::=  Path `.' type


A singleton type is of the form .type@, where  is a
path pointing to a value expected to conform (sec:expr-typing)
to .AnyRef@.  The type denotes the set of values
consisting of null and the value denoted by .

A stable type is either a singleton type or a type which is
declared to be a subtype of trait .Singleton@.

Type Projection


lstlisting
  SimpleType  ::=  SimpleType `#' id


A type projection #@ references the type member named
 of type .



Type Designators


lstlisting
  SimpleType  ::=  StableId


A type designator refers to a named value type. It can be simple or
qualified. All such type designators are shorthands for type projections.

Specifically, the unqualified type name  where  is bound in some
class, object, or package  is taken as a shorthand for
.this.type#@. If  is
not bound in a class, object, or package, then  is taken as a
shorthand for .type#@.

A qualified type designator has the form .@ where  is
a path (sec:paths) and  is a type name. Such a type designator is
equivalent to the type projection .type#@.


Some type designators and their expansions are listed below. We assume
a local type parameter , a value maintable
with a type member Node and the standard class .Int@,

  t                     .type#t
  Int                   scala.type#Int
  scala.Int             scala.type#Int
  data.maintable.Node   data.maintable.type#Node


Parameterized Types


lstlisting
  SimpleType      ::=  SimpleType TypeArgs
  TypeArgs        ::=  `[' Types `]'


A parameterized type  consists of a type
designator  and type parameters  where
.   must refer to a type constructor which takes  type
parameters .

Say the type parameters have lower bounds  and
upper bounds .  The parameterized type is
well-formed if each actual type parameter conforms to its
bounds, i.e.  where  is the
substitution .

ex:param-types
Given the partial type definitions:


  class TreeMap[A <: Comparable[A], B]
  class List[A]
  class I extends Comparable[I]

  class F[M[_], X]
  class S[K <: String]
  class G[M[ Z <: I ], I]


the following parameterized types are well formed:


  TreeMap[I, String]
  List[I]
  List[List[Boolean]]

  F[List, Int]
  G[S, String]


Given the type definitions of ,
the following types are ill-formed:


  TreeMap[I]            // illegal: wrong number of parameters
  TreeMap[List[I], Int] // illegal: type parameter not within bound

  F[Int, Boolean]       // illegal: Int is not a type constructor
  F[TreeMap, Int]       // illegal: TreeMap takes two parameters,
                        //   F expects a constructor taking one
  G[S, Int]             // illegal: S constrains its parameter to
                        //   conform to String,
                        // G expects type constructor with a parameter
                        //   that conforms to Int


Tuple Types

lstlisting
  SimpleType    ::=   `(' Types ')'


A tuple type ()@ is an alias for the
class  .Tuple[]@, where
.

Tuple classes are case classes whose fields can be accessed using
selectors  _1, ..., _@. Their functionality is
abstracted in a corresponding Product trait. The -ary tuple
class and product trait are defined at least as follows in the
standard Scala library (they might also add other methods and
implement other traits).


case class Tuple[+T1, ..., +T](_1: T1, ..., _: T)
extends Product[T1, ..., T]

trait Product[+T1, +T2, +T]
  override def arity =
  def _1: T1
  ...
  def _:T



Annotated Types

lstlisting
  AnnotType  ::=  SimpleType Annotation


An annotated type  @
attaches annotations  to the type
(sec:annotations).

The following type adds the @suspendable@ annotation to the type
String:

  String @suspendable


Compound Types



lstlisting
  CompoundType    ::=  AnnotType `with' AnnotType [Refinement]
                      Refinement
  Refinement      ::=  [nl] `' RefineStat semi RefineStat `'
  RefineStat      ::=  Dcl
                      `type' TypeDef



A compound type   with  with  @
represents objects with members as given in the component types
 and the refinement @. A refinement
@ contains declarations and type definitions.
If a declaration or definition overrides a declaration or definition in
one of the component types , the usual rules for
overriding (sec:overriding) apply; otherwise the declaration
or definition is said to be ``structural'' A reference to a
structurally defined member (method call or access to a value or
variable) may generate binary code that is significantly slower than
an equivalent code to a non-structural member..

Within a method declaration in a structural refinement, the type of
any value parameter may only refer to type parameters or abstract
types that are contained inside the refinement. That is, it must refer
either to a type parameter of the method itself, or to a type
definition within the refinement. This restriction does not apply to
the function's result type.

If no refinement is given, the empty refinement is implicitly added,
i.e.    with  with @  is a shorthand for
  with  with  @.

A compound type may also consist of just a refinement
 @ with no preceding component types. Such a type is
equivalent to  @.

The following example shows how to declare and use a function which parameter's type contains a refinement with structural declarations.
[escapechar=]
  case class Bird (val name: String) extends Object
  	def fly(height: Int) = ...
	...

  case class Plane (val callsign: String) extends Object
  	def fly(height: Int) = ...
	...

  def takeoff(
  	    runway: Int,
        r:  val callsign: String; def fly(height: Int) ) =
    tower.print(r.callsign + " requests take-off on runway " + runway)
    tower.read(r.callsign + " is clear f
    r.fly(1000)

  val bird = new Bird("Polly the parrot") val callsign = name
  val a380 = new Plane("TZ-987")
  takeoff(42, bird)
  takeoff(89, a380)

Although  and  do not share any parent class other than  , the parameter  of function  is defined using a refinement with structural declarations to accept any object that declares a value  and a  function.


Infix Types

lstlisting
  InfixType     ::=  CompoundType id [nl] CompoundType

An infix type  @  consists of an infix
operator  which gets applied to two type operands  and
.  The type is equivalent to the type application
.  The infix operator  may be an arbitrary identifier,
except for *, which is reserved as a postfix modifier
denoting a repeated parameter type (sec:repeated-params).

All type infix operators have the same precedence; parentheses have to
be used for grouping. The associativity (sec:infix-operations)
of a type operator is determined as for term operators: type operators
ending in a colon `:@' are right-associative; all other
operators are left-associative.

In a sequence of consecutive type infix operations
, all operators  must have the same
associativity. If they are all left-associative, the sequence is
interpreted as ,
otherwise it is interpreted as .

Function Types


lstlisting
  Type              ::=  FunctionArgs `=>' Type
  FunctionArgs      ::=  InfixType
                        `(' [ ParamType `,' ParamType  ] `)'

The type  () => @  represents the set of function
values that take arguments of types  and yield
results of type .  In the case of exactly one argument type
  => @  is a shorthand for  () => @.
An argument type of the form T@
represents a call-by-name parameter (sec:by-name-params) of type .

Function types associate to the right, e.g.
  =>  => @  is the same as
  => ( => )@.

Function types are shorthands for class types that define apply
functions.  Specifically, the -ary function type
 () => U@  is a shorthand for the class type
[,]@. Such class
types are defined in the Scala library for  between 0 and 9 as follows.

package scala
trait Function[- -, +]
  def apply(: : ):
  override def toString = "<function>"


Hence, function types are covariant (sec:variances) in their
result type and contravariant in their argument types.


Existential Types


lstlisting
  Type               ::= InfixType ExistentialClauses
  ExistentialClauses ::= `forSome' `' ExistentialDcl
                         semi ExistentialDcl `'
  ExistentialDcl     ::= `type' TypeDcl
                        `val' ValDcl

An existential type has the form   forSome @
where  is a sequence of type declarations sec:typedcl.
Let
be the types declared in  (any of the
type parameter sections []@ might be missing).
The scope of each type  includes the type  and the existential clause .
The type variables  are said to be bound in the type   forSome @.
Type variables which occur in a type  but which are not bound in  are said
to be free in .

A type instance of   forSome @
is a type  where  is a substitution over
such that, for each , .
The set of values denoted by the existential type   forSome @
is the union of the set of values of all its type instances.

A skolemization of   forSome @  is
a type instance , where  is the substitution
 and each  is a fresh abstract type
with lower bound  and upper bound .

*Simplification Rules

Existential types obey the following four equivalences:


Multiple for-clauses in an existential type can be merged. E.g.,
  forSome  forSome @
is equivalent to
  forSome ;@.

Unused quantifications can be dropped. E.g.,
  forSome ;@
where none of the types defined in  are referred to by  or ,
is equivalent to
  forSome @.

An empty quantification can be dropped. E.g.,
  forSome  @  is equivalent to  @.

An existential type   forSome @  where  contains
a clause  @ is equivalent
to the type   forSome @  where  results from  by replacing every
covariant occurrence (sec:variances) of  in  by  and by replacing every
contravariant occurrence of  in  by .


*Existential Quantification over Values

As a syntactic convenience, the bindings clause
in an existential type may also contain
value declarations : @.
An existential type   forSome  ; val : ; @
is treated as a shorthand for the type
  forSome  ; type  <:  with Singleton;  @, where  is a fresh
type name and  results from  by replacing every occurrence of
.type@ with .

*Placeholder Syntax for Existential Types

lstlisting
  WildcardType   ::=  `_' TypeBounds


Scala supports a placeholder syntax for existential types.
A wildcard type is of the form  _>:<:@. Both bound
clauses may be omitted. If a lower bound clause >:@ is missing,
>:scala.Nothing@
is assumed. If an upper bound clause  <:@ is missing,
<:scala.Any@  is assumed. A wildcard type is a shorthand for an
existentially quantified type variable, where the existential quantification is implicit.

A wildcard type must appear as type argument of a parameterized type.
Let  be a parameterized type where  may be empty and
 is a wildcard type  _>:<:@. Then  is equivalent to the existential
type

    forSome  type  >:  <:

where  is some fresh type variable.
Wildcard types may also appear as parts of infix types
(sec:infix-types), function types (sec:function-types),
or tuple types (sec:tuple-types).
Their expansion is then the expansion in the equivalent parameterized
type.

Assume the class definitions

class Ref[T]
abstract class Outer  type T  .

Here are some examples of existential types:

Ref[T] forSome  type T <: java.lang.Number
Ref[x.T] forSome  val x: Outer
Ref[x_type # T] forSome  type x_type <: Outer with Singleton

The last two types in this list are equivalent.
An alternative formulation of the first type above using wildcard syntax is:

Ref[_ <: java.lang.Number]


The type [List[_]]@ is equivalent to the existential type

List[List[t] forSome  type t ] .


Assume a covariant type

class List[+T]

The type

List[T] forSome  type T <: java.lang.Number

is equivalent (by simplification rule 4 above) to

List[java.lang.Number] forSome  type T <: java.lang.Number

which is in turn equivalent (by simplification rules 2 and 3 above) to
[java.lang.Number]@.

Non-Value Types


The types explained in the following do not denote sets of values, nor
do they appear explicitly in programs. They are introduced in this
report as the internal types of defined identifiers.

Method Types


A method type is denoted internally as , where  is a
sequence of parameter names and types
for some  and  is a (value or method) type.  This type
represents named methods that take arguments named
of types
and that return a result of type .

Method types associate to the right:  is
treated as .

A special case are types of methods without any parameters. They are
written here T@. Parameterless methods name expressions
that are re-evaluated each time the parameterless method name is
referenced.

Method types do not exist as types of values. If a method name is used
as a value, its type is implicitly converted to a corresponding
function type (sec:impl-conv).

The declarations

def a: Int
def b (x: Int): Boolean
def c (x: Int) (y: String, z: String): String

produce the typings

a: => Int
b: (Int) Boolean
c: (Int) (String, String) String


Polymorphic Method Types


A polymorphic method type is denoted internally as  []@  where
[]@ is a type parameter section
 [ >:  <:  >:  <: ]@
for some  and  is a
(value or method) type.  This type represents named methods that
take type arguments  @  which
conform (sec:param-types) to the lower bounds
 @  and the upper bounds
 @  and that yield results of type .

The declarations

def empty[A]: List[A]
def union[A <: Comparable[A]] (x: Set[A], xs: Set[A]): Set[A]

produce the typings

empty : [A >: Nothing <: Any] List[A]
union : [A >: Nothing <: Comparable[A]] (x: Set[A], xs: Set[A]) Set[A]  .


Type Constructors

A type constructor is represented internally much like a polymorphic method type.
 [  >:  <:  >:  <: ] @  represents a type that is expected by a type constructor parameter (sec:type-params) or an abstract type constructor binding (sec:typedcl) with the corresponding type parameter clause.

Consider this fragment of the [+X]@ class:

trait Iterable[+X]
  def flatMap[newType[+X] <: Iterable[X], S](f: X => newType[S]): newType[S]



Conceptually, the type constructor is a name for the anonymous type [+X] Iterable[X]@, which may be passed to the type constructor parameter in .


Overloaded Types


More than one values or methods are defined in the same scope with the
same name, we model

An overloaded type consisting of type alternatives
 is denoted internally .

The definitions

def println: Unit
def println(s: String): Unit =
def println(x: Float): Unit =
def println(x: Float, width: Int): Unit =
def println[A](x: A)(tostring: A => String): Unit =

define a single function println which has an overloaded
type.

println:  => Unit
          (String) Unit
          (Float) Unit
          (Float, Int) Unit
          [A] (A) (A => String) Unit


The definitions

def f(x: T): T =
val f = 0

define a function f which has type  (x: T)T  Int@.


Base Types and Member Definitions


Types of class members depend on the way the members are referenced.
Central here are three notions, namely:

the notion of the set of base types of a type ,
the notion of a type  in some class  seen from some
      prefix type ,
the notion of the set of member bindings of some type .

These notions are defined mutually recursively as follows.

1. The set of base types of a type is a set of class types,
given as follows.


The base types of a class type  with parents  are
 itself, as well as the base types of the compound type
  with  with  @.

The base types of an aliased type are the base types of its alias.

The base types of an abstract type are the base types of its upper bound.

The base types of a parameterized type
 []@  are the base types
of type , where every occurrence of a type parameter
of  has been replaced by the corresponding parameter type .

The base types of a singleton type .type@ are the base types of
the type of .

The base types of a compound type
  with  with  @
are the reduced union of the base
classes of all 's. This means:
Let the multi-set  be the multi-set-union of the
base types of all 's.
If  contains several type instances of the same class, say
 #[]@  , then
all those instances
are replaced by one of them which conforms to all
others. It is an error if no such instance exists. It follows that the reduced union, if it exists,
produces a set of class types, where different types are instances of different classes.

The base types of a type selection #@ are
determined as follows. If  is an alias or abstract type, the
previous clauses apply. Otherwise,  must be a (possibly
parameterized) class type, which is defined in some class .  Then
the base types of #@ are the base types of
in  seen from the prefix type .

The base types of an existential type  forSome @ are
all types  forSome @ where  is a base type of .


2. The notion of a type
in class  seen from some prefix type
 makes sense only if the prefix type
has a type instance of class  as a base type, say
 #[]@. Then we define as follows.


  If  = .type@, then  in  seen from  is  itself.

  Otherwise, if  is an existential type   forSome @, and
   in  seen from  is ,
  then  in  seen from  is   forSome @.

   Otherwise, if  is the 'th type parameter of some class , then


   If  has a base type  []@, for some type parameters
    []@, then  in  seen from  is .

   Otherwise, if  is defined in a class , then
    in  seen from  is the same as  in  seen from .

   Otherwise, if  is not defined in another class, then
    in  seen from  is  itself.


   Otherwise,
   if  is the singleton type .this.type@ for some class
   then


   If  is a subclass of  and
    has a type instance of class  among its base types,
   then  in  seen from  is .

   Otherwise, if  is defined in a class , then
    in  seen from  is the same as  in  seen from .

   Otherwise, if  is not defined in another class, then
    in  seen from  is  itself.


  If  is some other type, then the described mapping is performed
  to all its type components.


If  is a possibly parameterized class type, where 's class
is defined in some other class , and  is some prefix type,
then we use `` seen from '' as a shorthand for
`` in  seen from ''.

3. The member bindings of a type  are (1) all bindings  such that
there exists a type instance of some class  among the base types of
and there exists a definition or declaration  in
such that  results from  by replacing every
type  in  by  in  seen from , and (2) all bindings
of the type's refinement (sec:refinements), if it has one.

The definition of a type projection #@ is the member
binding  of the type  in . In that case, we also say
that #@ is defined by .
share a to
Relations between types

We define two relations between types.
l@l@l
Type equivalence &  &  and  are interchangeable
in all contexts.

Conformance &  & Type  conforms to type .


Type Equivalence


Equivalence  between types is the smallest congruence  A
congruence is an equivalence relation which is closed under formation
of contexts such that the following holds:


If  is defined by a type alias   = @, then  is
equivalent to .

If a path  has a singleton type  .type@, then
 .type .type@.

If  is defined by an object definition, and  is a path
consisting only of package or object selectors and ending in , then
 .this.type .type@.

Two compound types (sec:compound-types) are equivalent if the sequences of their component
are pairwise equivalent, and occur in the same order, and their
refinements are equivalent. Two refinements are equivalent if they
bind the same names and the modifiers, types and bounds of every
declared entity are equivalent in both refinements.

Two method types (sec:method-types) are equivalent if they have equivalent result types,
both have the same number of parameters, and corresponding parameters
have equivalent types.  Note that the names of parameters do not
matter for method type equivalence.

Two polymorphic method types (sec:poly-types) are equivalent if they have the same number of
type parameters, and, after renaming one set of type parameters by
another, the result types as well as lower and upper bounds of
corresponding type parameters are equivalent.

Two existential types (sec:existential-types)
are equivalent if they have the same number of
quantifiers, and, after renaming one list of type quantifiers by
another, the quantified types as well as lower and upper bounds of
corresponding quantifiers are equivalent.

Two type constructors (sec:higherkinded-types) are equivalent if they have the
same number of type parameters, and, after renaming one list of type parameters by
another, the result types as well as variances, lower and upper bounds of
corresponding type parameters are equivalent.


Conformance


The conformance relation  is the smallest
transitive relation that satisfies the following conditions.

Conformance includes equivalence. If  then .
For every value type ,
      .
For every type constructor  (with any number of type parameters),
      .

For every class type  such that
 and not
        one has .
A type variable or abstract type  conforms to its upper bound and
      its lower bound conforms to .
A class type or parameterized type conforms to any of its
  base-types.
A singleton type .type@ conforms to the type of
  the path .
A singleton type .type@ conforms to the type .
A type projection #@ conforms to #@ if
       conforms to .
A parameterized type  []@  conforms to
       []@  if
      the following three conditions hold for .


      If the 'th type parameter of  is declared covariant, then .

      If the 'th type parameter of  is declared contravariant, then .

      If the 'th type parameter of  is declared neither covariant
      nor contravariant, then .

A compound type   with  with  @  conforms to
      each of its component types .
If  for  and for every
      binding  of a type or value  in  there exists a member
      binding of  in  which subsumes , then  conforms to the
      compound type   with  with  @.
The existential type   forSome @ conforms to
       if its skolemization (sec:existential-types)
      conforms to .
The type  conforms to the existential type   forSome @
      if  conforms to one of the type instances (sec:existential-types)
      of   forSome @.
If
         for  and  conforms to
        then the method type  conforms to
        .
The polymorphic type
 conforms to the polymorphic type
 if, assuming

one has  and  and
for .

Type constructors  and  follow a similar discipline. We characterize  and  by their type parameter clauses
 and
, where an  or  may include a variance annotation, a higher-order type parameter clause, and bounds. Then,  conforms to  if any list  -- with declared variances, bounds and higher-order type parameter clauses -- of valid type arguments for  is also a valid list of type arguments for  and . Note that this entails that:


      The bounds on  must be weaker than the corresponding bounds declared for .

      The variance of  must match the variance of , where covariance matches covariance, contravariance matches contravariance and any variance matches invariance.

      Recursively, these restrictions apply to the corresponding higher-order type parameter clauses of  and .




A declaration or definition in some compound type of class type
subsumes another
declaration of the same name in some compound type or class type , if one of the following holds.


A value declaration or definition that defines a name  with type  subsumes
a value or method declaration that defines  with type , provided .

A method declaration or definition that defines a name  with type  subsumes
a method declaration that defines  with type , provided .

A type alias
 subsumes a type alias  if
.

A type declaration  [] >:  <: @  subsumes
a type declaration  [] >:  <: @  if  and
.

A type or class definition that binds a type name  subsumes an abstract
type declaration  t[] >: L <: U@  if
.


The  relation forms pre-order between types,
i.e. it is transitive and reflexive.
least upper bounds and greatest lower bounds of a set of types
are understood to be relative to that order.

Note The least upper bound or greatest lower bound
of a set of types does not always exist. For instance, consider
the class definitions

class A[+T]
class B extends A[B]
class C extends A[C]

Then the types  [Any], A[A[Any]], A[A[A[Any]]], ...@  form
a descending sequence of upper bounds for B and C. The
least upper bound would be the infinite limit of that sequence, which
does not exist as a Scala type. Since cases like this are in general
impossible to detect, a Scala compiler is free to reject a term
which has a type specified as a least upper or greatest lower bound,
and that bound would be more complex than some compiler-set
limit The current Scala compiler limits the nesting level
of parameterization in such bounds to be at most two deeper than the maximum
nesting level of the operand types.

The least upper bound or greatest lower bound might also not be
unique. For instance A with B and B with A are both
greatest lower of A and B. If there are several
least upper bounds or greatest lower bounds, the Scala compiler is
free to pick any one of them.

Weak Conformance

In some situations Scala uses a more genral conformance relation. A
type  weakly conforms
to a type , written
, if  or both  and  are primitive number types
and  precedes  in the following ordering.

Byte  Short
Short  Int
Char  Int
Int  Long
Long  Float
Float  Double


A weak least upper bound is a least upper bound with respect to
weak conformance.

Volatile Types


Type volatility approximates the possibility that a type parameter or abstract type instance
of a type does not have any non-null values.  As explained in
(sec:paths), a value member of a volatile type cannot appear in
a path.

A type is volatile if it falls into one of four categories:

A compound type   with  with  @
is volatile if one of the following two conditions hold.

One of  is a type parameter or abstract type, or
 is an abstract type and and either the refinement
  or a type  for  contributes an abstract member
  to the compound type, or
one of  is a singleton type.

Here, a type  contributes an abstract member to a type  if
 contains an abstract member that is also a member of .
A refinement  contributes an abstract member to a type  if
contains an abstract declaration which is also a member of .

A type designator is volatile if it is an alias of a volatile type, or
if it designates a type parameter or abstract type that has a volatile type as its
upper bound.

A singleton type .type@ is volatile, if the underlying
type of path  is volatile.

An existential type   forSome @  is volatile if
 is volatile.

Type Erasure


A type is called generic if it contains type arguments or type variables.
Type erasure is a mapping from (possibly generic) types to
non-generic types. We write  for the erasure of type .
The erasure mapping is defined as follows.

The erasure of an alias type is the erasure of its right-hand side.
The erasure of an abstract type is the erasure of its upper bound.
The erasure of the parameterized type .Array@ is
 .Array@.
 The erasure of every other parameterized type  is .
The erasure of a singleton type .type@ is the
      erasure of the type of .
The erasure of a type projection #@ is #@.
The erasure of a compound type
  with  with  @ is the erasure of the intersection dominator of
  .
The erasure of an existential type   forSome @
      is .


The intersection dominator of a list of types
 is computed as follows.
Let  be the subsequence of types
which are not supertypes of some other type .
If this subsequence contains a type designator  that refers to a class which is not a trait,
the intersection dominator is . Otherwise, the intersection
dominator is the first element of the subsequence, .


Basic Declarations and Definitions


lstlisting
  Dcl               ::=  `val' ValDcl
                        `var' VarDcl
                        `def' FunDcl
                        `type' nl TypeDcl
  PatVarDef         ::=  `val' PatDef
                        `var' VarDef
  Def               ::=  PatVarDef
                        `def' FunDef
                        `type' nl TypeDef
                        TmplDef


A declaration introduces names and assigns them types. It can
form part of a class definition (sec:templates) or of a
refinement in a compound type (sec:refinements).

A definition introduces names that denote terms or types. It can
form part of an object or class definition or it can be local to a
block.  Both declarations and definitions produce bindings that
associate type names with type definitions or bounds, and that
associate term names with types.

The scope of a name introduced by a declaration or definition is the
whole statement sequence containing the binding.  However, there is a
restriction on forward references in blocks: In a statement sequence
 making up a block, if a simple name in  refers
to an entity defined by  where , then for all
between and including  and ,

 cannot be a variable definition.
If  is a value definition, it must be lazy.



Every basic definition may introduce several defined names, separated
by commas. These are expanded according to the following scheme:
lcl
;x, y: T = e && ; x: T = e
                 && ; y: T = x [0.5em]

;x, y: T = e && ; x: T = e
                 && ; y: T = x [0.5em]

;x, y (ps): T = e &expands to& ; x(ps): T = e
                      && ; y(ps): T = x(ps)[0.5em]

;x, y: T := e && ;x: T := e
                  && ;y: T := x[0.5em]

;t,u = T && ; t = T
              && ; u = t[0.5em]


All definitions have a ``repeated form'' where the initial
definition keyword is followed by several constituent definitions
which are separated by commas.  A repeated definition is
always interpreted as a sequence formed from the
constituent definitions. E.g. the function definition
 f(x) = x, g(y) = y@  expands to
 f(x) = x; def g(y) = y@  and
the type definition
 T, U <: B@  expands to
 T; type U <: B@.


If an element in such a sequence introduces only the defined name,
possibly with some type or value parameters, but leaves out any
additional parts in the definition, then those parts are implicitly
copied from the next subsequent sequence element which consists of
more than just a defined name and parameters. Examples:

[]
The variable declaration  x, y: Int@
expands to  x: Int; var y: Int@.
[]
The value definition  x, y: Int = 1@
expands to  x: Int = 1; val y: Int = 1@.
[]
The class definition  class X(), Y(n: Int) extends Z@  expands to
 class X extends Z; case class Y(n: Int) extends Z@.

The object definition  object Red, Green, Blue extends Color@
expands to

case object Red extends Color
case object Green extends Color
case object Blue extends Color .



Value Declarations and Definitions


lstlisting
  Dcl          ::=  `val' ValDcl
  ValDcl       ::=  ids `:' Type
  Def          ::=  `val' PatDef
  PatDef       ::=  Pattern2 `,' Pattern2 [`:' Type] `=' Expr
  ids          ::=  id `,' id


A value declaration  : @  introduces  as a name of a value of
type .

A value definition  :  = @  defines  as a
name of the value that results from the evaluation of .
If the value definition is not recursive, the type
 may be omitted, in which case the packed type (sec:expr-typing) of expression  is
assumed.  If a type  is given, then  is expected to conform to
it.

Evaluation of the value definition implies evaluation of its
right-hand side , unless it has the modifier .  The
effect of the value definition is to bind  to the value of
converted to type . A value definition evaluates
its right hand side  the first time the value is accessed.

A constant value definition is of the form

final val x = e

where is a constant expression
(sec:constant-expression).
The modifier must be
present and no type annotation may be given. References to the
constant value are themselves treated as constant expressions; in the
generated code they are replaced by the definition's right-hand side .

Value definitions can alternatively have a pattern
(sec:patterns) as left-hand side.  If  is some pattern other
than a simple name or a name followed by a colon and a type, then the
value definition   = @  is expanded as follows:

1. If the pattern  has bound variables , where :

val  =  match case  =>
val  = ._1

val  = ._n  .

Here,  is a fresh name.

2. If  has a unique bound variable :

val  =  match  case  =>


3. If  has no bound variables:

 match  case  => ()



The following are examples of value definitions

val pi = 3.1415
val pi: Double = 3.1415   // equivalent to first definition
val Some(x) = f()         // a pattern definition
val x :: xs = mylist      // an infix pattern definition


The last two definitions have the following expansions.

val x = f() match  case Some(x) => x

val x = mylist match  case x :: xs => x, xs
val x = x._1
val xs = x._2


The name of any declared or defined value may not end in _=@.

A value declaration  : @
is a
shorthand for the sequence of value declarations
 : ; ...; val : @.
A value definition   = @
is a
shorthand for the sequence of value definitions
  = ; ...; val  = @.
A value definition   = @
is a
shorthand for the sequence of value definitions
  = ; ...; val  = @.

Variable Declarations and Definitions


lstlisting
  Dcl            ::=  `var' VarDcl
  Def            ::=  `var' VarDef
  VarDcl         ::=  ids `:' Type
  VarDef         ::=  PatDef
                     ids `:' Type `=' `_'


A variable declaration  : @  is equivalent to declarations
of a getter function  and a setter function
_=@, defined as follows:


  def :
  def _= (: ): Unit


An implementation of a class containing variable declarations
may define these variables using variable definitions, or it may
define setter and getter functions directly.

A variable definition  :  = @  introduces a
mutable variable with type  and initial value as given by the
expression . The type  can be omitted, in which case the type of
 is assumed. If  is given, then  is expected to conform to it
(sec:expr-typing).

Variable definitions can alternatively have a pattern
(sec:patterns) as left-hand side.  A variable definition
   = @  where  is a pattern other
than a simple name or a name followed by a colon and a type is expanded in the same way
(sec:valdef)
as a value definition    = @, except that
the free names in  are introduced as mutable variables, not values.

The name of any declared or defined variable may not end in _=@.

A variable definition  :  = _@  can appear only
as a member of a template. It introduces a mutable field with type
  and a default initial value.  The default value depends on the
type  as follows:
ll
0 & if  is Int or one of its subrange types,
0L & if  is Long,
0.0f@ & if  is Float,
0.0d@ & if  is Double,
false & if  is Boolean,
@ & if  is Unit,
null & for all other types .

When they occur as members of a template, both forms of variable
definition also introduce a getter function  which returns the
value currently assigned to the variable, as well as a setter function
_=@ which changes the value currently assigned to the variable.
The functions have the same signatures as for a variable declaration.
The template then has these getter and setter functions as
members, whereas the original variable cannot be accessed directly as
a template member.

The following example shows how properties can be
simulated in Scala. It defines a class TimeOfDayVar of time
values with updatable integer fields representing hours, minutes, and
seconds. Its implementation contains tests that allow only legal
values to be assigned to these fields. The user code, on the other
hand, accesses these fields just like normal variables.


class TimeOfDayVar
  private var h: Int = 0
  private var m: Int = 0
  private var s: Int = 0

  def hours              =  h
  def hours_= (h: Int)   =  if (0 <= h && h < 24) this.h = h
                            else throw new DateError()

  def minutes            =  m
  def minutes_= (m: Int) =  if (0 <= m && m < 60) this.m = m
                            else throw new DateError()

  def seconds            =  s
  def seconds_= (s: Int) =  if (0 <= s && s < 60) this.s = s
                            else throw new DateError()

val d = new TimeOfDayVar
d.hours = 8; d.minutes = 30; d.seconds = 0
d.hours = 25                  // throws a DateError exception


A variable declaration  : @
is a
shorthand for the sequence of variable declarations
 : ; ...; var : @.
A variable definition   = @
is a
shorthand for the sequence of variable definitions
  = ; ...; var  = @.
A variable definition   = @
is a
shorthand for the sequence of variable definitions
  = ; ...; var  = @.

Type Declarations and Type Aliases



Higher-kinded tdecls should have a separate section

lstlisting
  Dcl             ::=  `type' nl TypeDcl
  TypeDcl         ::=  id [TypeParamClause] [`>:' Type] [`<:' Type]
  Def             ::=  type nl TypeDef
  TypeDef         ::=  id [TypeParamClause] `=' Type



A type declaration  [] >:  <: @  declares
 to be an abstract type with lower bound type  and upper bound
type . If the type parameter clause []@ is omitted,  abstracts over a first-order type, otherwise  stands for a type constructor that accepts type arguments as described by the type parameter clause.


If a type declaration appears as a member declaration of a
type, implementations of the type may implement  with any type
for which . It is a compile-time error if
 does not conform to .  Either or both bounds may be omitted.
If the lower bound  is absent, the bottom type
.Nothing@ is assumed.  If the upper bound  is absent,
the top type .Any@ is assumed.


A type constructor declaration imposes additional restrictions on the
concrete types for which  may stand. Besides the bounds  and
, the type parameter clause may impose higher-order bounds and
variances, as governed by the conformance of type constructors
(sec:conformance).


The scope of a type parameter extends over the bounds  >:  <: @ and the type parameter clause  itself. A
higher-order type parameter clause (of an abstract type constructor
) has the same kind of scope, restricted to the declaration of the
type parameter .

To illustrate nested scoping, these declarations are all equivalent:  t[m[x] <: Bound[x], Bound[x]]@,  t[m[x] <: Bound[x], Bound[y]]@ and  t[m[x] <: Bound[x], Bound[_]]@, as the scope of, e.g., the type parameter of  is limited to the declaration of . In all of them,  is an abstract type member that abstracts over two type constructors:  stands for a type constructor that takes one type parameter and that must be a subtype of , 's second type constructor parameter.  [MutableList, Iterable]@ is a valid use of .

A type alias   = @  defines  to be an alias
name for the type .  The left hand side of a type alias may
have a type parameter clause, e.g.  [] = @.  The scope
of a type parameter extends over the right hand side  and the
type parameter clause  itself.

The scope rules for definitions (sec:defs) and type parameters
(sec:funsigs) make it possible that a type name appears in its
own bound or in its right-hand side.  However, it is a static error if
a type alias refers recursively to the defined type constructor itself.
That is, the type  in a type alias  [] = @  may not
refer directly or indirectly to the name .  It is also an error if
an abstract type is directly or indirectly its own upper or lower bound.

The following are legal type declarations and definitions:

type IntList = List[Integer]
type T <: Comparable[T]
type Two[A] = Tuple2[A, A]
type MyCollection[+X] <: Iterable[X]


The following are illegal:

type Abs = Comparable[Abs]        // recursive type alias

type S <: T                       // S, T are bounded by themselves.
type T <: S

type T >: Comparable[T.That]      // Cannot select from T.
                                  // T is a type, not a value
type MyCollection <: Iterable     // Type constructor members must explicitly state their type parameters.


If a type alias  [] = @  refers to a class type
, the name  can also be used as a constructor for
objects of type .

The Predef object contains a definition which establishes Pair
as an alias of the parameterized class Tuple2:

type Pair[+A, +B] = Tuple2[A, B]
object Pair
  def apply[A, B](x: A, y: B) = Tuple2(x, y)
  def unapply[A, B](x: Tuple2[A, B]): Option[Tuple2[A, B]] = Some(x)


As a consequence, for any two types  and , the type
 [, ]@  is equivalent to the type  2[, ]@.
Pair can also be used as a constructor instead of Tuple2, as in:

val x: Pair[Int, String] = new Pair(1, "abc")


Type Parameters

lstlisting
  TypeParamClause  ::= `[' VariantTypeParam `,' VariantTypeParam `]'
  VariantTypeParam ::= Annotation [`+'  `-'] TypeParam
  TypeParam        ::= (id  `_') [TypeParamClause] [`>:' Type] [`<:' Type] [`:' Type]


Type parameters appear in type definitions, class definitions, and
function definitions.  In this section we consider only type parameter
definitions with lower bounds  >: @  and upper bounds
 <: @  whereas a discussion of context bounds
 : @  and view bounds  <
is deferred to Section .

The most general form of a first-order type parameter is
 !   >:  <: !.
Here, , and  are lower and upper bounds that
constrain possible type arguments for the parameter.  It is a
compile-time error if  does not conform to .  is a
variance, i.e. an optional prefix of either +@, or
One or more annotations may precede the type parameter.


The upper bound  in a type parameter clauses may not be a final
class. The lower bound may not denote a value type.Why


@M TODO this is a pretty awkward description of scoping and distinctness of binders
The names of all type parameters must be pairwise different in their enclosing type parameter clause.  The scope of a type parameter includes in each case the whole type parameter clause. Therefore it is possible that a type parameter appears as part of its own bounds or the bounds of other type parameters in the same clause.  However, a type parameter may not be bounded directly or indirectly by itself.

A type constructor parameter adds a nested type parameter clause to the type parameter. The most general form of a type constructor parameter is  !   >:  <: !.

The above scoping restrictions are generalized to the case of nested type parameter clauses, which declare higher-order type parameters. Higher-order type parameters (the type parameters of a type parameter ) are only visible in their immediately surrounding parameter clause (possibly including clauses at a deeper nesting level) and in the bounds of . Therefore, their names must only be pairwise different from the names of other visible parameters. Since the names of higher-order type parameters are thus often irrelevant, they may be denoted with a `_@', which is nowhere visible.

Here are some well-formed type parameter clauses:

[S, T]
[@specialized T, U]
[Ex <: Throwable]
[A <: Comparable[B], B <: A]
[A, B >: A, C >: A <: B]
[M[X], N[X]]
[M[_], N[_]] // equivalent to previous clause
[M[X <: Bound[X]], Bound[_]]
[M[+X] <: Iterable[X]]

The following type parameter clauses are illegal:

[A >: A]                  // illegal, `A' has itself as bound
[A <: B, B <: C, C <: A]  // illegal, `A' has itself as bound
[A, B, C >: A <: B]       // illegal lower bound `A' of `C' does
                          // not conform to upper bound `B'.


Variance Annotations

Variance annotations indicate how instances of parameterized types
vary with respect to subtyping (sec:conformance).  A
`+@' variance indicates a covariant dependency, a
`variance indicates a contravariant dependency, and a
missing variance indication indicates an invariant dependency.


A variance annotation constrains the way the annotated type variable
may appear in the type or class which binds the type parameter.  In a
type definition  [] = @, or a type
declaration  [] >:  <: @  type parameters labeled
`+@' must only appear in covariant position whereas
type parameters labeled `must only appear in contravariant
position. Analogously, for a class definition
 []() extends   :  => ...@,
type parameters labeled
`+@' must only appear in covariant position in the
self type  and the template , whereas type
parameters labeled `must only appear in contravariant
position.

The variance position of a type parameter in a type or template is
defined as follows.  Let the opposite of covariance be contravariance,
and the opposite of invariance be itself.  The top-level of the type
or template is always in covariant position. The variance position
changes at the following constructs.


The variance position of a method parameter is the opposite of the
variance position of the enclosing parameter clause.

The variance position of a type parameter is the opposite of the
variance position of the enclosing type parameter clause.

The variance position of the lower bound of a type declaration or type parameter
is the opposite of the variance position of the type declaration or parameter.

The type of a mutable variable is always in invariant position.

The prefix  of a type selection #@ is always in invariant position.

For a type argument  of a type  [ ]@: If the
corresponding type parameter is invariant, then  is in
invariant position.  If the corresponding type parameter is
contravariant, the variance position of  is the opposite of
the variance position of the enclosing type  [ ]@.

handle type aliases
References to the type parameters in object-private values, variables,
or methods (sec:modifiers) of the class are not checked for their variance
position. In these members the type parameter may appear anywhere
without restricting its legal variance annotations.

The following variance annotation is legal.

abstract class P[+A, +B]
  def fst: A; def snd: B


With this variance annotation, type instances
of  subtype covariantly with respect to their arguments.
For instance,

P[IOException, String] <: P[Throwable, AnyRef] .


If the members of  are mutable variables,
the same variance annotation becomes illegal.

abstract class Q[+A, +B](x: A, y: B)
  var fst: A = x           // **** error: illegal variance:
  var snd: B = y           // `A', `B' occur in invariant position.


If the mutable variables are object-private, the class definition
becomes legal again:

abstract class R[+A, +B](x: A, y: B)
  private[this] var fst: A = x        // OK
  private[this] var snd: B = y        // OK



The following variance annotation is illegal, since  appears
in contravariant position in the parameter of append:


abstract class Sequence[+A]
  def append(x: Sequence[A]): Sequence[A]
                  // **** error: illegal variance:
                  // `A' occurs in contravariant position.


The problem can be avoided by generalizing the type of append
by means of a lower bound:


abstract class Sequence[+A]
  def append[B >: A](x: Sequence[B]): Sequence[B]



Here is a case where a contravariant type parameter is useful.


abstract class OutputChannel[-A]
  def write(x: A): Unit


With that annotation, we have that
[AnyRef]@ conforms to [String]@.
That is, a
channel on which one can write any object can substitute for a channel
on which one can write only strings.

Function Declarations and Definitions


lstlisting
Dcl                ::=  `def' FunDcl
FunDcl             ::=  FunSig `:' Type
Def                ::=  `def' FunDef
FunDef             ::=  FunSig [`:' Type] `=' Expr
FunSig             ::=  id [FunTypeParamClause] ParamClauses
FunTypeParamClause ::=  `[' TypeParam `,' TypeParam `]'
ParamClauses       ::=  ParamClause [[nl] `(' `implicit' Params `)']
ParamClause        ::=  [nl] `(' [Params] `)'
Params             ::=  Param `,' Param
Param              ::=  Annotation id [`:' ParamType] [`=' Expr]
ParamType          ::=  Type
                       `=>' Type
                       Type `*'


A function declaration has the form  : @, where
 is the function's name,  is its parameter
signature and  is its result type. A function definition
 :  = @  also includes a function body ,
i.e. an expression which defines the function's result.  A parameter
signature consists of an optional type parameter clause []@,
followed by zero or more value parameter clauses
 ()()@.  Such a declaration or definition
introduces a value with a (possibly polymorphic) method type whose
parameter types and result type are as given.

The type of the function body is expected to conform (sec:expr-typing)
to the function's declared
result type, if one is given. If the function definition is not
recursive, the result type may be omitted, in which case it is
determined from the packed type of the function body.

A type parameter clause  consists of one or more type
declarations (sec:typedcl), which introduce type parameters,
possibly with bounds.  The scope of a type parameter includes
the whole signature, including any of the type parameter bounds as
well as the function body, if it is present.

A value parameter clause  consists of zero or more formal
parameter bindings such as : @ or @, which bind value
parameters and associate them with their types. Each value parameter
declaration may optionally define a default argument. The default argument
expression  is type-checked with an expected type  obtained
by replacing all occurences of the function's type parameters in  by
the undefined type.

For every parameter  with a default argument a method named
defaultn@ is generated which computes the default argument
expression. Here,  denotes the parameter's position in the method
declaration. These methods are parametrized by the type parameter clause
[]@ and all value parameter clauses
 ()()@ preceeding .
The defaultn@ methods are inaccessible for
user programs.

The scope of a formal value parameter name  comprises all subsequent parameter
clauses, as well as the method return type and the function body, if
they are given. However, at present singleton types of method
parameters may only appear in the method body; so dependent method
types are not supported. Both type parameter names
and value parameter names must be pairwise distinct.

In the method

def compare[T](a: T = 0)(b: T = a) = (a == b)

the default expression 0 is type-checked with an undefined expected
type. When applying compare(), the default value 0 is inserted
and T is instantiated to Int. The methods computing the default
arguments have the form:

def comparedefault1[T]: Int = 0
def comparedefault2[T](a: T): T = a


By-Name Parameters

lstlisting
ParamType          ::=  `=>' Type


The type of a value parameter may be prefixed by =>, e.g.
 : => @. The type of such a parameter is then the
parameterless method type  @. This indicates that the
corresponding argument is not evaluated at the point of function
application, but instead is evaluated at each use within the
function. That is, the argument is evaluated using call-by-name.

The by-name modifier is disallowed for parameters of classes that
carry a val or var prefix, including parameters of case
classes for which a val prefix is implicitly generated. The
by-name modifier is also disallowed for implicit parameters (sec:impl-params).

The declaration

def whileLoop (cond: => Boolean) (stat: => Unit): Unit

indicates that both parameters of whileLoop are evaluated using
call-by-name.

Repeated Parameters

lstlisting
ParamType          ::=  Type `*'


The last value parameter of a parameter section may be suffixed by
``*'', e.g.  (..., :*)@.  The type of such a
repeated parameter inside the method is then the sequence type
.Seq[]@.  Methods with repeated parameters
*@ take a variable number of arguments of type .
That is, if a method  with type  (
*)@  is applied to arguments  where
, then  is taken in that application to have type
, with  occurrences of type
 where any parameter names beyond  are fresh. The only exception to this rule is if the last argument is
marked to be a sequence argument via a _*@ type
annotation. If  above is applied to arguments
 (: _*)@, then the type of  in
that application is taken to be
 (scala.Seq[])@.

It is not allowed to define any default arguments in a parameter section
with a repeated parameter.

The following method definition computes the sum of the squares of a variable number
of integer arguments.

def sum(args: Int*) =
  var result = 0
  for (arg <- args) result += arg * arg
  result


The following applications of this method yield 0, 1,
6, in that order.

sum()
sum(1)
sum(1, 2, 3)

Furthermore, assume the definition:

val xs = List(1, 2, 3)

The following application of method is ill-formed:

sum(xs)       // ***** error: expected: Int, found: List[Int]

By contrast, the following application is well formed and yields again
the result 6:

sum(xs: _*)


Procedures

lstlisting
  FunDcl   ::=  FunSig
  FunDef   ::=  FunSig [nl] `' Block `'


Special syntax exists for procedures, i.e. functions that return the
value @.
A procedure declaration is a function declaration where the result type
is omitted. The result type is then implicitly completed to the
type. E.g.,  ()@  is equivalent to
 (): Unit@.

A procedure definition is a function definition where the result type
and the equals sign are omitted; its defining expression must be a block.
E.g.,  () @  is equivalent to
 (): Unit = @.

Here is a declaration and a definition of a procedure named :

trait Writer
  def write(str: String)

object Terminal extends Writer
  def write(str: String)  System.out.println(str)


The code above is implicitly completed to the following code:

trait Writer
  def write(str: String): Unit

object Terminal extends Writer
  def write(str: String): Unit =  System.out.println(str)



Method Return Type Inference


Functions that are members of a class  may define parameters
without type annotations. The types of such parameters are inferred as
follows.  Say, a method  in a class  has a parameter  which
does not have a type annotation. We first determine methods  in
 that might be overridden (sec:overriding) by , assuming
that appropriate types are assigned to all parameters of  whose
types are missing.  If there is exactly one such method, the type of
the parameter corresponding to  in that method -- seen as a member
of  -- is assigned to . It is a compile-time error if there are
several such overridden methods , or if there is none.


A class member definition  that overrides some other function
in a base class of  may leave out the return type, even if it is
recursive. In this case, the return type  of the overridden
function , seen as a member of , is taken as the return type of
 for each recursive invocation of . That way, a type  for the
right-hand side of  can be determined, which is then taken as the
return type of . Note that  may be different from , as long
as  conforms to .


Assume the following definitions:

trait I[A]
  def f(x: A)(y: A): A

class C extends I[Int]
  def f(x)(y) = x + y


Here, the parameter and return types of in are
inferred from the corresponding types of in . The
signature of in is thus inferred to be

  def f(x: Int)(y: Int): Int



Assume the following definitions:

trait I
  def factorial(x: Int): Int

class C extends I
  def factorial(x: Int) = if (x == 0) 1 else x * factorial(x - 1)


Here, it is OK to leave out the result type of
in , even though the method is recursive.



For any index  let  be a function signature consisting of a function
name, an optional type parameter section, and zero or more parameter
sections.  Then a function declaration
 : @
is a shorthand for the sequence of function
declarations  : ; ...; def : @.
A function definition   = @  is a
shorthand for the sequence of function definitions
  = ; ...; def  = @.
A function definition
  = @  is a shorthand for the
sequence of function definitions
  = ; ...; def  = @.



Overloaded Definitions

change

An overloaded definition is a set of  value or function
definitions in the same statement sequence that define the same name,
binding it to types  @, respectively.
The individual definitions are called alternatives.  Overloaded
definitions may only appear in the statement sequence of a template.
Alternatives always need to specify the type of the defined entity
completely.  It is an error if the types of two alternatives  and
 have the same erasure (sec:erasure).

Say something about bridge methods.




Import Clauses


lstlisting
  Import          ::= `import' ImportExpr `,' ImportExpr
  ImportExpr      ::= StableId `.' (id  `_'  ImportSelectors)
  ImportSelectors ::= `' ImportSelector `,'
                      (ImportSelector  `_') `'
  ImportSelector  ::= id [`=>' id  `=>' `_']


An import clause has the form  .@  where  is a stable
identifier (sec:paths) and  is an import expression.
The import expression determines a set of names of importable members of
which are made available without qualification.  A member  of  is
importable if it is not object-private (sec:modifiers).
The most general form of an import expression is a list of import
selectors

  =>  => , _  .

for , where the final wildcard `_@' may be absent.  It
makes available each importable member .@ under the unqualified name
. I.e. every import selector   => @  renames
.@ to
.  If a final wildcard is present, all importable members  of
 other than  @  are also made available
under their own unqualified names.

Import selectors work in the same way for type and term members. For
instance, an import clause  . => @  renames the term
name .@ to the term name  and the type name .@
to the type name . At least one of these two names must
reference an importable member of .

If the target in an import selector is a wildcard, the import selector
hides access to the source member. For instance, the import selector
  => _@  ``renames''  to the wildcard symbol (which is
unaccessible as a name in user programs), and thereby effectively
prevents unqualified access to . This is useful if there is a
final wildcard in the same import selector list, which imports all
members not mentioned in previous import selectors.

The scope of a binding introduced by an import-clause starts
immediately after the import clause and extends to the end of the
enclosing block, template, package clause, or compilation unit,
whichever comes first.

Several shorthands exist. An import selector may be just a simple name
. In this case,  is imported without renaming, so the
import selector is equivalent to   => @. Furthermore, it is
possible to replace the whole import selector list by a single
identifier or wildcard. The import clause  .@  is
equivalent to  .@ , i.e. it makes available without
qualification the member  of . The import clause
 ._@  is equivalent to
 ._@,
i.e. it makes available without qualification all members of
(this is analogous to  .*@  in Java).

An import clause with multiple import expressions
 ..@  is interpreted as a
sequence of import clauses
 .; ; import .@.

Consider the object definition:

object M
  def z = 0, one = 1
  def add(x: Int, y: Int): Int = x + y


Then the block

 import M.one, z => zero, _; add(zero, one)

is equivalent to the block

 M.add(M.z, M.one)  .


Classes and Objects


lstlisting
  TmplDef          ::= [`case'] `class' ClassDef
                      [`case'] `object' ObjectDef
                      `trait' TraitDef


Classes (sec:class-defs) and objects
(sec:object-defs) are both defined in terms of templates.

Templates


lstlisting
  ClassTemplate   ::=  [EarlyDefs] ClassParents [TemplateBody]
  TraitTemplate   ::=  [EarlyDefs] TraitParents [TemplateBody]
  ClassParents    ::=  Constr `with' AnnotType
  TraitParents    ::=  AnnotType `with' AnnotType
  TemplateBody    ::=  [nl] `' [SelfType] TemplateStat semi TemplateStat `'
  SelfType        ::=  id [`:' Type] `=>'
                      this `:' Type `=>'


A template defines the type signature, behavior and initial state of a
trait or class of objects or of a single object. Templates form part of
instance creation expressions, class definitions, and object
definitions.  A template
  with  with  with  @
consists of a constructor invocation
which defines the template's superclass, trait references
 @  , which define the
template's traits, and a statement sequence  which
contains initialization code and additional member definitions for the
template.

Each trait reference  must denote a trait (sec:traits).
By contrast, the superclass constructor  normally refers to a
class which is not a trait. It is possible to write a list of
parents that starts with a trait reference, e.g.
  with  with @. In that case the list
of parents is implicitly extended to include the supertype of
as first parent type. The new supertype must have at least one
constructor that does not take parameters.  In the following, we will
always assume that this implicit extension has been performed, so that
the first parent class of a template is a regular superclass
constructor, not a trait reference.

The list of parents of every class is also always implicitly extended
by a reference to the scala.ScalaObject trait as last
mixin. E.g.

 with  with  with

becomes

 with  with   with ScalaObject  .


The list of parents of a template must be well-formed. This means that
the class denoted by the superclass constructor  must be a
subclass of the superclasses of all the traits .
In other words, the non-trait classes inherited by a template form a
chain in the inheritance hierarchy which starts with the template's
superclass.

The least proper supertype of a template is the class type or
compound type (sec:compound-types) consisting of all its parent
class types.

The statement sequence  contains member definitions that
define new members or overwrite members in the parent classes.  If the
template forms part of an abstract class or trait definition, the
statement part  may also contain declarations of abstract
members. If the template forms part of a concrete class definition,
 may still contain declarations of abstract type members, but
not of abstract term members.  Furthermore,  may in any case
also contain expressions; these are executed in the order they are
given as part of the initialization of a template.

The sequence of template statements may be prefixed with a formal
parameter definition and an arrow, e.g.  =>@, or
 : =>@.  If a formal parameter is given, it can be
used as an alias for the reference throughout the
body of the template.
If the formal parameter comes with a type , this definition affects
the self type  of the underlying class or object as follows:  Let  be the type
of the class or trait or object defining the template.
If a type  is given for the formal self parameter,
is the greatest lower bound of  and .
If no type  is given,  is just .
Inside the template, the type of this is assumed to be .

The self type of a class or object must conform to the self types of
all classes which are inherited by the template .

A second form of self type annotation reads just
 :  =>@. It prescribes the type  for
without introducing an alias name for it.

Consider the following class definitions:


class Base extends Object
trait Mixin extends Base
object O extends Mixin

In this case, the definition of O is expanded to:

object O extends Base with Mixin






Make all references to Java generic

Inheriting from Java Types A template may have a Java class as
its superclass and Java interfaces as its mixins.

Template Evaluation
Consider a template   with  with  @.

If this is the template of a trait (sec:traits) then its
mixin-evaluation consists of an evaluation of the statement sequence
.

If this is not a template of a trait, then its evaluation
consists of the following steps.


First, the superclass constructor  is evaluated (sec:constr-invoke).

Then, all base classes in the template's linearization
(sec:linearization) up to the
template's superclass denoted by  are
mixin-evaluated. Mixin-evaluation happens in reverse order of
occurrence in the linearization.

Finally the statement sequence  is evaluated.


Constructor Invocations

lstlisting
  Constr  ::=  AnnotType `(' [Exprs] `)'


Constructor invocations define the type, members, and initial state of
objects created by an instance creation expression, or of parts of an
object's definition which are inherited by a class or object
definition. A constructor invocation is a function application
 .[]()()@, where  is a stable identifier
(sec:stable-ids),  is a type name which either designates a
class or defines an alias type for one,  is a type argument
list,  are argument lists, and there is a
constructor of that class which is applicable (sec:apply)
to the given arguments. If the constructor invocation uses named or
default arguments, it is transformed into a block expression using the
same transformation as described in (sec:named-default).

The prefix `.@' can be omitted.  A type argument list
can be given only if the class  takes type parameters.  Even then
it can be omitted, in which case a type argument list is synthesized
using local type inference (sec:local-type-inf). If no explicit
arguments are given, an empty list ()@ is implicitly supplied.

An evaluation of a constructor invocation
 .[]()()@
consists of the following steps:

First, the prefix  is evaluated.
Then, the arguments  are evaluated from left to right.
Finally, the class being constructed is initialized by evaluating the
  template of the class referred to by .


Class Linearization

The classes reachable through transitive closure of the direct
inheritance relation from a class  are called the
base classes of .  Because of mixins, the inheritance relationship
on base classes forms in general a directed acyclic graph. A
linearization of this graph is defined as follows.

+
[1]L(#1)

 Let  be a class with template
  with ... with    @.
The linearization of ,  is defined as follows:
rcl
C &=& C ,  C_n C_1

Here  denotes concatenation where elements of the right operand
replace identical elements of the left operand:
lcll
a, A B &=& a, (A B)  &if a B
                 &=& A B       &if a B



Consider the following class definitions.

abstract class AbsIterator extends AnyRef  ...
trait RichIterator extends AbsIterator  ...
class StringIterator extends AbsIterator  ...
class Iter extends StringIterator with RichIterator  ...

Then the linearization of class is

 Iter, RichIterator, StringIterator, AbsIterator, ScalaObject, AnyRef, Any

Trait appears in this list because it
is added as last mixin to every Scala class (sec:templates).

Note that the linearization of a class refines the inheritance
relation: if  is a subclass of , then  precedes  in any
linearization where both  and  occur.
 also satisfies the property that a linearization
of a class always contains the linearization of its direct superclass
as a suffix.  For instance, the linearization of
is

 StringIterator, AbsIterator, ScalaObject, AnyRef, Any

which is a suffix of the linearization of its subclass .
The same is not true for the linearization of mixins.
For instance, the linearization of is

 RichIterator, AbsIterator, ScalaObject, AnyRef, Any

which is not a suffix of the linearization of .


Class Members


A class  defined by a template
  with  with    @
can define members in its statement sequence
 and can inherit members from all parent classes.  Scala
adopts Java and C's conventions for static overloading of
methods. It is thus possible that a class defines and/or inherits
several methods with the same name.  To decide whether a defined
member of a class  overrides a member of a parent class, or whether
the two co-exist as overloaded variants in , Scala uses the
following definition of matching on members:


A member definition  matches a member definition , if
and  bind the same name, and one of following holds.

Neither  nor  is a method definition.
 and  define both monomorphic methods with equivalent argument
  types.
 defines a parameterless method and  defines a method
  with an empty parameter list () or vice versa.
 and  define both polymorphic methods with
equal number of argument types ,
and equal numbers of type parameters
, , say, and .





Member definitions fall into two categories: concrete and abstract.
Members of class  are either directly defined (i.e. they appear in
's statement sequence ) or they are inherited.  There are two rules
that determine the set of members of a class, one for each category:


A concrete member of a class  is any concrete definition  in
some class , except if there is a preceding class
 where  which directly defines a concrete member  matching .

An abstract member of a class  is any abstract definition
in some class , except if  contains already a
concrete member  matching , or if there is a preceding class
 where  which directly defines an abstract member  matching
.

This definition also determines the overriding relationships between
matching members of a class  and its parents (sec:overriding).
First, a concrete definition always overrides an abstract definition.  Second, for
definitions  and ' which are both concrete or both abstract,
overrides  if  appears in a class that precedes (in the
linearization of ) the class in which  is defined.

It is an error if a template directly defines two matching members. It
is also an error if a template contains two members (directly defined
or inherited) with the same name and the same erased type (sec:erasure).
Finally, a template is not allowed to contain two methods (directly
defined or inherited) with the same name which both define default arguments.



The type of a member  is determined as follows: If  is defined
in , then its type is the type as given in the member's
declaration or definition. Otherwise, if  is inherited from the
base class  [, . ]@, 's class declaration has formal
parameters  []@, and 's type in  is , then
's type in  is  [ :=  := ]@.


Members of templates have internally qualified names  where
 is a simple name and  is either the empty name , or
is a qualified name referencing the module or class that first
introduces the member. A basic declaration or definition of  in a
module or class  introduces a member with the following qualified
name:


If the binding is labeled with an  @Override
  with qualifier modifier,
where  is a fully qualified name of a base class of , then the
qualified name is the qualified expansion (sec:names) of  in
.

If the binding is labeled with an override modifier without a
base class name, then the qualified name is the qualified expansion
of  in 's least proper supertype (sec:templates).

An implicit override modifier is added and case (2) also
applies if 's least proper supertype contains an abstract member
with simple name .

If no override modifier is given or implied, then if  is
labeled qualified, the qualified name is . If  is
not labeled qualified, the qualified name is .




Consider the trait definitions:


trait A  def f: Int
trait B extends A  def f: Int = 1 ; def g: Int = 2 ; def h: Int = 3
trait C extends A  override def f: Int = 4 ; def g: Int
trait D extends B with C  def h: Int


Then trait D has a directly defined abstract member h. It
inherits member f from trait C and member g from
trait B.

Overriding


Explain that classes cannot override each other

A member  of class  that matches (sec:members)
a non-private member  of a
base class of  is said to override that member.  In this case
the binding of the overriding member  must subsume
(sec:conformance) the binding of the overridden member .
Furthermore, the following restrictions on modifiers apply to  and
:


 must not be labeled final.

 must not be private (sec:modifiers).

If  is labeled  []@  for some enclosing class or package ,
then  must be labeled  []@  for some class or package  where
 equals  or  is contained in . check whether this is accurate

If  is labeled protected, then  must also be
labeled protected.

If  is not an abstract member, then
 must be labeled override.
Furthermore, one of two possibilities must hold:

either  is defined in a subclass of the class where is  is defined,
or both  and  override a third member  which is defined
      in a base class of both the classes containing  and


If  is incomplete (sec:modifiers) in  then  must be
labeled abstract override.

If  and  are both concrete value definitions, then either none
of them is marked lazy or both must be marked lazy.

A special rule concerns parameterless methods. If a paramterless
method defined as :  = ...@ or
 = ...@ overrides a method of
type  which has an empty parameter list, then  is also
assumed to have an empty parameter list.

Another restriction applies to abstract type members: An abstract type
member with a volatile type (sec:volatile-types) as its upper
bound may not override an abstract type member which does not have a
volatile upper bound.

An overriding method inherits all default arguments from the definition
in the superclass. By specifying default arguments in the overriding method
it is possible to add new defaults (if the corresponding parameter in the
superclass does not have a default) or to override the defaults of the
superclass (otherwise).

ex:compound-a
Consider the definitions:

trait Root  type T <: Root
trait A extends Root  type T <: A
trait B extends Root  type T <: B
trait C extends A with B

Then the class definition C is not well-formed because the
binding of T in C is
 T <: B@,
which fails to subsume the binding  T <: A@  of T
in type A. The problem can be solved by adding an overriding
definition of type T in class C:

class C extends A with B  type T <: C


Inheritance Closure

Let  be a class type. The inheritance closure of  is the
smallest set  of types such that


If  is in , then every type  which forms syntactically
a part of  is also in .

If  is a class type in , then all parents (sec:templates)
of  are also in .

It is a static error if the inheritance closure of a class type
consists of an infinite number of types. (This restriction is
necessary to make subtyping decidable
).

Early Definitions

lstlisting
  EarlyDefs         ::= `' [EarlyDef semi EarlyDef] `' `with'
  EarlyDef          ::=  Annotation Modifier PatVarDef


A template may start with an early field definition clause,
which serves to define certain field values before the supertype
constructor is called. In a template

 val :  =
  ...
  val :  =
 with  with  with

The initial pattern definitions of  are called
early definitions. They define fields
which form part of the template. Every early definition must define
at least one variable.

An early definition is type-checked and evaluated in the scope which
is in effect just before the template being defined, augmented by any
type parameters of the enclosing class and by any early definitions
preceding the one being defined. In particular, any reference to
in the right-hand side of an early definition refers
to the identity of just outside the template. Consequently, it
is impossible that an early definition refers to the object being
constructed by the template, or refers to one of its fields and
methods, except for any other preceding early definition in the same
section. Furthermore, references to preceding early definitions
always refer to the value that's defined there, and do not take into account
overriding definitions. In other words, a block of early definitions
is evaluated exactly as if it was a local bock containing a number of value
definitions.


Early definitions are evaluated in the order they are being defined
before the superclass constructor of the template is called.

Early definitions are particularly useful for
traits, which do not have normal constructor parameters. Example:

trait Greeting
  val name: String
  val msg = "How are you, "+name

class C extends
  val name = "Bob"
 with Greeting
  println(msg)


In the code above, the field name is initialized before the
constructor of Greeting is called. Therefore, field in
class Greeting is properly initialized to "How are you, Bob".

If name had been initialized instead in C's normal class
body, it would be initialized after the constructor of
Greeting. In that case, would be initialized to
"How are you, <null>".


Modifiers


lstlisting
  Modifier          ::=  LocalModifier
                        AccessModifier
                        `override'
  LocalModifier     ::=  `abstract'
                        `final'
                        `sealed'
                        `implicit'
                        `lazy'
  AccessModifier    ::=  (`private'  `protected') [AccessQualifier]
  AccessQualifier   ::=  `[' (id  `this') `]'


Member definitions may be preceded by modifiers which affect the
accessibility and usage of the identifiers bound by them.  If several
modifiers are given, their order does not matter, but the same
modifier may not occur more than once.  Modifiers preceding a repeated
definition apply to all constituent definitions.  The rules governing
the validity and meaning of a modifier are as follows.


The private modifier can be used with any definition or
declaration in a template.  Such members can be accessed only from
within the directly enclosing template and its companion module or
companion class (def:companion).  They
are not inherited by subclasses and they may not override definitions
in parent classes.

The modifier can be qualified with an identifier  (e.g.
 []@) that must denote a class or package
enclosing the definition.  Members labeled with such a modifier are
accessible respectively only from code inside the package  or only
from code inside the class  and its companion module
(sec:object-defs). Such members are also inherited only from
templates inside .

An different form of qualification is private[this]. A member
 marked with this modifier can be accessed only from within
the object in which it is defined. That is, a selection  is only
legal if the prefix is this or .this@, for some
class  enclosing the reference. In addition, the restrictions for
unqualified private apply.

Members marked private without a qualifier are called
class-private, whereas members labeled with [this]@
are called object-private.  A member is private if it is
either class-private or object-private, but not if it is marked
[]@ where  is an identifier; in the latter
case the member is called qualified private.

Class-private or object-private members may not be abstract, and may
not have protected or override modifiers.

The protected modifier applies to class member definitions.
Protected members of a class can be accessed from within

the template of the defining class,
all templates that have the defining class as a base class,
the companion module of any of those classes.

A protected modifier can be qualified with an
identifier  (e.g.   []@) that must denote a
class or package enclosing the definition.  Members labeled with such
a modifier are also accessible respectively from all code inside the
package  or from all code inside the class  and its companion
module (sec:object-defs).

A protected identifier  may be used as a member name in a selection
.@ only if one of the following applies:

The access is within the template defining the member, or, if
  a qualification  is given, inside the package ,
  or the class , or its companion module, or
 is one of the reserved words this and
  super, or
's type conforms to a type-instance of the
  class which contains the access.


A different form of qualification is protected[this]. A member
 marked with this modifier can be accessed only from within
the object in which it is defined. That is, a selection  is only
legal if the prefix is this or .this@, for some
class  enclosing the reference. In addition, the restrictions for
unqualified protected apply.


The override modifier applies to class member definitions or declarations.  It
is mandatory for member definitions or declarations that override some other concrete
member definition in a parent class. If an override
modifier is given, there must be at least one overridden member
definition or declaration (either concrete or abstract).

The override modifier has an additional significance when
combined with the abstract modifier.  That modifier combination
is only allowed for value members of traits.

We call a member  of a template incomplete if it is either
abstract (i.e. defined by a declaration), or it is labeled
abstract and override and
every member overridden by  is again incomplete.

Note that the abstract override modifier combination does not
influence the concept whether a member is concrete or abstract. A
member is abstract if only a declaration is given for it; it is
concrete if a full definition is given.

The abstract modifier is used in class definitions. It is
redundant for traits, and mandatory for all other classes which have
incomplete members.  Abstract classes cannot be instantiated
(sec:inst-creation) with a constructor invocation unless
followed by mixins and/or a refinement which override all
incomplete members of the class. Only abstract classes and traits can have
abstract term members.

The abstract modifier can also be used in conjunction with
override for class member definitions. In that case the
previous discussion applies.

The final modifier applies to class member definitions and to
class definitions. A final class member definition may not be
overridden in subclasses. A final class may not be inherited by
a template. final is redundant for object definitions.  Members
of final classes or objects are implicitly also final, so the
final modifier is redundant for them, too.  final may
not be applied to incomplete members, and it may not be combined in one
modifier list with sealed.

The sealed modifier applies to class definitions. A
sealed class may not be directly inherited, except if the inheriting
template is defined in the same source file as the inherited class.
However, subclasses of a sealed class can be inherited anywhere.

The lazy modifier applies to value definitions. A lazy
value is initialized the first time it is accessed (which might never
happen at all). Attempting to access a lazy value during its
initialization might lead to looping behavior. If an exception is
thrown during initialization, the value is considered uninitialized,
and a later access will retry to evaluate its right hand side.


The following code illustrates the use of qualified private:

package outerpkg.innerpkg
class Outer
  class Inner
    private[Outer] def f()
    private[innerpkg] def g()
    private[outerpkg] def h()



Here, accesses to the method can appear anywhere within
, but not outside it. Accesses to method
can appear anywhere within the package
.innerpkg@, as would be the case for
package-private methods in Java. Finally, accesses to method
can appear anywhere within package ,
including packages contained in it.

A useful idiom to prevent clients of a class from
constructing new instances of that class is to declare the class
abstract and sealed:


object m
  abstract sealed class C (x: Int)
    def nextC = new C(x + 1)

  val empty = new C(0)


For instance, in the code above clients can create instances of class
.C@ only by calling the nextC method of an existing .C@
object; it is not possible for clients to create objects of class
.C@ directly. Indeed the following two lines are both in error:


  new m.C(0)    // **** error: C is abstract, so it cannot be instantiated.
  new m.C(0)  // **** error: illegal inheritance from sealed class.


A similar access restriction can be achieved by marking the primary
constructor private (see ).

Class Definitions


lstlisting
  TmplDef           ::=  `class' ClassDef
  ClassDef          ::=  id [TypeParamClause] Annotation
                         [AccessModifier] ClassParamClauses ClassTemplateOpt
  ClassParamClauses ::=  ClassParamClause
                         [[nl] `(' implicit ClassParams `)']
  ClassParamClause  ::=  [nl] `(' [ClassParams] ')'
  ClassParams       ::=  ClassParam `,' ClassParam
  ClassParam        ::=  Annotation [Modifier (`val'  `var')]
                         id [`:' ParamType] [`=' Expr]
  ClassTemplateOpt  ::=  `extends' ClassTemplate  [[`extends'] TemplateBody]


The most general form of class definition is

class []  ()() extends     .

Here,

[]
 is the name of the class to be defined.
[]  is a non-empty list of type parameters of the class
being defined.  The scope of a type parameter is the whole class
definition including the type parameter section itself.  It is
illegal to define two type parameters with the same name.  The type
parameter section []@ may be omitted. A class with a type
parameter section is called polymorphic, otherwise it is called
monomorphic.
[]  is a possibly empty sequence of annotations
  (sec:annotations). If any annotations are given,
they apply to the primary constructor of the class.
[]  is an access modifier (sec:modifiers) such as
private or protected, possibly with a qualification.  If
such an access modifier is given it applies to the primary constructor
to the class.
[]
 are formal value parameter clauses for the primary
constructor of the class. The scope of a formal value parameter includes
all subsequent parameter sections and the template . However, a formal value
parameter may not form
part of the types of any of the parent classes or members of the class
template .
It is illegal to define two formal value parameters with the same name.
If no formal parameter sections are given,
an empty parameter section ()@ is assumed.

If a formal parameter declaration  is preceded by a val
or var keyword, an accessor (getter) definition
(sec:vardef) for this parameter is implicitly added to the
class. The getter introduces a value member  of class  that is
defined as an alias of the parameter. If the introducing keyword is
var, a setter accessor _=@ (sec:vardef) is also
implicitly added to the class. In invocation of that setter _=()@
changes the value of the parameter to the result of evaluating .
The formal parameter declaration may contain modifiers, which then
carry over to the accessor definition(s). A formal parameter prefixed
by val or var may not at the same time be a call-by-name
parameter (sec:by-name-params).
[]
 is a
template (sec:templates) of the form

 with  with  with

which defines the base classes, behavior and initial state of objects of
the class. The extends clause   with  with  with @
can be omitted, in which case
 scala.AnyRef@  is assumed.  The class body
 @  may also be omitted, in which case the empty body
@ is assumed.

This class definition defines a type []@ and a constructor
which when applied to parameters conforming to types
initializes instances of type []@ by evaluating the template
.

The following example illustrates val and var
parameters of a class C:

class C(x: Int, val y: String, var z: List[String])
val c = new C(1, "abc", List())
c.z = c.y :: c.z


ex:private-constr
The following class can be created only from its companion
module.

object Sensitive
  def makeSensitive(credentials: Certificate): Sensitive =
    if (credentials == Admin) new Sensitive()
    else throw new SecurityViolationException

class Sensitive private ()
  ...




For any index  let  be a class signature consisting of a class
name and optional type parameter and value parameter sections. Let
be a class template.
Then a class definition
  @
is a shorthand for the sequence of class definitions
  ; ...; class  @.
A class definition
  @
is a shorthand for the sequence of class definitions
  ; ...; class  @.


Constructor Definitions

lstlisting
  FunDef         ::= `this' ParamClause ParamClauses
                     (`=' ConstrExpr  [nl] ConstrBlock)
  ConstrExpr     ::= SelfInvocation
                    ConstrBlock
  ConstrBlock    ::= `' SelfInvocation semi BlockStat `'
  SelfInvocation ::= `this' ArgumentExprs ArgumentExprs


A class may have additional constructors besides the primary
constructor.  These are defined by constructor definitions of the form
 this()() = @.  Such a
definition introduces an additional constructor for the enclosing
class, with parameters as given in the formal parameter lists
, and whose evaluation is defined by the constructor
expression .  The scope of each formal parameter is the subsequent
parameter sections and the constructor
expression .  A constructor expression is either a self constructor
invocation ()()@ or a block
which begins with a self constructor invocation. The self constructor
invocation must construct a generic instance of the class. I.e. if the
class in question has name  and type parameters
[]@, then a self constructor invocation must
generate an instance of []@; it is not permitted
to instantiate formal type parameters.

The signature and the self constructor invocation of a constructor
definition are type-checked and evaluated in the scope which is in
effect at the point of the enclosing class definition, augmented by
any type parameters of the enclosing class and by any early
definitions (sec:early-defs) of the enclosing template.
The rest of the
constructor expression is type-checked and evaluated as a function
body in the current class.

If there are auxiliary constructors of a class , they form together
with 's primary constructor (sec:class-defs)
an overloaded constructor
definition. The usual rules for overloading resolution
(sec:overloading-resolution) apply for constructor invocations of ,
including for the self constructor invocations in the constructor
expressions themselves. However, unlike other methods, constructors
are never inherited.  To prevent infinite cycles of constructor
invocations, there is the restriction that every self constructor
invocation must refer to a constructor definition which precedes it
(i.e. it must refer to either a preceding auxiliary constructor or the
primary constructor of the class).

Consider the class definition


class LinkedList[A]()
  var head = _
  var tail = null
  def isEmpty = tail != null
  def this(head: A) =  this(); this.head = head
  def this(head: A, tail: List[A]) =  this(head); this.tail = tail


This defines a class LinkedList with three constructors.  The
second constructor constructs an singleton list, while the
third one constructs a list with a given head and tail.

Case Classes


lstlisting
  TmplDef  ::=  `case' `class' ClassDef


If a class definition is prefixed with case, the class is said
to be a case class.

The formal parameters in the first parameter section of a case class
are called elements; they are treated
specially. First, the value of such a parameter can be extracted as a
field of a constructor pattern. Second, a val prefix is
implicitly added to such a parameter, unless the parameter carries
already a val or var modifier. Hence, an accessor
definition for the parameter is generated (sec:class-defs).

A case class definition of  []()()@  with type
parameters  and value parameters  implicitly
generates an extractor object (sec:extractor-patterns) which is
defined as follows:

  object
    def apply[]()(): [] = new []()()
    def unapply[](: []) =
      if (x eq null) scala.None
      else scala.Some()


Here,
  stands for the vector of types defined in the type
parameter section ,
each  denotes the parameter names of the parameter
section , and
 denote the names of all parameters
in the first parameter section .
If a type parameter section is missing in the
class, it is also missing in the and
methods.
The definition of is omitted if class  is
.

If the case class definition contains an empty value parameter list, the
method returns a instead of an type and
is defined as follows:

    def unapply[](: []) = x ne null

The name of the method is changed to if the first
parameter section  of  ends in a repeated parameter of (sec:repeated-params).
If a companion object  exists already, no new object is created,
but the and methods are added to the existing
object instead.

A method named copy is implicitly added to every case class unless the
class already has a member (directly defined or inherited) with that name. The
method is defined as follows:

  def copy[]()(): [] = new []()()

Again,  stands for the vector of types defined in the type parameter section
and each  denotes the parameter names of the parameter section . Every value
parameter  of the copy method has the form :=this.@,
where  and  refer to the name and type of the corresponding class parameter
.

Every case class implicitly overrides some method definitions of class
.AnyRef@ (sec:cls-object) unless a definition of the same
method is already given in the case class itself or a concrete
definition of the same method is given in some base class of the case
class different from AnyRef. In particular:

[] Method  : (Any)Boolean@  is structural equality, where two
instances are equal if they both belong to the case class in question and they
have equal (with respect to equals) constructor arguments.
[]
Method  : Int@ computes a hash-code. If the hashCode methods
of the data structure members map equal (with respect to equals)
values to equal hash-codes, then the case class hashCode method does
too.
[] Method  : String@  returns a string representation which
contains the name of the class and its elements.


Here is the definition of abstract syntax for lambda
calculus:


class Expr
case class Var   (x: String)          extends Expr
case class Apply (f: Expr, e: Expr)   extends Expr
case class Lambda(x: String, e: Expr) extends Expr

This defines a class Expr with case classes
Var, Apply and Lambda. A call-by-value evaluator for lambda
expressions could then be written as follows.


type Env = String => Value
case class Value(e: Expr, env: Env)

def eval(e: Expr, env: Env): Value = e match
  case Var (x) =>
    env(x)
  case Apply(f, g) =>
    val Value(Lambda (x, e1), env1) = eval(f, env)
    val v = eval(g, env)
    eval (e1, (y => if (y == x) v else env1(y)))
  case Lambda(_, _) =>
    Value(e, env)



It is possible to define further case classes that extend type
Expr in other parts of the program, for instance

case class Number(x: Int) extends Expr


This form of extensibility can be excluded by declaring the base class
Expr sealed; in this case, all classes that
directly extend Expr must be in the same source file as
Expr.

Traits


lstlisting
  TmplDef          ::=  `trait' TraitDef
  TraitDef         ::=  id [TypeParamClause] TraitTemplateOpt
  TraitTemplateOpt ::=  `extends' TraitTemplate  [[`extends'] TemplateBody]


A trait is a class that is meant to be added to some other class
as a mixin. Unlike normal classes, traits cannot have
constructor parameters. Furthermore, no constructor arguments are
passed to the superclass of the trait. This is not necessary as traits are
initialized after the superclass is initialized.

Assume a trait  defines some aspect of an instance  of
type  (i.e.  is a base class of ). Then the actual
supertype of  in  is the compound type consisting of all the
base classes in  that succeed .  The actual supertype gives
the context for resolving a super reference in a trait
(sec:this-super). Note that the actual supertype depends
on the type to which the trait is added in a mixin composition; it is not
statically known at the time the trait is defined.

If  is not a trait, then its actual supertype is simply its
least proper supertype (which is statically known).

ex:comparable The following trait defines the property
of being comparable to objects of some type. It contains an abstract
method <@ and default implementations of the other
comparison operators <=@, >@, and
>=@.


trait Comparable[T <: Comparable[T]]  self: T =>
  def < (that: T): Boolean
  def <=(that: T): Boolean = this < that  this == that
  def > (that: T): Boolean = that < this
  def >=(that: T): Boolean = that <= this



Consider an abstract class Table that implements maps
from a type of keys A to a type of values B. The class
has a method set to enter a new key / value pair into the table,
and a method get that returns an optional value matching a
given key. Finally, there is a method apply which is like
get, except that it returns a given default value if the table
is undefined for the given key. This class is implemented as follows.

abstract class Table[A, B](defaultValue: B)
  def get(key: A): Option[B]
  def set(key: A, value: B)
  def apply(key: A) = get(key) match
    case Some(value) => value
    case None => defaultValue



Here is a concrete implementation of the Table class.

class ListTable[A, B](defaultValue: B) extends Table[A, B](defaultValue)
  private var elems: List[(A, B)]
  def get(key: A) = elems.find(._1.==(key)).map(._2)
  def set(key: A, value: B) =  elems = (key, value) :: elems


Here is a trait that prevents concurrent access to the
get and set operations of its parent class:

trait SynchronizedTable[A, B] extends Table[A, B]
  abstract override def get(key: A): B =
    synchronized  super.get(key)
  abstract override def set((key: A, value: B) =
    synchronized  super.set(key, value)



Note that SynchronizedTable does not pass an argument to
its superclass, Table, even  though Table is defined with a
formal parameter. Note also that the super calls
in SynchronizedTable's get and set methods
statically refer to abstract methods in class Table. This is
legal, as long as the calling method is labeled
abstract override (sec:modifiers).

Finally, the following mixin composition creates a synchronized list table
with strings as keys and integers as values and with a default value 0:

object MyTable extends ListTable[String, Int](0) with SynchronizedTable

The object MyTable inherits its get and set
method from SynchronizedTable.  The super calls in these
methods are re-bound to refer to the corresponding implementations in
ListTable, which is the actual supertype of SynchronizedTable
in MyTable.

Object Definitions



lstlisting
  ObjectDef       ::=  id ClassTemplate


An object definition defines a single object of a new class. Its
most general form is
  extends @. Here,
 is the name of the object to be defined, and
 is a template (sec:templates) of the form

 with  with  with

which defines the base classes, behavior and initial state of .
The extends clause   with  with  with @
can be omitted, in which case
 scala.AnyRef@  is assumed.  The class body
 @  may also be omitted, in which case the empty body
@ is assumed.

The object definition defines a single object (or: module)
conforming to the template .  It is roughly equivalent to the
following definition of a lazy value:

lazy val  = new  with  with  with   this:  =>

Note that the value defined by an object definition is instantiated
lazily.  The  cls@  constructor is evaluated
not at the point of the object definition, but is instead evaluated
the first time  is dereferenced during execution of the program
(which might be never at all). An attempt to dereference  again in
the course of evaluation of the constructor leads to a infinite loop
or run-time error.
Other threads trying to dereference  while the
constructor is being evaluated block until evaluation is complete.

The expansion given above is not accurate for top-level objects. It
cannot be because variable and method definition cannot appear on the
top-level outside of a package object (sec:pkg-obj).  Instead,
top-level objects are translated to static fields.


Classes in Scala do not have static members; however, an equivalent
effect can be achieved by an accompanying object definition
E.g.

abstract class Point
  val x: Double
  val y: Double
  def isOrigin = (x == 0.0 && y == 0.0)

object Point
  val origin = new Point()  val x = 0.0; val y = 0.0


This defines a class Point and an object Point which
contains origin as a member.  Note that the double use of the
name Point is legal, since the class definition defines the
name Point in the type name space, whereas the object
definition defines a name in the term namespace.

This technique is applied by the Scala compiler when interpreting a
Java class with static members. Such a class  is conceptually seen
as a pair of a Scala class that contains all instance members of
and a Scala object that contains all static members of .

Generally, a companion module of a class is an object which has
the same name as the class and is defined in the same scope and
compilation unit. Conversely, the class is called the companion class
of the module.



Let  be a class template.
Then an object definition
  @
is a shorthand for the sequence of object definitions
  ; ...; object  @.
An object definition
  @
is a shorthand for the sequence of object definitions
  ; ...; object  @.



Here's an outline of a module definition for a file system.


object FileSystem
  private type FileDirectory
  private val dir: FileDirectory

  trait File
    def read(xs: Array[Byte])
    def close: Unit


  private class FileHandle extends File

  def open(name: String): File =




Expressions


lstlisting
  Expr              ::=  (Bindings  id  `_') `=>' Expr
                        Expr1
  Expr1             ::=  `if' `(' Expr `)' nl Expr [[semi] else Expr]
                        `while' `(' Expr `)' nl Expr
                        `try' `' Block `' [`catch'  `' CaseClauses `']
                         [`finally' Expr]
                        `do' Expr [semi] `while' `(' Expr ')'
                        `for' (`(' Enumerators `)'  `' Enumerators `')
                         nl [`yield'] Expr
                        `throw' Expr
                        `return' [Expr]
                        [SimpleExpr `.'] id `=' Expr
                        SimpleExpr1 ArgumentExprs `=' Expr
                        PostfixExpr
                        PostfixExpr Ascription
                        PostfixExpr `match' `' CaseClauses `'
  PostfixExpr       ::=  InfixExpr [id [nl]]
  InfixExpr         ::=  PrefixExpr
                        InfixExpr id [nl] InfixExpr
  PrefixExpr        ::=  [`-'  `+'  ` '  `!'] SimpleExpr
  SimpleExpr        ::=  `new' (ClassTemplate  TemplateBody)
                        BlockExpr
                        SimpleExpr1 [`_']
  SimpleExpr1       ::=  Literal
                        Path
                        `_'
                        `(' [Exprs] `)'
                        SimpleExpr `.' id s
                        SimpleExpr TypeArgs
                        SimpleExpr1 ArgumentExprs
                        XmlExpr
  Exprs             ::=  Expr `,' Expr
  BlockExpr         ::=  `' CaseClauses `'
                        `' Block `'
  Block             ::=  BlockStat semi [ResultExpr]
  ResultExpr        ::=  Expr1
                        (Bindings  ([`implicit'] id  `_') `:' CompoundType) `=>' Block
  Ascription        ::=  `:' InfixType
                        `:' Annotation Annotation
                        `:' `_' `*'


Expressions are composed of operators and operands. Expression forms are
discussed subsequently in decreasing order of precedence.

Expression Typing

The typing of expressions is often relative to some expected
type (which might be undefined).
When we write ``expression  is expected to conform to
type '', we mean: (1) the expected type of  is
, and (2) the type of expression  must conform to
.

The following skolemization rule is applied universally for every
expression: If the type of an expression would be an existential type
, then the type of the expression is assumed instead to be a
skolemization (sec:existential-types) of .

Skolemization is reversed by type packing. Assume an expression  of
type  and let  be
all the type variables created by skolemization of some part of  which are free in .
Then the packed type of  is

 forSome  type ; ; type  .


Literals

lstlisting
  SimpleExpr    ::=  Literal


Typing of literals is as described in (sec:literals); their
evaluation is immediate.


The Null Value

The null value is of type .Null@, and is thus
compatible with every reference type.  It denotes a reference value
which refers to a special ``object. This object
implements methods in class .AnyRef@ as follows:


()@ and return true iff the
argument  is also the ``null'' object.

()@ and !=()@ return true iff the
argument x is not also the ``null'' object.

[]@ always returns false.

[]@ returns the ``null'' object itself if
 conforms to .AnyRef@, and throws a
otherwise.

A reference to any other member of the ``null'' object causes a
NullPointerException to be thrown.

Designators


lstlisting
  SimpleExpr  ::=  Path
                  SimpleExpr `.' id


A designator refers to a named term. It can be a simple name or
a selection.

A simple name  refers to a value as specified in sec:names.
If  is bound by a definition or declaration in an enclosing class
or object , it is taken to be equivalent to the selection
.this.@ where  is taken to refer to the class containing
even if the type name  is shadowed (sec:names) at the
occurrence of .

If  is a stable identifier
(sec:stable-ids) of type , the selection  refers
statically to a term member  of  that is identified in  by
the name . There might be several such members, in which
case overloading resolution (overloading-resolution) is applied
to pick a unique one.

For other expressions ,  is typed as
if it was   val  = ; . @, for some fresh name
.

The expected type of a designator's prefix is always undefined.  The
type of a designator is the type  of the entity it refers to, with
the following exception: The type of a path (sec:paths)
which occurs in a context where a stable type
(sec:singleton-types) is required is the singleton type
.type@.

The contexts where a stable type is required are those that satisfy
one of the following conditions:


The path  occurs as the prefix of a selection and it does not
designate a constant, or

The expected type  is a stable type, or

The expected type  is an abstract type with a stable type as lower
bound, and the type  of the entity referred to by  does not
conform to , or

The path  designates a module.


The selection  is evaluated by first evaluating the qualifier
expression , which yields an object , say. The selection's
result is then the member of  that is either defined by  or defined
by a definition overriding .
If that member has a type which
conforms to .NotNull@, the member's value must be initialized
to a value different from , otherwise a .UnitializedError@
is thrown.


This and Super


lstlisting
  SimpleExpr  ::=  [id `.'] `this'
                  [id '.'] `super' [ClassQualifier] `.' id


The expression this can appear in the statement part of a
template or compound type. It stands for the object being defined by
the innermost template or compound type enclosing the reference. If
this is a compound type, the type of this is that compound type.
If it is a template of a
class or object definition with simple name , the type of this
is the same as the type of .this@.

The expression .this@ is legal in the statement part of an
enclosing class or object definition with simple name . It
stands for the object being defined by the innermost such definition.
If the expression's expected type is a stable type, or
.this@ occurs as the prefix of a selection, its type is
.this.type@, otherwise it is the self type of class .

A reference  .@  refers statically to a method or type
in the least proper supertype of the innermost template containing the
reference.  It evaluates to the member  in the actual supertype of
that template which is equal to  or which overrides .  The
statically referenced member  must be a type or a
method.

If it is
a method, it must be concrete, or the template
containing the reference must have a member  which overrides
and which is labeled abstract override.

A reference  .super.@  refers statically to a method
or type  in the least proper supertype of the innermost enclosing class or
object definition named  which encloses the reference. It evaluates
to the member  in the actual supertype of that class or object
which is equal to  or which overrides . The
statically referenced member  must be a type or a
method.  If the statically
referenced member  is a method, it must be concrete, or the innermost enclosing
class or object definition named  must have a member  which
overrides  and which is labeled abstract override.

The super prefix may be followed by a trait qualifier
[]@, as in .super[].@. This is
called a static super reference.  In this case, the reference is
to the type or method of  in the parent trait of  whose simple
name is . That member must be uniquely defined. If it is a method,
it must be concrete.

ex:super
Consider the following class definitions


class Root  def x = "Root"
class A extends Root  override def x = "A" ; def superA = super.x
trait B extends Root  override def x = "B" ; def superB = super.x
class C extends Root with B
  override def x = "C" ; def superC = super.x

class D extends A with B
  override def x = "D" ; def superD = super.x


The linearization of class C is  C, B, Root@  and
the linearization of class D is  D, B, A, Root@.
Then we have:

(new A).superA == "Root",
                          (new C).superB = "Root", (new C).superC = "B",
(new D).superA == "Root", (new D).superB = "A",    (new D).superD = "B",

Note that the superB function returns different results
depending on whether B is mixed in with class Root or A.


Consider the following class definitions:

class Shape
  override def equals(other: Any) =


trait Bordered extends Shape
  val thickness: Int
  override def equals(other: Any) = other match
    case that: Bordered =>
      super equals other && this.thickness == that.thickness
    case _ => false



trait Colored extends Shape
  val color: Color
  override def equals(other: Any) = other match
    case that: Colored =>
      super equals other && this.color == that.color
    case _ => false





Both definitions of equals are combined in the class
below.

trait BorderedColoredShape extends Shape with Bordered with Colored
  override def equals(other: Any) =
    super[Bordered].equals(that) && super[Colored].equals(that)




Function Applications


lstlisting
  SimpleExpr    ::=  SimpleExpr1 ArgumentExprs
  ArgumentExprs ::=  `(' [Exprs] `)'
                    `(' [Exprs `,'] PostfixExpr `:' `_' `*' ')'
                    [nl] BlockExpr
  Exprs         ::=  Expr `,' Expr


An application ()@ applies the
function  to the argument expressions . If
has a method type (::)@, the type of
each argument expression  is typed with the
corresponding parameter type  as expected type. Let  be type
type of argument  . If  is a polymorphic method,
local type inference (sec:local-type-inf) is used to determine
type arguments for . If  has some value type, the application is taken to
be equivalent to .apply()@,
i.e. the application of an apply method defined by .

The function  must be applicable to its arguments
 of types .

If  has a method type
we say that an argument expression  is a named argument if
it has the form  and  is one of the parameter names
. The function  is applicable if all of the follwing conditions
hold:


For every named argument  the type
  is compatible with the parameter type  whose name  matches .
For every positional argument  the type
is compatible with .









If the expected type is defined, the result type  is
compatible to it.


If  is a polymorphic method it is applicable if local type
inference (sec:local-type-inf) can
determine type arguments so that the instantiated method is applicable. If
 has some value type it is applicable if it has a method member named
apply which is applicable.






Evaluation of ()@ usually entails evaluation of
 and  in that order. Each argument expression
is converted to the type of its corresponding formal parameter.  After
that, the application is rewritten to the function's right hand side,
with actual arguments substituted for formal parameters.  The result
of evaluating the rewritten right-hand side is finally converted to
the function's declared result type, if one is given.

The case of a formal parameter with a parameterless
method type  is treated specially. In this case, the
corresponding actual argument expression  is not evaluated before the
application. Instead, every use of the formal parameter on the
right-hand side of the rewrite rule entails a re-evaluation of .
In other words, the evaluation order for
=>-parameters is call-by-name whereas the evaluation
order for normal parameters is call-by-value.
Furthermore, it is required that 's packed type (sec:expr-typing)
conforms to the parameter type .
The behavior of by-name parameters is preserved if the application is
transformed into a block due to named or default arguments. In this case,
the local value for that parameter has the form  = () => @
and the argument passed to the function is ()@.

The last argument in an application may be marked as a sequence
argument, e.g. : _*@. Such an argument must correspond
to a repeated parameter (sec:repeated-params) of type
*@ and it must be the only argument matching this
parameter (i.e. the number of formal parameters and actual arguments
must be the same). Furthermore, the type of  must conform to
 .Seq[]@, for some type  which conforms to
. In this case, the argument list is transformed by replacing the
sequence  with its elements. When the application uses named
arguments, the vararg parameter has to be specified exactly once.

A function application usually allocates a new frame on the program's
run-time stack. However, if a local function or a final method calls
itself as its last action, the call is executed using the stack-frame
of the caller.

Assume the following function which computes the sum of a
variable number of arguments:

def sum(xs: Int*) = (0 /: xs) ((x, y) => x + y)

Then

sum(1, 2, 3, 4)
sum(List(1, 2, 3, 4): _*)

both yield 10 as result. On the other hand,

sum(List(1, 2, 3, 4))

would not typecheck.

Named and Default Arguments


If an application might uses named arguments  or default
arguments, the following conditions must hold.

The named arguments form a suffix of the argument list ,
  i.e. no positional argument follows a named one.
The names  of all named arguments are pairwise distinct and no named
  argument defines a parameter which is already specified by a
  positional argument.
Every formal parameter  which is not specified by either a positional
  or a named argument has a default argument.


If the application uses named or default
arguments the following transformation is applied to convert it into
an application without named or default arguments.

If the function
has the form []@ it is transformed into the
block

 val q =
  q.[]


If the function  is itself an application expression the transformation
is applied recursively on . The result of transforming  is a block of
the form

 val q =
  val  = expr

  val  = expr
  q.[]()()


where every argument in  is a reference to
one of the values . To integrate the current application
into the block, first a value definition using a fresh name  is created
for every argument in , which is initialised to  for
positional arguments and to  for named arguments of the form
@. Then, for every parameter which is not specified
by the argument list, a value definition using a fresh name  is created,
which is initialized using the method computing the default argument of
this parameter (sec:funsigs).

Let  be a permutation of the generated names  and  such such
that the position of each name matches the position of its corresponding
parameter in the method type ()@.
The final result of the transformation is a block of the form

 val q =
  val  = expr

  val  = expr
  val  =

  val  =
  val  = q.defaulti[]()()

  val  = q.defaultj[]()()
  q.[]()()()




Method Values

lstlisting
  SimpleExpr    ::=  SimpleExpr1 `_'


The expression    _@   is well-formed if  is of method
type or if  is a call-by-name parameter.  If  is a method with
parameters,  _@   represents  converted to a function
type by eta expansion (sec:eta-expand). If  is a
parameterless method or call-by-name parameter of type
  _@   represents the function of type
() => @, which evaluates  when it is applied to the empty
parameterlist ()@.

The method values in the left column are each equivalent to the
anonymous functions (sec:closures) on their right.


Math.sin _              x => Math.sin(x)
Array.range _           (x1, x2) => Array.range(x1, x2)
List.map2 _             (x1, x2) => (x3) => List.map2(x1, x2)(x3)
List.map2(xs, ys)_      x => List.map2(xs, ys)(x)


Note that a space is necessary between a method name and the trailing underscore
because otherwise the underscore would be considered part of the name.

Type Applications

lstlisting
  SimpleExpr    ::=  SimpleExpr TypeArgs


A type application []@ instantiates
a polymorphic value  of type  [ >:  <:
 >:  <: ]@  with argument types
@.  Every argument type  must obey
the corresponding bounds  and .  That is, for each
, we must have
, where  is the substitution
.  The type of the application is .

If the function part  is of some value type, the type application
is taken to be equivalent to
 .apply[ T]@, i.e. the application of an apply method defined by
.

Type applications can be omitted if local type inference
(sec:local-type-inf) can infer best type parameters for a
polymorphic functions from the types of the actual function arguments
and the expected result type.

Tuples


lstlisting
  SimpleExpr   ::=  `(' [Exprs] `)'


A tuple expression ()@ is an alias
for the class instance creation
 .Tuple()@, where .
The empty tuple
()@ is the unique value of type .Unit@.

Instance Creation Expressions


lstlisting
  SimpleExpr     ::=  `new' (ClassTemplate  TemplateBody)


A simple instance creation expression is of the form
 @
where  is a constructor invocation
(sec:constr-invoke).  Let  be the type of . Then  must
denote a (a type instance of) a non-abstract subclass of
.AnyRef@. Furthermore, the concrete self type of the
expression must conform to the self type of the class denoted by
(sec:templates). The concrete self type is normally
, except if the expression  @  appears as the
right hand side of a value definition

val :  = new

(where the type annotation  : @  may be missing).
In the latter case, the concrete self type of the expression is the
compound type   with .type@.

The expression is evaluated by creating a fresh
object of type  which is is initialized by evaluating . The
type of the expression is .

A general instance creation expression is of the form
 @  for some class template  (sec:templates).
Such an expression is equivalent to the block

 class  extends ; new

where  is a fresh name of an anonymous class which is
inaccessible to user programs.

There is also a shorthand form for creating values of structural
types: If  @ is a class body, then
 @  is equivalent to the general instance creation expression
 AnyRef@.

Consider the following structural instance creation
expression:

new  def getName() = "aaron"

This is a shorthand for the general instance creation expression

new AnyRef def getName() = "aaron"

The latter is in turn a shorthand for the block

 class anonX extends AnyRef def getName() = "aaron" ; new anonX

where X@ is some freshly created name.

Blocks


lstlisting
  BlockExpr   ::=  `' Block `'
  Block       ::=  BlockStat semi [ResultExpr]


A block expression  ; ; ; @  is
constructed from a sequence of block statements
and a final expression .  The statement sequence may not contain
two definitions or declarations that bind the same name in the same
namespace.  The final expression can be omitted, in which
case the unit value ()@ is assumed.




The expected type of the final expression  is the expected
type of the block. The expected type of all preceding statements is
undefined.

The type of a block  ; ; ; @  is
 forSome @, where  is the type of  and
contains existential clauses (sec:existential-types)
for every value or type name which is free in
and which is defined locally in one of the statements .
We say the existential clause binds the occurrence of the value or type name.
Specifically,


A locally defined type definition   @
is bound by the existential clause  @.
It is an error if  carries type parameters.

A locally defined value definition  @  is
bound by the existential clause  @.

A locally defined class definition   extends@
is bound by the existential clause  @  where
 is the least class type or refinement type which is a proper
supertype of the type . It is an error if  carries type parameters.

A locally defined object definition  extends@
is bound by the existential clause @ where
 is the least class type or refinement type which is a proper supertype of the type
.type@.

Evaluation of the block entails evaluation of its
statement sequence, followed by an evaluation of the final expression
, which defines the result of the block.


Assuming a class [T](x: T)@, the block

 class C extends B  ; new Ref(new C)

has the type  [_1] forSome  type _1 <: B @.
The block

 class C extends B  ; new C

simply has type B, because with the rules in
(sec:ex-simpl the existentially quantified type
 _1 forSome  type _1 <: B @  can be simplified to B.


Prefix, Infix, and Postfix Operations


lstlisting
  PostfixExpr     ::=  InfixExpr [id [nl]]
  InfixExpr       ::=  PrefixExpr
                      InfixExpr id [nl] InfixExpr
  PrefixExpr      ::=  [`-'  `+'  `!'  ` '] SimpleExpr


Expressions can be constructed from operands and operators.

Prefix Operations

A prefix operation  consists of a prefix operator , which
must be one of the identifiers `+@', `
`!@' or ` @'. The expression  is
equivalent to the postfix method application
.unary_@.

Generalize to arbitrary operators

Prefix operators are different from normal function applications in
that their operand expression need not be atomic. For instance, the
input sequence is read as whereas the
function application sin(x)@ would be parsed as the
application of the infix operator sin to the operands
negate and (x)@.

Postfix Operations

A postfix operator can be an arbitrary identifier. The postfix
operation  is interpreted as .

Infix Operations

An infix operator can be an arbitrary identifier. Infix operators have
precedence and associativity defined as follows:

The precedence of an infix operator is determined by the operator's first
character. Characters are listed below in increasing order of
precedence, with characters on the same line having the same precedence.



        ^
        &
        < >
        = !
        :
        + -
        * /


That is, operators starting with a letter have lowest precedence,
followed by operators starting with `@', etc.

There's one exception to this rule, which concerns
assignment operators(sec:assops).
The precedence of an assigment operator is the same as the one
of simple assignment (=). That is, it is lower than the
precedence of any other operator.

The associativity of an operator is determined by the operator's
last character.  Operators ending in a colon `:@' are
right-associative. All other operators are left-associative.

Precedence and associativity of operators determine the grouping of
parts of an expression as follows.

If there are several infix operations in an
expression, then operators with higher precedence bind more closely
than operators with lower precedence.
If there are consecutive infix
operations
with operators  of the same precedence,
then all these operators must
have the same associativity. If all operators are left-associative,
the sequence is interpreted as
.
Otherwise, if all operators are right-associative, the
sequence is interpreted as
.

Postfix operators always have lower precedence than infix
operators. E.g.  is always equivalent to
.

The right-hand operand of a left-associative operator may consist of
several arguments enclosed in parentheses, e.g. .
This expression is then interpreted as .

A left-associative binary
operation  is interpreted as . If  is
right-associative, the same operation is interpreted as
  val =; .() @, where  is a fresh
name.

Assignment Operators

An assignment operator is an operator symbol (syntax category
in (sec:idents)) that ends in an equals character
``='', with the exception of operators for which one of
the following conditions holds:

[(1)] the operator also starts with an equals character, or
[(2)] the operator is one of (<=), (>=),
  (!=).


Assignment operators are treated specially in that they
can be expanded to assignments if no other interpretation is valid.

Let's consider an assignment operator such as += in an infix
operation   += @, where ,  are expressions.
This operation can be re-interpreted as an operation which corresponds
to the assignment

 =  +

except that the operation's left-hand-side  is evaluated only once.

The re-interpretation occurs if the following two conditions are fulfilled.


The left-hand-side  does not have a member named
+=, and also cannot be converted by an implicit conversion (sec:impl-conv)
to a value with a member named +=.

The assignment  =  + @ is type-correct.
In particular this implies that  refers to a variable or object
that can be assigned to, and that is convertible to a value with a member named +.


Typed Expressions

lstlisting
  Expr1              ::=  PostfixExpr `:' CompoundType


The typed expression  has type . The type of
expression  is expected to conform to . The result of
the expression is the value of  converted to type .

Here are examples of well-typed and illegally typed expressions.


  1: Int               // legal, of type Int
  1: Long              // legal, of type Long
  // 1: string         // ***** illegal




Annotated Expressions

lstlisting
  Expr1              ::=  PostfixExpr `:' Annotation Annotation


An annotated expression  ^: @  @^
attaches annotations  to the expression
(sec:annotations).

Assignments

lstlisting
  Expr1        ::=  [SimpleExpr `.'] id `=' Expr
                   SimpleExpr1 ArgumentExprs `=' Expr


The interpretation of an assignment to a simple variable   = @
depends on the definition of . If  denotes a mutable
variable, then the assignment changes the current value of  to be
the result of evaluating the expression . The type of  is
expected to conform to the type of . If  is a parameterless
function defined in some template, and the same template contains a
setter function _=@ as member, then the assignment
  = @  is interpreted as the invocation
 _=()@  of that setter function.  Analogously, an
assignment   = @  to a parameterless function
is interpreted as the invocation  _=()@.

An assignment  () = @  with a function application to the
left of the `operator is interpreted as
 update(, )@, i.e.
the invocation of an update function defined by .


Here is the usual imperative code for matrix multiplication.


def matmul(xss: Array[Array[Double]], yss: Array[Array[Double]]) =
  val zss: Array[Array[Double]] = new Array(xss.length, yss(0).length)
  var i = 0
  while (i < xss.length)
    var j = 0
    while (j < yss(0).length)
      var acc = 0.0
      var k = 0
      while (k < yss.length)
        acc = acc + xss(i)(k) * yss(k)(j)
        k += 1

      zss(i)(j) = acc
      j += 1

    i += 1

  zss


Desugaring the array accesses and assignments yields the following
expanded version:

def matmul(xss: Array[Array[Double]], yss: Array[Array[Double]]) =
  val zss: Array[Array[Double]] = new Array(xss.length, yss.apply(0).length)
  var i = 0
  while (i < xss.length)
    var j = 0
    while (j < yss.apply(0).length)
      var acc = 0.0
      var k = 0
      while (k < yss.length)
        acc = acc + xss.apply(i).apply(k) * yss.apply(k).apply(j)
        k += 1

      zss.apply(i).update(j, acc)
      j += 1

    i += 1

  zss



Conditional Expressions

lstlisting
  Expr1          ::=  `if' `(' Expr `)' nl Expr [[semi] `else' Expr]


The conditional expression  ()  else @  chooses
one of the values of  and , depending on the
value of . The condition  is expected to
conform to type Boolean.  The then-part  and the
else-part  are both expected to conform to the expected
type of the conditional expression. The type of the conditional
expression is the weak least upper bound (sec:weakconformance)
of the types of  and
.  A semicolon preceding the else symbol of a
conditional expression is ignored.

The conditional expression is evaluated by evaluating first
. If this evaluates to true, the result of
evaluating  is returned, otherwise the result of
evaluating  is returned.

A short form of the conditional expression eliminates the
else-part. The conditional expression  () @  is
evaluated as if it was  ()  else ()@.

While Loop Expressions

lstlisting
  Expr1          ::=  `while' `(' Expr ')' nl Expr


The while loop expression  () @  is typed and
evaluated as if it was an application of  () ()@  where
the hypothetical function whileLoop is defined as follows.


  def whileLoop(cond: => Boolean)(body: => Unit): Unit  =
    if (cond)  body ; whileLoop(cond)(body)  else



The loop

  while (x != 0)  y = y + 1/x ; x -= 1

Is equivalent to the application

  whileLoop (x != 0)  y = y + 1/x ; x -= 1

Note that this application will never produce a division-by-zero
error at run-time, since the
expression  (y = 1/x)@  will be evaluated in the body of
while only if the condition parameter is false.


Do Loop Expressions

lstlisting
  Expr1          ::=  `do' Expr [semi] `while' `(' Expr ')'


The do loop expression   while ()@  is typed and
evaluated as if it was the expression  ( ; while () )@.
A semicolon preceding the while symbol of a do loop expression is ignored.

For Comprehensions and For Loops

lstlisting
  Expr1          ::=  `for' (`(' Enumerators `)'  `' Enumerators `')
                         nl [`yield'] Expr
  Enumerators    ::=  Generator semi Enumerator
  Enumerator     ::=  Generator
                     Guard
                     `val' Pattern1 `=' Expr
  Generator      ::=  Pattern1 `<-' Expr [Guard]
  Guard          ::=  `if' PostfixExpr


A for loop  () @  executes expression
for each binding generated by the enumerators .  A for
comprehension  () yield @  evaluates
expression  for each binding generated by the enumerators
and collects the results. An enumerator sequence always starts with a
generator; this can be followed by further generators, value
definitions, or guards.  A generator   <- @
produces bindings from an expression  which is matched in some way
against pattern . A value definition   = @
binds the value name  (or several names in a pattern ) to
the result of evaluating the expression .  A guard
 @ contains a boolean expression which restricts
enumerated bindings. The precise meaning of generators and guards is
defined by translation to invocations of four methods: map,
withFilter, flatMap, and foreach. These methods can
be implemented in different ways for different carrier types.
As an example, an implementation of these methods for lists
  is given in cls-list.

The translation scheme is as follows.  In a first step, every
generator   <- @, where  is not irrefutable (sec:patterns)
for the type of  is replaced by

 <- .withFilter  case  => true; case _ => false


Then, the following rules are applied repeatedly until all
comprehensions have been eliminated.


A for comprehension
 ( <- ) yield @
is translated to
 .map  case  =>  @.


A for loop
 ( <- ) @
is translated to
 .foreach  case  =>  @.


A for comprehension

for ( <- ;  <- ) yield  ,

where @ is a (possibly empty)
sequence of generators, definitions, or guards,
is translated to

.flatMap  case  => for ( <- ) yield   .


A for loop

for ( <- ;  <- )  .

where @ is a (possibly empty)
sequence of generators, definitions, or guards,
is translated to

.foreach  case  => for ( <- )   .


A generator   <- @  followed by a guard
 @  is translated to a single generator
  <- .withFilter(() => )@  where
 are the free variables of .

A generator   <- @  followed by a value definition
  = @ is translated to the following generator of pairs of values, where
 and  are fresh names:

(, ) <- for ( <- ) yield  val  = ; (, )




The following code produces all pairs of numbers
between  and  whose sums are prime.

for   i <- 1 until n
       j <- 1 until i
       if isPrime(i+j)
 yield (i, j)

The for comprehension is translated to:

(1 until n)
  .flatMap
     case i => (1 until i)
       .withFilter  j => isPrime(i+j)
       .map  case j => (i, j)





class List[A]
  def map[B](f: A => B): List[B] = match
    case <> => <>
    case x :: xs => f(x) :: xs.map(f)

  def withFilter(p: A => Boolean) = match
    case <> => <>
    case x :: xs => if p(x) then x :: xs.withFilter(p) else xs.withFilter(p)

  def flatMap[B](f: A => List[B]): List[B] =
    if (isEmpty) Nil
    else f(head) ::: tail.flatMap(f)
  def foreach(f: A => Unit): Unit =
    if (isEmpty) ()
    else (f(head); tail.foreach(f))





abstract class Graph[Node]
  type Edge = (Node, Node)
  val nodes: List[Node]
  val edges: List[Edge]
  def succs(n: Node) = for ((p, s) <- g.edges, p == n) s
  def preds(n: Node) = for ((p, s) <- g.edges, s == n) p

def topsort[Node](g: Graph[Node]): List[Node] =
  val sources = for (n <- g.nodes, g.preds(n) == <>) n
  if (g.nodes.isEmpty) <>
  else if (sources.isEmpty) new Error(``topsort of cyclic graph'') throw
  else sources :+: topsort(new Graph[Node]
    val nodes = g.nodes diff sources
    val edges = for ((p, s) <- g.edges, !(sources contains p)) (p, s)
  )




For comprehensions can be used to express vector
and matrix algorithms concisely.
For instance, here is a function to compute the transpose of a given matrix:


def transpose[A](xss: Array[Array[A]]) =
  for (i <- Array.range(0, xss(0).length)) yield
    for (xs <- xss) yield xs(i)



Here is a function to compute the scalar product of two vectors:

def scalprod(xs: Array[Double], ys: Array[Double]) =
  var acc = 0.0
  for ((x, y) <- xs zip ys) acc = acc + x * y
  acc



Finally, here is a function to compute the product of two matrices.
Compare with the imperative version of .

def matmul(xss: Array[Array[Double]], yss: Array[Array[Double]]) =
  val ysst = transpose(yss)
  for (xs <- xss) yield
    for (yst <- ysst) yield
      scalprod(xs, yst)


The code above makes use of the fact that map, flatMap,
withFilter, and foreach are defined for instances of class
.Array@.

Return Expressions

lstlisting
  Expr1      ::=  `return' [Expr]


A return expression  @  must occur inside the body of some
enclosing named method or function. The innermost enclosing named
method or function in a source program, , must have an explicitly declared result type,
and the type of  must conform to it.
The return expression
evaluates the expression  and returns its value as the result of
. The evaluation of any statements or
expressions following the return expression is omitted. The type of
a return expression is scala.Nothing.

The expression  may be omitted.  The return expression
   is type-checked and evaluated as if it was  ()@.

An method which is generated by the compiler as an
expansion of an anonymous function does not count as a named function
in the source program, and therefore is never the target of a return
expression.

Returning from a nested anonymous function is implemented by throwing
and catching a .runtime.NonLocalReturnException@.  Any
exception catches between the point of return and the enclosing
methods might see the exception.  A key comparison makes sure that
these exceptions are only caught by the method instance which is
terminated by the return.

If the return expression is itself part of an anonymous function, it
is possible that the enclosing instance of  has already returned
before the return expression is executed. In that case, the thrown
.runtime.NonLocalReturnException@ will not be caught,
and will propagate up the call stack.



Throw Expressions

lstlisting
  Expr1      ::=  `throw' Expr


A throw expression  @  evaluates the expression
. The type of this expression must conform to
Throwable.  If  evaluates to an exception
reference, evaluation is aborted with the thrown exception. If
evaluates to null, evaluation is instead aborted with a
NullPointerException. If there is an active
try expression (sec:try) which handles the thrown
exception, evaluation resumes with the handler; otherwise the thread
executing the throw is aborted.  The type of a throw expression
is scala.Nothing.

Try Expressions

lstlisting
  Expr1 ::=  `try' `' Block `' [`catch' `' CaseClauses `']
             [`finally' Expr]


A try expression is of the form     catch @
where the handler  is a pattern matching anonymous function
(sec:pattern-closures)

  case  =>   case  =>   .

This expression is evaluated by evaluating the block
.  If evaluation of  does not cause an exception to be
thrown, the result of  is returned. Otherwise the
handler  is applied to the thrown exception.
If the handler contains a case matching the thrown exception,
the first such case is invoked. If the handler contains
no case matching the thrown exception, the exception is
re-thrown.

Let  be the expected type of the try expression.  The block
 is expected to conform to .  The handler
is expected conform to type
 .PartialFunction[scala.Throwable, ]@.  The
type of the try expression is the weak least upper bound (sec:weakconformance)
of the type of
and the result type of .

A try expression     finally @  evaluates the block
.  If evaluation of  does not cause an exception to be
thrown, the expression  is evaluated. If an exception is thrown
during evaluation of , the evaluation of the try expression is
aborted with the thrown exception. If no exception is thrown during
evaluation of , the result of  is returned as the
result of the try expression.

If an exception is thrown during evaluation of , the finally block
 is also evaluated. If another exception  is thrown
during evaluation of , evaluation of the try expression is
aborted with the thrown exception. If no exception is thrown during
evaluation of , the original exception thrown in  is
re-thrown once evaluation of  has completed.  The block
 is expected to conform to the expected type of the try
expression. The finally expression  is expected to conform to
type Unit.

A try expression     catch  finally @
is a shorthand
for    try    catch   finally @.

Anonymous Functions


lstlisting
  Expr            ::=  (Bindings  [`implicit'] id  `_') `=>' Expr
  ResultExpr      ::=  (Bindings  ([`implicit'] id  `_') `:' CompoundType) `=>' Block
  Bindings        ::=  `(' Binding `,' Binding `)'
  Binding         ::=  (id  `_') [`:' Type]


The anonymous function  (: : ) => e@
maps parameters  of types  to a result given
by expression . The scope of each formal parameter
 is . Formal parameters must have pairwise distinct names.

If the expected type of the anonymous function is of the form
 .Function[, ]@, the
expected type of  is  and the type  of any of the
parameters  can be omitted, in which
case  = @ is assumed.
If the expected type of the anonymous function is
some other type, all formal parameter types must be explicitly given,
and the expected type of  is undefined. The type of the anonymous
function
is .Function[, ]@,
where  is the packed type (sec:expr-typing)
of .  must be equivalent to a
type which does not refer to any of the formal parameters .

The anonymous function is evaluated as the instance creation expression

new scala.Function[, ]
  def apply(: : ):  =


In the case of a single untyped formal parameter,
 () => @
can be abbreviated to   => @. If an
anonymous function  (: ) => @  with a single
typed parameter appears as the result expression of a block, it can be
abbreviated to  :  => e@.

A formal parameter may also be a wildcard represented by an underscore _@.
In that case, a fresh name for the parameter is chosen arbitrarily.

A named parameter of an anonymous function may be optionally preceded
by an modifier. In that case the parameter is
labeled (sec:implicits); however the
parameter section itself does not count as an implicit parameter
section in the sense of (sec:impl-params). Hence, arguments to
anonymous functions always have to be given explicitly.

Examples of anonymous functions:


  x => x                             // The identity function

  f => g => x => f(g(x))             // Curried function composition

  (x: Int,y: Int) => x + y           // A summation function

  () =>  count += 1; count         // The function which takes an
                                     // empty parameter list ,
                                     // increments a non-local variable
                                     // `count' and returns the new value.

  _ => 5                             // The function that ignores its argument
                                     // and always returns 5.


*Placeholder Syntax for Anonymous Functions

lstlisting
  SimpleExpr1  ::=  `_'


An expression (of syntactic category )
may contain embedded underscore symbols _ at places where identifiers
are legal. Such an expression represents an anonymous function where subsequent
occurrences of underscores denote successive parameters.

Define an underscore section to be an expression of the form
_:@ where  is a type, or else of the form _,
provided the underscore does not appear as the expression part of a
type ascription _:@.

An expression  of syntactic category Expr binds an underscore section
, if the following two conditions hold: (1)  properly contains , and
(2) there is no other expression of syntactic category Expr
which is properly contained in  and which itself properly contains .

If an expression  binds underscore sections , in this order, it is equivalent to
the anonymous function  (, ... ) => @
where each  results from  by replacing the underscore with a fresh identifier and
 results from  by replacing each underscore section  by .

The anonymous functions in the left column use placeholder
syntax. Each of these is equivalent to the anonymous function on its right.


_ + 1                  x => x + 1
_ * _                  (x1, x2) => x1 * x2
(_: Int) * 2           (x: Int) => (x: Int) * 2
if (_) x else y        z => if (z) x else y
_.map(f)               x => x.map(f)
_.map(_ + 1)           x => x.map(y => y + 1)


Constant Expressions

Constant expressions are expressions that the Scala compiler can evaluate to a constant.
The definition of ``constant expression'' depends on the platform, but they
include at least the expressions of the following forms:

A literal of a value class, such as an integer
A string literal
A class constructed with Predef.classOf (cls:predef)
An element of an enumeration from the underlying platform
A literal array, of the form
      ^Array^,
      where all of the 's are themselves constant expressions
An identifier defined by a constant value definition (sec:valdef).



Statements


lstlisting
  BlockStat    ::=  Import
                   Annotation [`implicit'] Def
                   Annotation LocalModifier TmplDef
                   Expr1

  TemplateStat ::=  Import
                   Annotation Modifier Def
                   Annotation Modifier Dcl
                   Expr



Statements occur as parts of blocks and templates.  A statement can be
an import, a definition or an expression, or it can be empty.
Statements used in the template of a class definition can also be
declarations.  An expression that is used as a statement can have an
arbitrary value type. An expression statement  is evaluated by
evaluating  and discarding the result of the evaluation.
Generalize to implicit coercion?

Block statements may be definitions which bind local names in the
block. The only modifier allowed in all block-local definitions is
implicit. When prefixing a class or object definition,
modifiers abstract, final, and sealed are also
permitted.

Evaluation of a statement sequence entails evaluation of the
statements in the order they are written.

Implicit Conversions


Implicit conversions can be applied to expressions whose type does not
match their expected type, as well as to unapplied methods. The
available implicit conversions are given in the next two sub-sections.

We say, a type  is compatible to a type  if  conforms
to  after applying eta-expansion (sec:eta-expand) and view applications
(sec:views).

Value Conversions

The following five implicit conversions can be applied to an
expression  which has some value type  and which is type-checked with
some expected type .

Overloading Resolution
If an expression denotes several possible members of a class,
overloading resolution (sec:overloading-resolution)
is applied to pick a unique member.

Type Instantiation
An expression  of polymorphic type

[ >:  <:  >:  <: ]

which does not appear as the function part of
a type application is converted to a type instance of
by determining with local type inference
(sec:local-type-inf) instance types  @
for the type variables  @  and
implicitly embedding  in the type application
 []@  (sec:type-app).

Numeric Widening
If  has a primitive number type which weakly conforms
(sec:weakconformance) to the expected type, it is widened to
the expected type using one of the numeric conversion methods
toShort, toChar, toInt, toLong,
toFloat, toDouble defined in cls:numeric-value.

Numeric Literal Narrowing
If the expected type is Byte, Short or Char, and
the expression  is an integer literal fitting in the range of that
type, it is converted to the same literal in that type.

Value Discarding
If  has some value type and the expected type is Unit,
 is converted to the expected type by embedding it in the
term   ; () @.

View Application
If none of the previous conversions applies, and the 's type
does not conform to the expected type , it is attempted to convert
 to the expected type with a view (sec:views).

Method Conversions

The following four implicit conversions can be applied to methods
which are not applied to some argument list.

Evaluation
A parameterless method  of type @ is always converted to
type  by evaluating the expression to which  is bound.

Implicit Application
  If the method takes only implicit parameters, implicit
  arguments are passed following the rules of sec:impl-params.

Eta Expansion
  Otherwise, if the method is not a constructor,
  and the expected type  is a function type
  , eta-expansion
  (sec:eta-expand) is performed on the
  expression .

Empty Application
  Otherwise, if  has method type , it is implicitly applied to the empty
  argument list, yielding .

Overloading Resolution


If an identifier or selection  references several members of a
class, the context of the reference is used to identify a unique
member.  The way this is done depends on whether or not  is used as
a function. Let  be the set of members referenced by .

Assume first that  appears as a function in an application, as in
()@.

One first determines the set of functions that is potentially
applicable based on the shape of the arguments.

shape

The shape of an argument expression , written  , is
a type that is defined as follows:


For a function expression (: : ) => @:
(Any  Any) => @, where occurs  times
in the argument type.

For a named argument  = @: .

For all other expressions: .


Let  be the set of alternatives in  that are applicable (sec:apply)
to expressions  of types
.
If there is precisely one
alternative in , that alternative is chosen.

Otherwise, let  be the vector of types obtained by
typing each argument with an undefined expected type.  For every
member  in  one determines whether it is
applicable to expressions () of types
.
It is an error if none of the members in  is applicable. If there is one
single applicable alternative, that alternative is chosen. Otherwise, let
be the set of applicable alternatives which don't employ any default argument
in the application to . It is again an error if  is empty.
Otherwise, one chooses the most specific alternative among the alternatives
in , according to the following definition of being ``as specific as'', and
``more specific than'':













A parameterized method  of type ()@ is as specific as some other
member  of type  if  is applicable to arguments
()@ of
types .

A polymorphic method of type
 [ >:  <:  >:  <: ]@  is
as specific as some other member of type  if  is as
specific as  under the assumption that for
 each  is an abstract type name
bounded from below by  and from above by .

A member of any other type is always as specific as a parameterized method
or a polymorphic method.

Given two members of types  and  which are
neither parameterized nor polymorphic method types, the member of type  is as specific as
the member of type  if the existential dual of  conforms to the existential dual of .
Here, the existential dual of a polymorphic type
 [ >:  <:  >:  <: ]@  is
  forSome  type  >:  <:   type  >:  <: @.
The existential dual of every other type is the type itself.


The relative weight of an alternative  over an alternative  is a
number from 0 to 2, defined as the sum of

1 if  is as specific as , 0 otherwise, and
1 if  is defined in a class or object which is derived
      from the class or object defining , 0 otherwise.

A class or object  is derived from a class or object  if one of
the following holds:

 is a subclass of , or
 is a companion object of a class derived from , or
 is a companion object of a class from which  is derived.


An alternative  is more specific than an alternative  if
the relative weight of  over  is greater than the relative
weight of  over .

It is an error if there is no alternative in  which is more
specific than all other alternatives in .

Assume next that  appears as a function in a type application, as
in []@. Then all alternatives in
 which take the same number of type parameters as there are type
arguments in  are chosen. It is an error if no such alternative exists.
If there are several such alternatives, overloading resolution is
applied again to the whole expression []@.

Assume finally that  does not appear as a function in either
an application or a type application. If an expected type is given,
let  be the set of those alternatives in  which are
compatible (sec:impl-conv) to it. Otherwise, let  be the same as .
We choose in this case the most specific alternative among all
alternatives in . It is an error if there is no
alternative in  which is more specific than all other
alternatives in .

Consider the following definitions:


  class A extends B
  def f(x: B, y: B) =
  def f(x: A, y: B) =
  val a: A
  val b: B

Then the application (b, b)@ refers to the first
definition of  whereas the application (a, a)@
refers to the second.  Assume now we add a third overloaded definition

  def f(x: B, y: A) =

Then the application (a, a)@ is rejected for being ambiguous, since
no most specific applicable signature exists.

Local Type Inference


Local type inference infers type arguments to be passed to expressions
of polymorphic type. Say  is of type [ >:  <:
 >:  <: ] and no explicit type parameters
are given.

Local type inference converts this expression to a type
application  []@. The choice of the
type arguments  depends on the context in which
the expression appears and on the expected type .
There are three cases.

Case 1: Selections
If the expression appears as the prefix of a selection with a name
, then type inference is deferred to the whole expression
. That is, if  has type , it is now treated as having
type [ >:  <:  >:  <: ],
and local type inference is applied in turn to infer type arguments
for , using the context in which  appears.

Case 2: Values
If the expression  appears as a value without being applied to
value arguments, the type arguments are inferred by solving a
constraint system which relates the expression's type  with the
expected type . Without loss of generality we can assume that
 is a value type; if it is a method type we apply eta-expansion
(sec:eta-expand) to convert it to a function type.  Solving
means finding a substitution  of types  for the type
parameters  such that


None of inferred types  is a singleton type sec:singleton-types

All type parameter bounds are respected, i.e.
 and  for .

The expression's type conforms to the expected type, i.e.
.

It is a compile time error if no such substitution exists.
If several substitutions exist, local-type inference will choose for
each type variable  a minimal or maximal type  of the
solution space.  A maximal type  will be chosen if the type
parameter  appears contravariantly (sec:variances) in the
type  of the expression.  A minimal type  will be chosen
in all other situations, i.e. if the variable appears covariantly,
non-variantly or not at all in the type . We call such a substitution
an optimal solution of the given constraint system for the type .

Case 3: Methods The last case applies if the expression
 appears in an application . In that case
 is a method type . Without loss of
generality we can assume that the result type  is a value type; if
it is a method type we apply eta-expansion (sec:eta-expand) to
convert it to a function type.  One computes first the types  of
the argument expressions , using two alternative schemes.  Each
argument expression  is typed first with the expected type ,
in which the type parameters  are taken as type
constants.  If this fails, the argument  is typed instead with an
expected type  which results from  by replacing every type
parameter in  with undefined.

In a second step, type arguments are inferred by solving a constraint
system which relates the method's type with the expected type
 and the argument types . Solving the
constraint system means
finding a substitution  of types  for the type parameters
 such that


None of inferred types  is a singleton type sec:singleton-types

All type parameter bounds are respected, i.e.
 and  for .

The method's result type  conforms to the expected type, i.e.
.

Each argument type weakly conforms (sec:weakconformance)
to the corresponding formal parameter
type, i.e.
 for .

It is a compile time error if no such substitution exists.  If several
solutions exist, an optimal one for the type  is chosen.

All or parts of an expected type  may be undefined. The rules for
conformance (sec:conformance) are extended to this case by adding
the rule that for any type  the following two statements are always
true:




It is possible that no minimal or maximal solution for a type variable
exists, in which case a compile-time error results. Because  is a
pre-order, it is also possible that a solution set has several optimal
solutions for a type. In that case, a Scala compiler is free to pick
any one of them.

Consider the two methods:

def cons[A](x: A, xs: List[A]): List[A] = x :: xs
def nil[B]: List[B] = Nil

and the definition

val xs = cons(1, nil) .

The application of cons is typed with an undefined expected
type. This application is completed by local type inference to
 [Int](1, nil)@.
Here, one uses the following
reasoning to infer the type argument for the type
parameter a:

First, the argument expressions are typed. The first argument 1
has type Int whereas the second argument is
itself polymorphic. One tries to type-check with an
expected type List[a]. This leads to the constraint system

List[b?] <: List[a]

where we have labeled ?@ with a question mark to indicate
that it is a variable in the constraint system.
Because class is covariant, the optimal
solution of this constraint is

b = scala.Nothing .


In a second step, one solves the following constraint system for
the type parameter a of cons:

Int <: a?
List[scala.Nothing] <: List[a?]
List[a?] <:

The optimal solution of this constraint system is

a = Int ,

so Int is the type inferred for a.

Consider now the definition

val ys = cons("abc", xs)

where xs is defined of type List[Int] as before.
In this case local type inference proceeds as follows.

First, the argument expressions are typed. The first argument
"abc" has type String. The second argument xs is
first tried to be typed with expected type List[a]. This fails,
as List[Int] is not a subtype of List[a]. Therefore,
the second strategy is tried; xs is now typed with expected type
[]@. This succeeds and yields the argument type
List[Int].

In a second step, one solves the following constraint system for
the type parameter a of cons:

String <: a?
List[Int] <: List[a?]
List[a?] <:

The optimal solution of this constraint system is

a = scala.Any ,

so scala.Any is the type inferred for a.

Eta Expansion

  Eta-expansion converts an expression of method type to an
  equivalent expression of function type. It proceeds in two steps.

  First, one identifes the maximal sub-expressions of ; let's
  say these are . For each of these, one creates a
  fresh name . Let  be the expression resulting from
  replacing every maximal subexpression  in  by the
  corresponding fresh name . Second, one creates a fresh name
  for every argument type  of the method (
). The result of eta-conversion is then:

   val  = ;

    val  = ;
    () => ()



Implicit Parameters and Views

The Implicit Modifier

lstlisting
  LocalModifier  ::= `implicit'
  ParamClauses   ::= ParamClause [nl] `(' `implicit' Params `)'


Template members and parameters labeled with an implicit
modifier can be passed to implicit parameters (sec:impl-params)
and can be used as implicit conversions called views
(sec:views). The implicit modifier is illegal for all
type members, as well as for top-level (sec:packagings)
objects.

ex:impl-monoid
The following code defines an abstract class of monoids and
two concrete implementations, StringMonoid and
IntMonoid. The two implementations are marked implicit.


abstract class Monoid[A] extends SemiGroup[A]
  def unit: A
  def add(x: A, y: A): A

object Monoids
  implicit object stringMonoid extends Monoid[String]
    def add(x: String, y: String): String = x.concat(y)
    def unit: String = ""

  implicit object intMonoid extends Monoid[Int]
    def add(x: Int, y: Int): Int = x + y
    def unit: Int = 0




Implicit Parameters

An implicit parameter list
 (implicit ,,)@  of a method marks the parameters  as
implicit. A method or constructor can have only one implicit parameter
list, and it must be the last parameter list given.

A method with implicit parameters can be applied to arguments just
like a normal method. In this case the implicit label has no
effect. However, if such a method misses arguments for its implicit
parameters, such arguments will be automatically provided.

The actual arguments that are eligible to be passed to an implicit
parameter of type  fall into two categories. First, eligible are
all identifiers  that can be accessed at the point of the method
call without a prefix and that denote an implicit definition
(sec:impl-defs) or an implicit parameter.  An eligible
identifier may thus be a local name, or a member of an enclosing
template, or it may be have been made accessible without a prefix
through an import clause (sec:import). If there are no eligible
identifiers under this rule, then, second, eligible are also all
implicit members of some object that belongs to the implicit
scope of the implicit parameter's type, .

The implicit scope of a type  consists of all companion modules
(sec:object-defs) of classes that are associated with the
implicit parameter's type.  Here, we say a class  is
associated with a type , if it is a base class
(sec:linearization) of some part of .  The parts of a
type  are:


if  is a compound type   with  with @, the
union of the parts of , as well as  itself,

if  is a parameterized type  []@,
the union of the parts of  and ,

if  is a singleton type  .type@, the parts of the type
of ,

if  is a type projection  #@, the parts of  as
well as  itself,

in all other cases, just  itself.


If there are several eligible arguments which match the implicit
parameter's type, a most specific one will be chosen using the rules
of static overloading resolution (sec:overloading-resolution).
If the parameter has a default argument and no implicit argument can
be found the default argument is used.

Assuming the classes from , here is a
method which computes the sum of a list of elements using the
monoid's add and unit operations.

def sum[A](xs: List[A])(implicit m: Monoid[A]): A =
  if (xs.isEmpty) m.unit
  else m.add(xs.head, sum(xs.tail))

The monoid in question is marked as an implicit parameter, and can therefore
be inferred based on the type of the list.
Consider for instance the call

  sum(List(1, 2, 3))

in a context where and
are visible.  We know that the formal type parameter of
needs to be instantiated to . The only
eligible object which matches the implicit formal parameter type
[Int]@ is so this object will
be passed as implicit parameter.

This discussion also shows that implicit parameters are inferred after
any type arguments are inferred (sec:local-type-inf).

Implicit methods can themselves have implicit parameters. An example
is the following method from module scala.List, which injects
lists into the .Ordered@ class, provided the element
type of the list is also convertible to this type.

implicit def list2ordered[A](x: List[A])
  (implicit elem2ordered: A => Ordered[A]): Ordered[List[A]] =
  ...

Assume in addition a method

implicit def int2ordered(x: Int): Ordered[Int]

that injects integers into the class.  We can now
define a sort method over ordered lists:

def sort[A](xs: List[A])(implicit a2ordered: A => Ordered[A]) = ...

We can apply sort to a list of lists of integers  : List[List[Int]]@
as follows:

sort(yss)

The call above will be completed by passing two nested implicit arguments:

sort(yss)(xs: List[Int] => list2ordered[Int](xs)(int2ordered)) .

The possibility of passing implicit arguments to implicit arguments
raises the possibility of an infinite recursion.  For instance, one
might try to define the following method, which injects every type into the class:

implicit def magic[A](x: A)(implicit a2ordered: A => Ordered[A]): Ordered[A] =
  a2ordered(x)

Now, if one tried to apply
to an argument arg of a type that did not have
another injection into the Ordered class, one would obtain an infinite
expansion:

sort(arg)(x => magic(x)(x => magic(x)(x => ... )))

To prevent such infinite expansions, the compiler keeps track of
a stack of ``open implicit types'' for which implicit arguments are currently being
searched. Whenever an implicit argument for type  is searched, the
``core type'' of  is added to the stack. Here, the core type
of  is  with aliases expanded, top-level type annotations (sec:annotations) and
refinements (sec:refinements) removed, and occurrences
of top-level existentially bound variables replaced by their upper
bounds. The core type is removed from the stack once the search for
the implicit argument either definitely fails or succeeds. Everytime a
core type is added to the stack, it is checked that this type does not
dominate any of the other types in the set.

Here, a core type  dominates a type  if  is equivalent (sec:type-equiv)
to , or if the top-level type constructors of  and  have a
common element and  is more complex than .

The set of top-level type constructors  of a type  depends on the form of
the type:

For a type designator,
;
For a parameterized type,
;
For a singleton type,
, provided  has type ;
For a compound type,
 with  with @ .


The complexity  of a core type is an integer which also depends on the form of
the type:

For a type designator,

For a parameterized type,

For a singleton type denoting a package ,

For any other singleton type,
, provided  has type ;
For a compound type,
 with  with @


When typing sort(xs) for some list xs of type List[List[List[Int]]],
the sequence of types for
which implicit arguments are searched is

List[List[Int]] => Ordered[List[List[Int]]],
List[Int] => Ordered[List[Int]]
Int => Ordered[Int]

All types share the common type constructor scala.Function1,
but the complexity of the each new type is lower than the complexity of the previous types.
Hence, the code typechecks.

Let ys be a list of some type which cannot be converted
to Ordered. For instance:

val ys = List(new IllegalArgumentException, new ClassCastException, new Error)

Assume that the definition of magic above is in scope. Then the sequence
of types for which implicit arguments are searched is

Throwable => Ordered[Throwable],
Throwable => Ordered[Throwable],
...

Since the second type in the sequence is equal to the first, the compiler
will issue an error signalling a divergent implicit expansion.

Views

Implicit parameters and methods can also define implicit conversions
called views. A view from type  to type  is
defined by an implicit value which has function type
=>@ or (=>)=>@ or by a method convertible to a value of that
type.

Views are applied in three situations.


If an expression  is of type , and  does not conform to the
expression's expected type . In this case an implicit  is
searched which is applicable to  and whose result type conforms to
.  The search proceeds as in the case of implicit parameters,
where the implicit scope is the one of   => @. If
such a view is found, the expression  is converted to
()@.

In a selection  with  of type , if the selector  does
not denote a member of .  In this case, a view  is searched
which is applicable to  and whose result contains a member named
.  The search proceeds as in the case of implicit parameters, where
the implicit scope is the one of .  If such a view is found, the
selection  is converted to ().@.

In a selection  with  of type , if the selector
 denotes some member(s) of , but none of these members is applicable to the arguments
. In this case a view  is searched which is applicable to
and whose result contains a method  which is applicable to .
The search proceeds as in the case of implicit parameters, where
the implicit scope is the one of .  If such a view is found, the
selection  is converted to ().@.

The implicit view, if it is found, can accept is argument  as a
call-by-value or as a call-by-name parameter. However, call-by-value
implicits take precedence over call-by-name implicits.

As for implicit parameters, overloading resolution is applied
if there are several possible candidates (of either the call-by-value
or the call-by-name category).

ex:impl-ordered Class .Ordered[A]@ contains a method

  def <= [B >: A](that: B)(implicit b2ordered: B => Ordered[B]): Boolean .

Assume two lists xs and ys of type List[Int]
and assume that the list2ordered and int2ordered
methods defined in sec:impl-params are in scope.
Then the operation

  xs <= ys

is legal, and is expanded to:

  list2ordered(xs)(int2ordered).<=
    (ys)
    (xs => list2ordered(xs)(int2ordered))

The first application of 2ordered@ converts the list
xs to an instance of class Ordered, whereas the second
occurrence is part of an implicit parameter passed to the <=
method.

Context Bounds and View Bounds

lstlisting
  TypeParam ::= (id  `_') [TypeParamClause] [`>:' Type] [`<:'Type]
                `<


A type parameter  of a method or non-trait class may have one or more view
bounds  <
instantiated to any type  which is convertible by application of a
view to the bound .

A type parameter  of a method or non-trait class may also have one
or more context bounds  : @. In this case the type parameter may be
instantiated to any type  for which evidence exists at the
instantiation point that  satisfies the bound . Such evidence
consists of an implicit value with type .

A method or class containing type parameters with view or context bounds is treated as being
equivalent to a method with implicit parameters. Consider first the case of a
single parameter with view and/or context bounds such as:

def [ <

Then the method definition above is expanded to

def []()(implicit :  => , ..., :  => ,
                       : [], ..., : []):  = ...

where the  and  are fresh names for the newly introduced implicit parameters. These
parameters are called evidence parameters.

If a class or method has several view- or context-bounded type parameters, each
such type parameter is expanded into evidence parameters in the order
they appear and all the resulting evidence parameters are concatenated
in one implicit parameter section.  Since traits do not take
constructor parameters, this translation does not work for them.
Consequently, type-parameters in traits may not be view- or context-bounded.
Also, a method or class with view- or context bounds may not define any
additional implicit parameters.

The <= method mentioned in  can be declared
more concisely as follows:

  def <= [B >: A <


Manifests

Mobj

Manifests are type descriptors that can be automatically generated by
the Scala compiler as arguments to implicit parameters. The Scala
standard library contains a hierarchy of four manifest classes,
with
at the top. Their signatures follow the outline below.

trait OptManifest[+T]
object NoManifest extends OptManifest[Nothing]
trait ClassManifest[T] extends OptManifest[T]
trait Manifest[T] extends ClassManifest[T]


If an implicit parameter of a method or constructor is of a subtype  of
class [T]@, a manifest is determined for ,
according to the following rules.

First if there is already an implicit argument that matches , this
argument is selected.

Otherwise, let  be the companion object .reflect.Manifest@
if  is trait , or be
the companion object .reflect.ClassManifest@ otherwise. Let  be the trait
if  is trait , or be the trait otherwise.
Then the following rules apply.




If  is a value class or one of the classes , , ,
, or ,
a manifest for it is generated by selecting
the corresponding manifest value .@, which exists in the
module.

If  is an instance of []@, a manifest is generated
with the invocation .arrayType[S](m)@, where  is the manifest
determined for .

If  is some other class type  where the prefix type
cannot be statically determined from the class ,
a manifest is generated
with the invocation .classType[T](, classOf[T], )@
where  is the manifest determined for  and  are the
manifests determined for .

If  is some other class type with type arguments ,
a manifest is generated
with the invocation .classType[T](classOf[T], )@
where  are the
manifests determined for .

If  is a singleton type  .type@, a manifest is generated with
the invocation
.singleType[T]()@

If  is a refined type , a manifest is generated for .
(That is, refinements are never reflected in manifests).

If  is an intersection type
 with  with @
where , the result depends on whether a full manifest is
to be determined or not.
If  is trait , then
a manifest is generated with the invocation
.intersectionType[T]()@ where  are the manifests
determined for .
Otherwise, if  is trait ,
then a manifest is generated for the intersection dominator
(sec:erasure)
of the types .

If  is some other type, then if  is trait ,
a manifest is generated from the designator .reflect.NoManifest@.
If  is a type different from , a static error results.


Pattern Matching

Patterns



lstlisting
  Pattern         ::=  Pattern1  `' Pattern1
  Pattern1        ::=  varid `:' TypePat
                      `_' `:' TypePat
                      Pattern2
  Pattern2        ::=  varid [`@' Pattern3]
                      Pattern3
  Pattern3        ::=  SimplePattern
                      SimplePattern id [nl] SimplePattern
  SimplePattern   ::=  `_'
                      varid
                      Literal
                      StableId
                      StableId `(' [Patterns] `)'
                      StableId `(' [Patterns `,'] [varid `@'] `_' `*' `)'
                      `(' [Patterns] `)'
                      XmlPattern
  Patterns        ::=  Pattern `,' Patterns






A pattern is built from constants, constructors, variables and type
tests. Pattern matching tests whether a given value (or sequence of values)
has the shape defined by a pattern, and, if it does, binds the
variables in the pattern to the corresponding components of the value
(or sequence of values).  The same variable name may not be bound more
than once in a pattern.

Some examples of patterns are:


The pattern  : IOException@ matches all instances of class
, binding variable to the instance.

The pattern  (x)@  matches values of the form  ()@,
binding to the argument value  of the Some constructor.

The pattern  (x, _)@  matches pairs of values, binding to
the first component of the pair. The second component is matched
with a wildcard pattern.

The pattern  :: y :: xs@  matches lists of length ,
binding to the list's first element, to the list's
second element, and to the remainder.

The pattern  1  2  3@  matches the integers between 1 and 3.


Pattern matching is always done in a context which supplies an
expected type of the pattern. We distinguish the following kinds of
patterns.

Variable Patterns

lstlisting
  SimplePattern   ::=  `_'
                      varid


A variable pattern  is a simple identifier which starts with a
lower case letter.  It matches any value, and binds the variable name
to that value.  The type of  is the expected type of the pattern as
given from outside.  A special case is the wild-card pattern
which is treated as if it was a fresh variable on each occurrence.

Typed Patterns



  Pattern1        ::=  varid `:' TypePat
                      `_' `:' TypePat


A typed pattern  consists of a pattern variable  and a
type pattern .  The type of  is the type pattern , where
each type variable and wildcard is replaced by a fresh, unknown type.
This pattern matches any value matched by the type
pattern  (sec:type-patterns); it binds the variable name to
that value.

Pattern Binders



  Pattern2        ::=  varid `@' Pattern3

A pattern binder @ consists of a pattern variable  and a
pattern . The type of the variable  is the static type  of the pattern .
This pattern matches any value  matched by the pattern ,
provided the run-time type of  is also an instance of ,
and it binds the variable name to that value.

Literal Patterns

lstlisting
  SimplePattern   ::=  Literal


A literal pattern  matches any value that is equal (in terms of
) to the literal . The type of  must conform to the
expected type of the pattern.

Stable Identifier Patterns



  SimplePattern   ::=  StableId


A stable identifier pattern is a stable identifier
(sec:stable-ids). The type of  must conform to the expected
type of the pattern. The pattern matches any value  such that
  == @  (sec:cls-object).

To resolve the syntactic overlap with a variable pattern, a
stable identifier pattern may not be a simple name starting with a lower-case
letter. However, it is possible to enclose a such a variable name in
backquotes; then it is treated as a stable identifier pattern.

Consider the following function definition:

def f(x: Int, y: Int) = x match
  case y => ...


Here, is a variable pattern, which matches any value.
If we wanted to turn the pattern into a stable identifier pattern, this
can be achieved as follows:

def f(x: Int, y: Int) = x match
  case `y` => ...


Now, the pattern matches the y parameter of the enclosing function f.
That is, the match succeeds only if the x argument and the y
argument of f are equal.

Constructor Patterns

lstlisting
  SimplePattern   ::=  StableId `(' [Patterns] `)


A constructor pattern is of the form  where
. It consists of a stable identifier , followed by element
patterns . The constructor  is a simple or
qualified name which denotes a case class
(sec:case-classes). If the case class is monomorphic, then it
must conform to the expected type of the pattern, and the formal
parameter types of 's primary constructor (sec:class-defs)
are taken as the expected types of the element patterns
.  If the case class is polymorphic, then its type parameters are
instantiated so that the instantiation of  conforms to the expected
type of the pattern. The instantiated formal parameter types of 's
primary constructor are then taken as the expected types of the
component patterns .  The pattern matches all
objects created from constructor invocations
where each element pattern  matches the corresponding value
.

A special case arises when 's formal parameter types end in a
repeated parameter. This is further discussed in
(sec:pattern-seqs).

Tuple Patterns

lstlisting
  SimplePattern   ::=  `(' [Patterns] `)'


A tuple pattern ()@ is an alias
for the constructor pattern  .Tuple(
)@, where . The empty tuple
()@ is the unique value of type .Unit@.

Extractor Patterns

lstlisting
  SimplePattern   ::=  StableId `(' [Patterns] `)'


An extractor pattern  where  is of
the same syntactic form as a constructor pattern. However, instead of
a case class, the stable identifier  denotes an object which has a
member method named unapply or unapplySeq that matches
the pattern.

An unapply method in an object  matches the pattern
 if it takes exactly one argument and one of
the following applies:

[]
 and unapply's result type is Boolean. In this case
the extractor pattern matches all values  for which
.unapply()@ yields true.
[]
 and unapply's result type is []@, for some
type .  In this case, the (only) argument pattern  is typed in
turn with expected type .  The extractor pattern matches then all
values  for which .unapply()@ yields a value of form
()@, and  matches .
[]
 and unapply's result type is
[()]@, for some
types .  In this case, the argument patterns
 are typed in turn with expected types
.  The extractor pattern matches then all values  for which
.unapply()@ yields a value of form
(())@, and each pattern
 matches the corresponding value .


An unapplySeq method in an object  matches the pattern
 if it takes exactly one argument and its
result type is of the form []@, where  is a subtype of
[]@ for some element type .
This case is further discussed in (sec:pattern-seqs).

The Predef object contains a definition of an
extractor object Pair:

object Pair
  def apply[A, B](x: A, y: B) = Tuple2(x, y)
  def unapply[A, B](x: Tuple2[A, B]): Option[Tuple2[A, B]] = Some(x)


This means that the name Pair can be used in place of Tuple2 for tuple
formation as well as for deconstruction of tuples in patterns.
Hence, the following is possible:

val x = (1, 2)
val y = x match
  case Pair(i, s) => Pair(s + i, i * i)



Pattern Sequences

lstlisting
  SimplePattern ::= StableId `(' [Patterns `,'] [varid `@'] `_' `*' `)'


A pattern sequence  appears in two
contexts. First, in a constructor pattern
), where  is a case
class which has  primary constructor parameters,
ending in a repeated parameter (sec:repeated-params) of type
. Second, in an extractor pattern
 if the extractor object  has an
unapplySeq method with a result type conforming to
[]@, but does not have an unapply method that
matches .
The expected type for the pattern sequence is in each case the type .

The last pattern in a pattern sequence may be a sequence
wildcard _*. Each element pattern  is type-checked with
 as expected type, unless it is a sequence wildcard. If a final
sequence wildcard is present, the pattern matches all values  that
are sequences which start with elements matching patterns
.  If no final sequence wildcard is given, the
pattern matches all values  that are sequences of
length  which consist of elements matching patterns
.

Infix Operation Patterns

lstlisting
  Pattern3  ::=  SimplePattern id [nl] SimplePattern


An infix operation pattern  is a shorthand for the
constructor or extractor pattern .  The precedence and
associativity of operators in patterns is the same as in expressions
(sec:infix-operations).

An infix operation pattern  is a
shorthand for the constructor or extractor pattern
.

Pattern Alternatives

lstlisting
  Pattern   ::=  Pattern1  `' Pattern1


A pattern alternative      @
consists of a number of alternative patterns . All alternative
patterns are type checked with the expected type of the pattern. They
may no bind variables other than wildcards. The alternative pattern
matches a value  if at least one its alternatives matches .

XML Patterns

XML patterns are treated in sec:xml-pats.

Regular Expression Patterns

Regular expression patterns have been discontinued in Scala from version 2.0.

Later version of Scala provide a much simplified version of regular
expression patterns that cover most scenarios of non-text sequence
processing.  A sequence pattern is a pattern that stands in a
position where either (1) a pattern of a type +T+ which is
conforming to
+Seq[A]+ for some +A+ is expected, or (2) a case
class constructor that has an iterated formal parameter
+A*+.  A wildcard star pattern +_*+ in the
rightmost position stands for arbitrary long sequences. It can be
bound to variables using +@+, as usual, in which case the variable will have the
type +Seq[A]+.


lstlisting
  Pattern         ::=  Pattern1  `' Pattern1
  Pattern1        ::=  varid `:' Type
                      `_' `:' Type
                      Pattern2
  Pattern2        ::=  [varid `@'] Pattern3
  Pattern3        ::=  SimplePattern [ `*'  `?'  `+' ]
                      SimplePattern  id' SimplePattern
  SimplePattern   ::=  `_'
                      varid
                      Literal
                      `null'
                      StableId [ `(' [Patterns] `)' ]
                      `(' [Patterns] `)'
  Patterns        ::=  Pattern `,' Pattern
  id'             ::=  id  '*'  '?'  '+'  `@'  `'


We distinguish between tree patterns and hedge patterns (hedges
are ordered sequences of trees). A tree pattern describes
a set of matching trees (like above). A hedge pattern describes
a set of matching hedges. Both kinds of patterns may contain
variable bindings which serve to extract constituents of a tree or hedge.

The type of a patterns and the expected types of variables
within patterns are determined by the context and the structure of the
patterns. The last case ensures that a variable bound
to a hedge pattern will have a sequence type.

The following patterns are added:

A hedge pattern  where  is a
sequence of patterns separated by commas and matching the hedge described
by the components. Hedge patterns may appear as arguments to constructor
applications, or nested within another hedge pattern if grouped with
parentheses. Note that empty hedge patterns are allowed. The type of tree
patterns that appear in a hedge pattern is the expected type as
determined from the enclosing constructor.
A fixed-length argument pattern is a special hedge pattern where
where all  are tree patterns.

A choice pattern  is a choice among several
alternatives, which may not contain variable-binding patterns. It
matches every tree and every hedge matched by at least one of its
alternatives.  Note that the empty sequence may appear as an alternative.
An option pattern  is an abbreviation for . A choice is
a tree pattern if all its branches are tree patterns. In this case, all
branches must conform to the expected type and the type
of the choice is the least upper bound of the branches. Otherwise,
its type is determined by the enclosing hedge pattern it is part of.

An iterated pattern  matches zero, one or more occurrences
of items matched by , where  may be either a tree pattern or a hedge pattern.  may not
contain a variable-binding. A non-empty iterated pattern  is an
abbreviation for .

The treatment of the following patterns changes with to the
previous section:

A constructor pattern  consists of a simple type
followed by a pattern .  If  designates a monomorphic case
class, then it must conform to the expected type of the pattern, the
pattern must be a fixed length argument pattern
whose length corresponds to the number of arguments of 's primary
constructor. The expected types of the component patterns are then
taken from the formal parameter types of (said) constructor.  If
designates a polymorphic case class, then there must be a unique type
application instance of it such that the instantiation of  conforms
to the expected type of the pattern. The instantiated formal parameter
types of 's primary constructor are then taken as the expected
types of the component patterns .  In both cases,
the pattern matches all objects created from constructor invocations
 where each component pattern  matches the
corresponding value . If  does not designate a case class, it
must be a subclass of []@. In that case  may be an
arbitrary sequence pattern. Value patterns in  are expected to conform to
type , and the pattern matches all objects whose ()@
method returns a sequence that matches .

The pattern  is regarded as equivalent to the pattern , if
is a nonempty sequence pattern. The empty tuple  is a shorthand
for the constructor pattern Unit.

A variable-binding  is a simple identifier
which starts with a lower case letter, together with a pattern . It
matches every item (tree or hedge) matched by , and in addition binds
it to the variable name. If  is a tree pattern of type , the type
of  is also .
If  is a hedge pattern enclosed by constructor []@,
then the type of  is []@
where  is the expected type as dictated by the constructor.




Regular expressions that contain variable bindings may be ambiguous,
i.e. there might be several ways to match a sequence against the
pattern. In these cases, the right-longest policy applies:
patterns that appear more to the right than others in a sequence take
precedence in case of overlaps.

Some examples of patterns are:


The pattern  : IOException@  matches all instances of class
IOException, binding variable ex to the instance.

The pattern  (x, _)@  matches pairs of values, binding x to
the first component of the pair. The second component is matched
with a wildcard pattern.

The pattern  List( x, y, xs @ _ * ) matches lists of length ,
binding x to the list's first element, y to the list's
second element, and xs to the remainder, which may be empty.

The pattern  List( 1, x@(( 'a'  'b' )+),y,_ ) matches a list that
contains 1 as its first element, continues with a non-empty sequence of
'a's and 'b's, followed by two more elements. The sequence of 'a's and 'b's
is bound to x, and the next to last element is bound to y.

The pattern List( x@( 'a'* ), 'a'+ ) matches a non-empty list of
'a's. Because of the shortest match policy, x will always be bound to
the empty sequence.

The pattern List( x@( 'a'+ ), 'a'* ) also matches a non-empty list of
'a's. Here, x will always be bound to
the sequence containing one 'a'.




Irrefutable Patterns

A pattern  is irrefutable for a type , if one of the following applies:

 is a variable pattern,
 is a typed pattern , and ,
 is a constructor pattern , the type
      is an instance of class , the primary constructor
      (sec:class-defs) of type  has
      argument types , and each  is irrefutable for .




Type Patterns

lstlisting
  TypePat           ::=  Type

Type patterns consist of types, type variables, and wildcards.
A type pattern  is of one of the following  forms:

A reference to a class , , or #@.  This
type pattern matches any non-null instance of the given class.
Note that the prefix of the class, if it is given, is relevant for determining
class instances. For instance, the pattern  matches only
instances of classes  which were created with the path  as
prefix.

The bottom types scala.Nothing and scala.Null cannot
be used as type patterns, because they would match nothing in any case.

A singleton type .type@. This type pattern matches only the value
denoted by the path  (that is, a pattern match involved a
comparison of the matched value with  using method eq in class
AnyRef).

A compound type pattern  with  with @ where each  is a
type pattern. This type pattern matches all values that are matched by each of
the type patterns .

A parameterized type pattern , where the
are type variable patterns or wildcards .
This type pattern matches all values which match  for
some arbitrary instantiation of the type variables and wildcards. The
bounds or alias type of these type variable are determined as
described in (sec:type-param-inf-pat).

A parameterized type pattern .Array@, where
 is a type pattern. This type pattern matches any non-null instance
of type .Array@, where  is a type matched by .

Types which are not of one of the forms described above are also
accepted as type patterns. However, such type patterns will be translated to their
erasure (sec:erasure).  The Scala
compiler will issue an ``unchecked'' warning for these patterns to
flag the possible loss of type-safety.

A type variable pattern is a simple identifier which starts with
a lower case letter. However, the predefined primitive type aliases
, , ,
, , ,
, , and are not
classified as type variable patterns.

Type Parameter Inference in Patterns

Type parameter inference is the process of finding bounds for the
bound type variables in a typed pattern or constructor
pattern. Inference takes into account the expected type of the
pattern.

Type parameter inference for typed patterns.
Assume a typed pattern . Let  result from  where all wildcards in
 are renamed to fresh variable names.  Let  be
the type variables in . These type variables are considered bound
in the pattern. Let the expected type of the pattern be .

Type parameter inference constructs first a set of subtype constraints over
the type variables . The initial constraints set  reflects
just the bounds of these type variables. That is, assuming  has
bound type variables  which correspond to class
type parameters  with lower bounds
 and upper bounds ,
contains the constraints rcll a_i &<:& U_i & (i = 1
n) L_i &<:& a_i & (i = 1 n)
where  is the substitution
.

The set  is then augmented by further subtype constraints. There are two
cases.

Case 1:
If there exists a substitution  over the type variables
 such that  conforms to , one determines
the weakest subtype constraints  over the type variables
 such that  implies that
conforms to .

Case 2:
Otherwise, if  can not be made to conform to  by
instantiating its type variables, one determines all type variables in
 which are defined as type parameters of a method enclosing
the pattern. Let the set of such type parameters be
. Let  be the subtype constraints reflecting the bounds of the
type variables .  If  denotes an instance type of a final
class, let  be the weakest set of subtype constraints over the type
variables  and  such that
 implies that  conforms to
.  If  does not denote an instance type of a final class,
let  be the weakest set of subtype constraints over the type variables
 and  such that
 implies that it is possible to construct a type
 which conforms to both  and . It is a static error if
there is no satisfiable set of constraints  with this property.

The final step consists in choosing type bounds for the type
variables which imply the established constraint system. The process
is different for the two cases above.

Case 1:
We take  where each
 is minimal and each  is maximal wrt  such that
 for  implies .

Case 2:
We take  and  where each
and  is minimal and each  and  is maximal such that
 for  and
 for
implies .

In both cases, local type inference is permitted to limit the
complexity of inferred bounds. Minimality and maximality of types have
to be understood relative to the set of types of acceptable
complexity.

Type parameter inference for constructor patterns.
Assume a constructor pattern  where class
has type type parameters .  These type parameters
are inferred in the same way as for the typed pattern
 (_: )@.


Consider the program fragment:

val x: Any
x match
  case y: List[a] => ...


Here, the type pattern [a]@ is matched against the
expected type . The pattern binds the type variable
.  Since [a]@ conforms to
for every type argument, there are no constraints on .
Hence, is introduced as an abstract type with no
bounds. The scope of is right-hand side of its case clause.

On the other hand, if is declared as

val x: List[List[String]],

this generates the constraint
 [a] <: List[List[String]]@, which simplifies to
 <: List[String]@, because is covariant. Hence,
is introduced with upper bound
[String]@.


Consider the program fragment:

val x: Any
x match
  case y: List[String] => ...


Scala does not maintain information about type arguments at run-time,
so there is no way to check that is a list of strings.
Instead, the Scala compiler will erase (sec:erasure) the
pattern to [_]@; that is, it will only test whether the
top-level runtime-class of the value conforms to
, and the pattern match will succeed if it does.  This
might lead to a class cast exception later on, in the case where the
list contains elements other than strings.  The Scala
compiler will flag this potential loss of type-safety with an
``unchecked'' warning message.


Consider the program fragment

class Term[A]
class Number(val n: Int) extends Term[Int]
def f[B](t: Term[B]): B = t match
  case y: Number => y.n


The expected type of the pattern  : Number@  is
 [B]@.  The type Number does not conform to
 [B]@; hence Case 2 of the rules above
applies. This means that is treated as another type
variable for which subtype constraints are inferred. In our case the
applicable constraint is  <: Term[B]@, which
entails = Int@.  Hence, is treated in
the case clause as an abstract type with lower and upper bound
. Therefore, the right hand side of the case clause,
.n@, of type , is found to conform to the
function's declared result type, .

Pattern Matching Expressions


lstlisting
  Expr            ::=  PostfixExpr `match' `' CaseClauses `'
  CaseClauses     ::=  CaseClause CaseClause
  CaseClause      ::=  `case' Pattern [Guard] `=>' Block


A pattern matching expression

e match  case  =>   case  =>

consists of a selector expression  and a number  of
cases. Each case consists of a (possibly guarded) pattern  and a
block . Each  might be complemented by a guard
 @  where  is a boolean expression.
The scope of the pattern
variables in  comprises the pattern's guard and the corresponding block .

Let  be the type of the selector expression  and let
 be the type parameters of all methods enclosing
the pattern matching expression.  For every , let  be its
lower bound and  be its higher bound.  Every pattern
 can be typed in two ways. First, it is attempted
to type  with  as its expected type. If this fails,  is
instead typed with a modified expected type  which results from
 by replacing every occurrence of a type parameter  by
undefined.  If this second step fails also, a compile-time
error results. If the second step succeeds, let  be the type of
pattern  seen as an expression. One then determines minimal bounds
 and maximal bounds  such
that for all ,  and  and the following
constraint system is satisfied:




If no such bounds can be found, a compile time error results.  If such
bounds are found, the pattern matching clause starting with  is
then typed under the assumption that each  has lower bound
instead of  and has upper bound  instead of .

The expected type of every block  is the expected type of the
whole pattern matching expression.  The type of the pattern matching
expression is then the weak least upper bound
(sec:weakconformance)
of the types of all blocks
.

When applying a pattern matching expression to a selector value,
patterns are tried in sequence until one is found which matches the
selector value (sec:patterns). Say this case is
.  The result of the whole expression is then the result of
evaluating , where all pattern variables of  are bound to
the corresponding parts of the selector value.  If no matching pattern
is found, a scala.MatchError exception is thrown.

The pattern in a case may also be followed by a guard suffix
if e with a boolean expression .  The guard expression is
evaluated if the preceding pattern in the case matches. If the guard
expression evaluates to true, the pattern match succeeds as
normal. If the guard expression evaluates to false, the pattern
in the case is considered not to match and the search for a matching
pattern continues.

In the interest of efficiency the evaluation of a pattern matching
expression may try patterns in some other order than textual
sequence. This might affect evaluation through
side effects in guards. However, it is guaranteed that a guard
expression is evaluated only if the pattern it guards matches.

If the selector of a pattern match is an instance of a
class (sec:modifiers),
the compilation of pattern matching can emit warnings which diagnose
that a given set of patterns is not exhaustive, i.e. that there is a
possibility of a MatchError being raised at run-time.

ex:eval
 Consider the following definitions of arithmetic terms:


abstract class Term[T]
case class Lit(x: Int) extends Term[Int]
case class Succ(t: Term[Int]) extends Term[Int]
case class IsZero(t: Term[Int]) extends Term[Boolean]
case class If[T](c: Term[Boolean],
                 t1: Term[T],
                 t2: Term[T]) extends Term[T]

There are terms to represent numeric literals, incrementation, a zero
test, and a conditional. Every term carries as a type parameter the
type of the expression it representes (either Int or Boolean).

A type-safe evaluator for such terms can be written as follows.

def eval[T](t: Term[T]): T = t match
  case Lit(n)        => n
  case Succ(u)       => eval(u) + 1
  case IsZero(u)     => eval(u) == 0
  case If(c, u1, u2) => eval(if (eval(c)) u1 else u2)


Note that the evaluator makes crucial use of the fact that type
parameters of enclosing methods can acquire new bounds through pattern
matching.

For instance, the type of the pattern in the second case,
 (u)@, is Int. It conforms to the selector type
T only if we assume an upper and lower bound of Int for T.
Under the assumption  <: T <: Int@  we can also
verify that the type right hand side of the second case, Int
conforms to its expected type, T.

Pattern Matching Anonymous Functions


lstlisting
  BlockExpr ::= `' CaseClauses `'


An anonymous function can be defined by a sequence of cases

 case  =>   case  =>

which appear as an expression without a prior match.  The
expected type of such an expression must in part be defined. It must
be either  .Function[, ]@  for some ,
or  .PartialFunction[, ]@, where the
argument type(s)  must be fully determined, but the result type
 may be undetermined.

If the expected type is  .Function[, ]@ ,
the expression is taken to be equivalent to the anonymous function:

() => () match
  case  =>   case  =>


Here, each  is a fresh name.
As was shown in (sec:closures), this anonymous function is in turn
equivalent to the following instance creation expression, where
  is the weak least upper bound of the types of all .

new scala.Function[, ]
  def apply():  = () match
    case  =>   case  =>



If the expected type is  .PartialFunction[, ]@,
the expression is taken to be equivalent to the following instance creation expression:

new scala.PartialFunction[, ]
  def apply(: ):  = x match
    case  =>   case  =>

  def isDefinedAt(: ): Boolean =
    case  => true  case  => true
    case _ => false



Here,  is a fresh name and  is the weak least upper bound of the
types of all . The final default case in the isDefinedAt
method is omitted if one of the patterns  is
already a variable or wildcard pattern.

Here is a method which uses a fold-left operation
/: to compute the scalar product of
two vectors:

def scalarProduct(xs: Array[Double], ys: Array[Double]) =
  (0.0 /: (xs zip ys))
    case (a, (b, c)) => a + b * c


The case clauses in this code are equivalent to the following
anonymous funciton:

  (x, y) => (x, y) match
    case (a, (b, c)) => a + b * c



Top-Level Definitions


Compilation Units

lstlisting
  CompilationUnit  ::=  `package' QualId semi TopStatSeq
  TopStatSeq       ::=  TopStat semi TopStat
  TopStat          ::=  Annotation Modifier TmplDef
                       Import
                       Packaging
                       PackageObject

  QualId           ::=  id `.' id


A compilation unit consists of a sequence of packagings, import
clauses, and class and object definitions, which may be preceded by a
package clause.

A compilation unit

package ;

package ;


starting with one or more package
clauses is equivalent to a compilation unit consisting of the
packaging

package
  package





Implicitly imported into every compilation unit are, in that order :
the package java.lang, the package scala, and the object
scala.Predef (cls:predef). Members of a later import in
that order hide members of an earlier import.

Packagings

lstlisting
  Packaging       ::=  `package' QualId [nl] `' TopStatSeq `'


A package is a special object which defines a set of member classes,
objects and packages.  Unlike other objects, packages are not introduced
by a definition.  Instead, the set of members of a package is determined by
packagings.

A packaging     @  injects all
definitions in  as members into the package whose qualified name
is . Members of a package are called top-level definitions.
If a definition in  is labeled private, it is
visible only for other members in the package.

Inside the packaging, all members of package  are visible under their
simple names. However this rule does not extend to members of enclosing
packages of  that are designated by a prefix of the path .

Given the packaging

package org.net.prj
  ...


all members of package .net.prj@ are visible under their
simple names, but members of packages org or org.net require
explicit qualification or imports.

Selections . from  as well as imports from
work as for objects. However, unlike other objects, packages may not
be used as values. It is illegal to have a package with the same fully
qualified name as a module or a class.

Top-level definitions outside a packaging are assumed to be injected
into a special empty package. That package cannot be named and
therefore cannot be imported. However, members of the empty package
are visible to each other without qualification.

Package Objects


lstlisting
  PackageObject   ::=  `package' `object' ObjectDef


A package object  object  extends @  adds the
members of template  to the package . There can be only one
package object per package. The standard naming convention is to place
the definition above in a file named .scala@ that's
located in the directory corresponding to package .

The package object should not define a member with the same name as
one of the top-level objects or classes defined in package . If
there is a name conflict, the behavior of the program is currently
undefined. It is expected that this restriction will be lifted in a
future version of Scala.

Package References

lstlisting
  QualId           ::=  id `.' id

A reference to a package takes the form of a qualified identifier.
Like all other references, package references are relative. That is,
a package reference starting in a name  will be looked up in the
closest enclosing scope that defines a member named .

The special predefined name _root_@  refers to the
outermost root package which contains all top-level packages.

ex:package-ids
Consider the following program:

package b
  class B


package a.b
  class A
    val x = new _root_.b.B



Here, the reference _root_.b.B refers to class B in the
toplevel package b. If the _root_ prefix had been
omitted, the name b would instead resolve to the package
a.b, and, provided that package does not also
contain a class B, a compiler-time error would result.

Programs

A program is a top-level object that has a member method
main of type  (Array[String])Unit@. Programs can be
executed from a command shell. The program's command arguments are are
passed to the main method as a parameter of type
Array[String].

The main method of a program can be directly defined in the
object, or it can be inherited. The scala library defines a class
scala.Application that defines an empty inherited main method.
An objects  inheriting from this class is thus a program,
which executes the initializaton code of the object .

The following example will create a hello world program by defining
a method main in module test.HelloWorld.

package test
object HelloWord
  def main(args: Array[String])  println("hello world")



This program can be started by the command

scala test.HelloWorld

In a Java environment, the command

java test.HelloWorld

would work as well.

HelloWorld can also be defined without a main method
by inheriting from Application instead:

package test
object HelloWord extends Application
  println("hello world")



XML expressions and patterns

By Burak Emir


This chapter describes the syntactic structure of XML expressions and patterns.
It follows as closely as possible the XML 1.0 specification ,
changes being mandated by the possibility of embedding Scala code fragments.

XML expressions
XML expressions are expressions generated by the following production, where the
opening bracket `<' of the first element must be in a position to start the lexical
XML mode (sec::xmlMode).

lstlisting
XmlExpr ::= XmlContent Element

Well-formedness constraints of the XML specification apply, which
means for instance that start tags and end tags must match, and
attributes may only be defined once, with the exception of constraints
related to entity resolution.

The following productions describe Scala's extensible markup language,
designed as close as possible to the W3C extensible markup language
standard. Only the productions for attribute values and character data
are changed. Scala does not support declarations, CDATA
sections or processing instructions. Entity references are not
resolved at runtime.

lstlisting
Element       ::=    EmptyElemTag
                    STag Content ETag

EmptyElemTag  ::=    `<' Name S Attribute [S] `/>'

STag          ::=    `<' Name S Attribute [S] `>'
ETag          ::=    `</' Name [S] '>'
Content       ::=    [CharData] Content1 [CharData]
Content1      ::=    XmlContent
                    Reference
                    ScalaExpr
XmlContent    ::=    Element
                    CDSect
                    PI
                    Comment


If an XML expression is a single element, its value is a runtime
representation of an XML node (an instance of a subclass of
.xml.Node@). If the XML expression consists of more
than one element, then its value is a runtime representation of a
sequence of XML nodes (an instance of a subclass of
.Seq[scala.xml.Node]@).

If an XML expression is an entity reference, CDATA section, processing
instructions or a comments, it is represented by an instance of the
corresponding Scala runtime class.

By default, beginning and trailing whitespace in element content is removed,
and consecutive occurrences of whitespace are replaced by a single space
character 0020. This behavior can be changed to preserve all whitespace
with a compiler option.

lstlisting
Attribute  ::=    Name Eq AttValue

AttValue      ::=    `"' CharQ  CharRef `"'
                    `'' CharA  CharRef `''
                    ScalaExpr

ScalaExpr     ::=    Block

CharData      ::=    CharNoRef   CharNoRef`'CharB CharNoRef
                                   CharNoRef`]]>'CharNoRef

XML expressions may contain Scala expressions as attribute values or
within nodes. In the latter case, these are embedded using a single opening
brace `' and ended by a closing brace `'. To express a single opening braces
within XML text as generated by CharData, it must be doubled. Thus, `'
represents the XML text `' and does not introduce an embedded Scala
expression.

lstlisting
BaseChar, Char, Comment, CombiningChar, Ideographic, NameChar, S, Reference
              ::=

Char1         ::=  Char  `<'  `&'
CharQ         ::=  Char1  `"'
CharA         ::=  Char1  `''
CharB         ::=  Char1  ''

Name          ::=  XNameStart NameChar

XNameStart    ::= `_'  BaseChar  Ideographic
                  `:'


XML patterns
XML patterns are patterns generated by the following production, where
the opening bracket `<' of the element patterns must be in a position
to start the lexical XML mode (sec::xmlMode).

lstlisting
XmlPattern  ::= ElementPattern

Well-formedness constraints of the XML specification apply.

An XML pattern has to be a single element pattern. It
matches exactly those runtime
representations of an XML tree
that have the same structure as described by the pattern.



XML patterns may contain Scala patterns(sec:pattern-match).

Whitespace is treated the same way as in XML expressions. Patterns
that are entity references, CDATA sections, processing
instructions and comments match runtime representations which are the
the same.

By default, beginning and trailing whitespace in element content is removed,
and consecutive occurrences of whitespace are replaced by a single space
character 0020. This behavior can be changed to preserve all whitespace
with a compiler option.

lstlisting
ElemPattern   ::=    EmptyElemTagP
                    STagP ContentP ETagP

EmptyElemTagP ::=    `<' Name [S] `/>'
STagP         ::=    `<' Name [S] `>'
ETagP         ::=    `</' Name [S]`>'
ContentP      ::=    [CharData] (ElemPatternScalaPatterns) [CharData]
ContentP1     ::=    ElemPattern
                    Reference
                    CDSect
                    PI
                    Comment
                    ScalaPatterns
ScalaPatterns ::=    `' Patterns `'



User-Defined Annotations


lstlisting
  Annotation       ::=  `@' SimpleType ArgumentExprs
  ConstrAnnotation ::=  `@' SimpleType ArgumentExprs


User-defined annotations associate meta-information with definitions.
A simple annotation has the form ^@^ or
^@^.
Here,  is a constructor of a class , which must conform
to the class .Annotation@.

Annotations may apply to definitions or declarations, types, or
expressions.  An annotation of a definition or declaration appears in
front of that definition.  An annotation of a type appears after
that type. An annotation of an expression  appears after the
expression , separated by a colon. More than one annotation clause
may apply to an entity. The order in which these annotations are given
does not matter.

Examples:

@serializable class C  ...          // A class annotation.
@transient @volatile var m: Int       // A variable annotation
String @local                         // A type annotation
(e: @unchecked) match  ...          // An expression annotation


The meaning of annotation clauses is implementation-dependent. On the
Java platform, the following annotations have a standard meaning.

^@transient^

Marks a field to be non-persistent; this is
equivalent to the ^transient^
modifier in Java.


^@volatile^
Marks a field which can change its value
outside the control of the program; this
is equivalent to the ^volatile^
modifier in Java.


^@serializable^
Marks a class to be serializable; this is
equivalent to inheriting from the
^java.io.Serializable^ interface
in Java.


^@SerialVersionUID(<longlit>)^
Attaches a serial version identifier (a
^long^ constant) to a class.
This is equivalent to a the following field
definition in Java:
[language=Java]
  private final static SerialVersionUID = <longlit>



^@throws(<classlit>)^

A Java compiler checks that a program contains handlers for checked exceptions
by analyzing which checked exceptions can result from execution of a method or
constructor. For each checked exception which is a possible result, the throws
clause for the method or constructor must mention the class of that exception
or one of the superclasses of the class of that exception.


^@deprecated(<stringlit>)^
 Marks a definition as deprecated. Accesses to the
  defined entity will then cause a deprecated warning mentioning the
  message <stringlit> to be issued from the compiler.  Deprecated
  warnings are suppressed in code that belongs itself to a definition
  that is labeled deprecated.


^@scala.reflect.BeanProperty^

When prefixed to a definition of some variable X, this
annotation causes getter and setter methods getX, setX
in the Java bean style to be added in the class containing the
variable. The first letter of the variable appears capitalized after
the get or set. When the annotation is added to the
definition of an immutable value definition X, only a getter is
generated. The construction of these methods is part of
code-generation; therefore, these methods become visible only once a
classfile for the containing class is generated.


^@scala.reflect.BooleanBeanProperty^

This annotation is equivalent to scala.reflect.BeanProperty, but
the generated getter method is named isX instead of getX.


^@unchecked^

When applied to the selector of a expression,
this attribute suppresses any warnings about non-exhaustive pattern
matches which would otherwise be emitted. For instance, no warnings
would be produced for the method definition below.

def f(x: Option[Int]) = (x: @unchecked) match
  case Some(y) => y


Without the ^@unchecked^ annotation, a Scala compiler could
infer that the pattern match is non-exhaustive, and could produce a
warning because is a class.


^@uncheckedStable^

When applied a value declaration or definition, it allows the defined
value to appear in a path, even if its type is volatile (volatile-types).
For instance, the following member definitions are legal:

type A  type T
type B
@uncheckedStable val x: A with B // volatile type
val y: x.T                       // OK since `x' is still a path

Without the ^@uncheckedStable^ annotation, the designator x
would not be a path since its type A with B is volatile. Hence,
the reference x.T would be malformed.

When applied to value declarations or definitions that have non-volatile types,
the annotation has no effect.


^@specialized^

When applied to the definition of a type parameter, this annotation causes the compiler
to generate specialized definitions for primitive types. An optional list of primitive
types may be given, in which case specialization takes into account only those types.
For instance, the following code would generate specialized traits for ,
and

trait Function0[@specialized(Unit, Int, Double) T]
  def apply: T


Whenever the static type of an expression matches a specialized variant of a definition,
the compiler will instead use the specialized version. See  for more details
of the implementation.



Other annotations may be interpreted by platform- or
application-dependent tools. Class scala.Annotation has two
sub-traits which are used to indicate how these annotations are
retained. Instances of an annotation class inheriting from trait
scala.ClassfileAnnotation will be stored in the generated class
files. Instances of an annotation class inheriting from trait
scala.StaticAnnotation will be visible to the Scala type-checker
in every compilation unit where the annotated symbol is accessed. An
annotation class can inherit from both scala.ClassfileAnnotation
and scala.StaticAnnotation. If an annotation class inherits from
neither scala.ClassfileAnnotation nor
scala.StaticAnnotation, its instances are visible only locally
during the compilation run that analyzes them.

Classes inheriting from scala.ClassfileAnnotation may be
subject to further restrictions in order to assure that they can be
mapped to the host environment. In particular, on both the Java and
the .NET platforms, such classes must be toplevel; i.e. they may not
be contained in another class or object.  Additionally, on both
Java and .NET, all constructor arguments must be constant expressions.


The Scala Standard Library

The Scala standard library consists of the package scala with a
number of classes and modules. Some of these classes are described in
the following.







*

Root Classes




Figure  illustrates Scala's class
hierarchy.
The root of this hierarchy is formed by class Any.
Every class in a Scala execution environment inherits directly or
indirectly from this class.  Class Any has two direct
subclasses: AnyRef and AnyVal.

The subclass AnyRef represents all values which are represented
as objects in the underlying host system. Every user-defined Scala
class inherits directly or indirectly from this class. Furthermore,
every user-defined Scala class also inherits the trait
scala.ScalaObject.  Classes written in other languages still
inherit from scala.AnyRef, but not from
scala.ScalaObject.

The class AnyVal has a fixed number of subclasses, which describe
values which are not implemented as objects in the underlying host
system.

Classes AnyRef and AnyVal are required to provide only
the members declared in class Any, but implementations may add
host-specific methods to these classes (for instance, an
implementation may identify class AnyRef with its own root
class for objects).

The signatures of these root classes are described by the following
definitions.


package scala
/** The universal root class */
abstract class Any

  /** Defined equality; abstract here */
  def equals(that: Any): Boolean

  /** Semantic equality between values */
  final def == (that: Any): Boolean  =
    if (null eq this) null eq that else this equals that

  /** Semantic inequality between values */
  final def != (that: Any): Boolean  =  !(this == that)

  /** Hash code; abstract here */
  def hashCode: Int =

  /** Textual representation; abstract here */
  def toString: String =

  /** Type test; needs to be inlined to work as given */
  def isInstanceOf[a]: Boolean

  /** Type cast; needs to be inlined to work as given */ */
  def asInstanceOf[A]: A = this match
    case x: A => x
    case _ => if (this eq null) this
              else throw new ClassCastException()



/** The root class of all value types */
final class AnyVal extends Any

/** The root class of all reference types */
class AnyRef extends Any
  def equals(that: Any): Boolean      = this eq that
  final def eq(that: AnyRef): Boolean =  // reference equality
  final def ne(that: AnyRef): Boolean = !(this eq that)

  def hashCode: Int =      // hashCode computed from allocation address
  def toString: String  =  // toString computed from hashCode and class name

/** A mixin class for every user-defined Scala class */
trait ScalaObject extends AnyRef


The type test .isInstanceOf[]@ is equivalent to a typed
pattern match

 match
  case _:  => true
  case _ => false


where the type  is the same as  except if  is
of the form  or  where  is a type member of some outer
class . In this case  is #@ (or
#@, respectively), whereas  itself would
expand to .this.@. In other words, an
test does not check for the


The test  .asInstanceOf[]@ is treated specially if  is a
numeric value type (sec:cls-value). In this case the cast will
be translated to an application of a conversion method  .to@
(cls:numeric-value). For non-numeric values  the operation will raise a
ClassCastException.

Value Classes


Value classes are classes whose instances are not represented as
objects by the underlying host system.  All value classes inherit from
class AnyVal. Scala implementations need to provide the
value classes Unit, Boolean, Double, Float,
Long, Int, Char, Short, and Byte
(but are free to provide others as well).
The signatures of these classes are defined in the following.

Numeric Value Types

Classes Double, Float,
Long, Int, Char, Short, and Byte
are together called numeric value types. Classes Byte,
Short, or Char are called subrange types.
Subrange types, as well as Int and Long are called
integer types, whereas Float and Double are called
floating point types.

Numeric value types are ranked in the following partial order:


Byte - Short

               Int - Long - Float - Double
             /
        Char

Byte and Short are the lowest-ranked types in this order,
whereas Double is the highest-ranked.  Ranking does not
imply a conformance (sec:conformance) relationship; for
instance Int is not a subtype of Long.  However, object
Predef (cls:predef) defines views (sec:views)
from every numeric value type to all higher-ranked numeric value types. Therefore,
lower-ranked types are implicitly converted to higher-ranked types
when required by the context (sec:impl-conv).

Given two numeric value types  and , the operation type of
 and  is defined as follows: If both  and  are subrange
types then the operation type of  and  is Int.  Otherwise
the operation type of  and  is the larger of the two types wrt
ranking. Given two numeric values  and  the operation type of
 and  is the operation type of their run-time types.

Any numeric value type  supports the following methods.


Comparison methods for equals (==), not-equals (!=),
less-than (<), greater-than (>), less-than-or-equals
(<=), greater-than-or-equals (>=), which each exist in 7
overloaded alternatives. Each alternative takes a parameter of some
numeric value type. Its result type is type Boolean. The
operation is evaluated by converting the receiver and its argument to
their operation type and performing the given comparison operation of
that type.

Arithmetic methods addition (+), subtraction (-),
multiplication (*), division (/), and remainder
(
alternative takes a parameter of some numeric value type .  Its
result type is the operation type of  and . The operation is
evaluated by converting the receiver and its argument to their
operation type and performing the given arithmetic operation of that
type.

Parameterless arithmethic methods identity (+) and negation
(-), with result type .  The first of these returns the
receiver unchanged, whereas the second returns its negation.

Conversion methods toByte, toShort, toChar,
toInt, toLong, toFloat, toDouble which
convert the receiver object to the target type, using the rules of
Java's numeric type cast operation. The conversion might truncate the
numeric value (as when going from Long to Int or from
Int to Byte) or it might lose precision (as when going
from Double to Float or when converting between
Long and Float).


Integer numeric value types support in addition the following operations:


Bit manipulation methods bitwise-and (&), bitwise-or
, and bitwise-exclusive-or (^), which each exist in 5
overloaded alternatives. Each alternative takes a parameter of some
integer numeric value type. Its result type is the operation type of
 and . The operation is evaluated by converting the receiver and
its argument to their operation type and performing the given bitwise
operation of that type.

A parameterless bit-negation method ( @). Its result type is
the reciver type  or Int, whichever is larger.
The operation is evaluated by converting the receiver to the result
type and negating every bit in its value.

Bit-shift methods left-shift (<<), arithmetic right-shift
(>>), and unsigned right-shift (>>>). Each of these
methods has two overloaded alternatives, which take a parameter
of type Int, respectively Long. The result type of the
operation is the receiver type , or Int, whichever is larger.
The operation is evaluated by converting the receiver to the result
type and performing the specified shift by  bits.


Numeric value types also implement operations equals,
hashCode, and toString from class Any.

The equals method tests whether the argument is a numeric value
type. If this is true, it will perform the == operation which
is appropriate for that type. That is, the equals method of a
numeric value type can be thought of being defined as follows:

def equals(other: Any): Boolean = other match
  case that: Byte   => this == that
  case that: Short  => this == that
  case that: Char   => this == that
  case that: Int    => this == that
  case that: Long   => this == that
  case that: Float  => this == that
  case that: Double => this == that
  case _ => false


The hashCode method returns an integer hashcode that maps equal
numeric values to equal results. It is guaranteed to be the identity for
for type Int and for all subrange types.

The toString method displays its receiver as an integer or
floating point number.

As an example, here is the signature of the numeric value type Int:


package scala
abstract sealed class Int extends AnyVal
  def == (that: Double): Boolean  // double equality
  def == (that: Float): Boolean   // float equality
  def == (that: Long): Boolean    // long equality
  def == (that: Int): Boolean     // int equality
  def == (that: Short): Boolean   // int equality
  def == (that: Byte): Boolean    // int equality
  def == (that: Char): Boolean    // int equality
  /* analogous for !=, <, >, <=, >= */

  def + (that: Double): Double    // double addition
  def + (that: Float): Double     // float addition
  def + (that: Long): Long        // long addition
  def + (that: Int): Int          // int addition
  def + (that: Short): Int        // int addition
  def + (that: Byte): Int         // int addition
  def + (that: Char): Int         // int addition
  /* analogous for -, *, /,

  def & (that: Long): Long        // long bitwise and
  def & (that: Int): Int          // int bitwise and
  def & (that: Short): Int        // int bitwise and
  def & (that: Byte): Int         // int bitwise and
  def & (that: Char): Int         // int bitwise and
  /* analogous for , ^ */

  def << (cnt: Int): Int          // int left shift
  def << (cnt: Long): Int         // long left shift
  /* analogous for >>, >>> */

  def unary_+ : Int               // int identity
  def unary_- : Int               // int negation
  def unary_  : Int               // int bitwise negation

  def toByte: Byte                // convert to Byte
  def toShort: Short              // convert to Short
  def toChar: Char                // convert to Char
  def toInt: Int                  // convert to Int
  def toLong: Long                // convert to Long
  def toFloat: Float              // convert to Float
  def toDouble: Double            // convert to Double



Class Boolean


Class Boolean has only two values: true and
false. It implements operations as given in the following
class definition.

package scala
abstract sealed class Boolean extends AnyVal
  def && (p: => Boolean): Boolean = // boolean and
    if (this) p else false
  def  (p: => Boolean): Boolean = // boolean or
    if (this) true else p
  def &  (x: Boolean): Boolean =    // boolean strict and
    if (this) x else false
  def   (x: Boolean): Boolean =    // boolean strict or
    if (this) true else x
  def == (x: Boolean): Boolean =    // boolean equality
    if (this) x else x.unary_!
  def != (x: Boolean): Boolean      // boolean inequality
    if (this) x.unary_! else x
  def unary_!: Boolean              // boolean negation
    if (this) false else true


The class also implements operations equals, hashCode,
and toString from class Any.

The equals method returns true if the argument is the
same boolean value as the receiver, false otherwise.  The
hashCode method returns a fixed, implementation-specific hash-code when invoked on true,
and a different, fixed, implementation-specific hash-code when invoked on false. The toString method
returns the receiver converted to a string, i.e. either "true"
or "false".

Class Unit

Class Unit has only one value: (). It implements only
the three methods equals, hashCode, and toString
from class Any.

The equals method returns true if the argument is the
unit value ()@, false otherwise.  The
hashCode method returns a fixed, implementation-specific hash-code,
The toString method returns "()".

Standard Reference Classes


This section presents some standard Scala reference classes which are
treated in a special way in Scala compiler -- either Scala provides
syntactic sugar for them, or the Scala compiler generates special code
for their operations. Other classes in the standard Scala library are
documented in the Scala library documentation by HTML pages.

Class String

Scala's class is usually derived from the standard String
class of the underlying host system (and may be identified with
it). For Scala clients the class is taken to support in each case a
method

def + (that: Any): String

which concatenates its left operand with the textual representation of its
right operand.

The Tuple classes

Scala defines tuple classes @ for .
These are defined as follows.


package scala
case class Tuple[+a_1, ..., +a_n](_1: a_1, ..., _: a_)
  def toString = "(" ++ _1 ++ "," ++  ++ "," ++ _ ++ ")"



The implicitly imported Predef object (cls:predef) defines
the names Pair as an alias of Tuple2 and Triple
as an alias for Tuple3.

The Function Classes


Scala defines function classes @ for .
These are defined as follows.


package scala
trait Function[-a_1, ..., -a_, +b]
  def apply(x_1: a_1, ..., x_: a_): b
  def toString = "<function>"




There is also a module Function, defined as follows.

package scala
object Function
  def compose[A](fs: List[A => A]): A => A =
    x => fs match
      case Nil => x
      case f :: fs1 => compose(fs1)(f(x))





A subclass of 1@ represents partial functions,
which are undefined on some points in their domain. In addition to the
apply method of functions, partial functions also have a
isDefined method, which tells whether the function is defined
at the given argument:

class PartialFunction[-A, +B] extends Function1[A, B]
  def isDefinedAt(x: A): Boolean



The implicitly imported Predef object (cls:predef) defines the name
Function as an alias of Function1.

Class Array

The class of generic arrays is given as follows.


final class Array[A](len: Int) extends Seq[A]
  def length: Int = len
  def apply(i: Int): A =
  def update(i: Int, x: A): Unit =
  def elements: Iterator[A] =
  def subArray(from: Int, end: Int): Array[A] =
  def filter(p: A => Boolean): Array[A] =
  def map[B](f: A => B): Array[B] =
  def flatMap[B](f: A => Array[B]): Array[B] =


If  is not a type parameter or abstract type, the type Array[]
is represented as the native array type [] in the
underlying host system. In that case length returns
the length of the array, apply means subscripting, and
update means element update. Because of the syntactic sugar for
apply and

update operations (sec:impl-conv,
we have the following correspondences between Scala and Java/C code for
operations on an array xs:



  xs.length        xs.length
  xs(i)            xs[i]
  xs(i) = e        xs[i] = e


Arrays also implement the sequence trait scala.Seq
by defining an elements method which returns
all elements of the array in an Iterator.

Because of the tension between parametrized types in Scala and the ad-hoc
implementation of arrays in the host-languages, some subtle points
need to be taken into account when dealing with arrays. These are
explained in the following.

First, unlike arrays in Java or C, arrays in Scala are not
co-variant; That is,  does not imply
 []  Array[]@ in Scala.
However, it is possible to cast an array
of  to an array of  if such a cast is permitted in the host
environment.

For instance Array[String] does not conform to
Array[Object], even though String conforms to Object.
However, it is possible to cast an expression of type
 [String]@  to  [Object]@, and this
cast will succeed without raising a ClassCastException. Example:

val xs = new Array[String](2)
// val ys: Array[Object] = xs   // **** error: incompatible types
val ys: Array[Object] = xs.asInstanceOf[Array[Object]] // OK


Second, for polymorphic arrays, that have a type parameter or
abstract type  as their element type, a representation different
from
[]T@ might be used. However, it is guaranteed that
isInstanceOf and asInstanceOf still work as if the array
used the standard representation of monomorphic arrays:

val ss = new Array[String](2)

def f[T](xs: Array[T]): Array[String] =
  if (xs.isInstanceOf[Array[String]]) xs.asInstanceOf[Array[String])
  else throw new Error("not an instance")

f(ss)                                     // returns ss

The representation chosen for polymorphic arrays also guarantees that
polymorphic array creations work as expected. An example is the
following implementation of method , which creates
an array of an arbitrary type , given a sequence of 's which
defines its elements.

def mkArray[T](elems: Seq[T]): Array[T] =
  val result = new Array[T](elems.length)
  var i = 0
  for (elem <- elems)
    result(i) = elem
    i += 1



Note that under Java's erasure model of arrays the method above would
not work as expected -- in fact it would always return an array of
.

Third, in a Java environment there is a method System.arraycopy
which takes two objects as parameters together with start indices and
a length argument, and copies elements from one object to the other,
provided the objects are arrays of compatible element
types. System.arraycopy will not work for Scala's polymorphic
arrays because of their different representation. One should instead
use method Array.copy which is defined in the companion object
of class . This companion object also defines various
constructor methods for arrays, as well as
the extractor method unapplySeq (sec:extractor-patterns)
which enables pattern matching over arrays.

package scala
object Array
  /** copies array elements from `src' to `dest'. */
  def copy(src: AnyRef, srcPos: Int,
           dest: AnyRef, destPos: Int, length: Int): Unit =

  /** Concatenate all argument arrays into a single array. */
  def concat[T](xs: Array[T]*): Array[T] =

  /** Create a an array of successive integers. */
  def range(start: Int, end: Int): Array[Int] =

  /** Create an array with given elements. */
  def apply[A <: AnyRef](xs: A*): Array[A] =

  /** Analogous to above. */
  def apply(xs: Boolean*): Array[Boolean] =
  def apply(xs: Byte*)   : Array[Byte]    =
  def apply(xs: Short*)  : Array[Short]   =
  def apply(xs: Char*)   : Array[Char]    =
  def apply(xs: Int*)    : Array[Int]     =
  def apply(xs: Long*)   : Array[Long]    =
  def apply(xs: Float*)  : Array[Float]   =
  def apply(xs: Double*) : Array[Double]  =
  def apply(xs: Unit*)   : Array[Unit]    =

  /** Create an array containing several copies of an element. */
  def make[A](n: Int, elem: A): Array[A] =

  /** Enables pattern matching over arrays */
  def unapplySeq[A](x: Array[A]): Option[Seq[A]] = Some(x)



The following method duplicates a given argument array and returns a pair consisting of the original and the duplicate:

def duplicate[T](xs: Array[T]) =
  val ys = new Array[T](xs.length)
  Array.copy(xs, 0, ys, 0, xs.length)
  (xs, ys)



Class Node

package scala.xml

trait Node

  /** the label of this node */
  def label: String

  /** attribute axis */
  def attribute: Map[String, String]

  /** child axis (all children of this node) */
  def child: Seq[Node]

  /** descendant axis (all descendants of this node) */
  def descendant: Seq[Node] = child.toList.flatMap
    x => x::x.descendant.asInstanceOf[List[Node]]


  /** descendant axis (all descendants of this node) */
  def descendant_or_self: Seq[Node] = this::child.toList.flatMap
    x => x::x.descendant.asInstanceOf[List[Node]]


  override def equals(x: Any): Boolean = x match
    case that:Node =>
      that.label == this.label &&
        that.attribute.sameElements(this.attribute) &&
          that.child.sameElements(this.child)
    case _ => false


 /** XPath style projection function. Returns all children of this node
  *  that are labeled with 'that'. The document order is preserved.
  */
    def