Next round of additions for tour

Author: jsuereth

tour/abstract-types.md

@@ -0,0 +1,62 @@
+---
+layout: overview
+title: Abstract Types
+---
+
+In Scala, classes are parameterized with values (the constructor parameters) and with types (if classes are [generic](generic-classes.html)). For reasons of regularity, it is not only possible to have values as object members; types along with values are members of objects. Furthermore, both forms of members can be concrete and abstract.
+Here is an example which defines both a deferred value definition and an abstract type definition as members of [class](traits.html) `Buffer`.
+ 
+    trait Buffer {
+      type T
+      val element: T
+    }
+ 
+*Abstract types* are types whose identity is not precisely known. In the example above, we only know that each object of class `Buffer` has a type member `T`, but the definition of class `Buffer` does not reveal to what concrete type the member type `T` corresponds. Like value definitions, we can override type definitions in subclasses. This allows us to reveal more information about an abstract type by tightening the type bound (which describes possible concrete instantiations of the abstract type).
+
+In the following program we derive a class `SeqBuffer` which allows us to store only sequences in the buffer by stating that type `T` has to be a subtype of `Seq[U]` for a new abstract type `U`:
+ 
+    abstract class SeqBuffer extends Buffer {
+      type U
+      type T <: Seq[U]
+      def length = element.length
+    }
+ 
+Traits or [classes](classes.html) with abstract type members are often used in combination with anonymous class instantiations. To illustrate this, we now look at a program which deals with a sequence buffer that refers to a list of integers:
+ 
+    abstract class IntSeqBuffer extends SeqBuffer {
+      type U = Int
+    }
+    
+    object AbstractTypeTest1 extends Application {
+      def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer =
+        new IntSeqBuffer {
+             type T = List[U]
+             val element = List(elem1, elem2)
+           }
+      val buf = newIntSeqBuf(7, 8)
+      println("length = " + buf.length)
+      println("content = " + buf.element)
+    }
+ 
+The return type of method `newIntSeqBuf` refers to a specialization of trait `Buffer` in which type `U` is now equivalent to `Int`. We have a similar type alias in the anonymous class instantiation within the body of method `newIntSeqBuf`. Here we create a new instance of `IntSeqBuffer` in which type `T` refers to List[Int].
+
+Please note that it is often possible to turn abstract type members into type parameters of classes and vice versa. Here is a version of the code above which only uses type parameters:
+ 
+    abstract class Buffer[+T] {
+      val element: T
+    }
+    abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] {
+      def length = element.length
+    }
+    object AbstractTypeTest2 extends Application {
+      def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] =
+        new SeqBuffer[Int, List[Int]] {
+          val element = List(e1, e2)
+        }
+      val buf = newIntSeqBuf(7, 8)
+      println("length = " + buf.length)
+      println("content = " + buf.element)
+    }
+ 
+Note that we have to use [variance annotations](variances.html) here; otherwise we would not be able to hide the concrete sequence implementation type of the object returned from method `newIntSeqBuf`.  Furthermore, there are cases where it is not possible to replace abstract types with type parameters.
+

tour/compound-types.md

@@ -0,0 +1,36 @@
+---
+layout: overview
+title: Compound Types
+---
+
+Sometimes it is necessary to express that the type of an object is a subtype of several other types. In Scala this can be expressed with the help of *compound types*, which are intersections of object types.
+
+Suppose we have two traits `Cloneable` and `Resetable`:
+
+    trait Cloneable extends java.lang.Cloneable {
+      override def clone(): Cloneable = { super.clone(); this }
+    }
+    trait Resetable {
+      def reset: Unit
+    }
+
+Now suppose we want to write a function `cloneAndReset` which takes an object, clones it and resets the original object:
+
+    def cloneAndReset(obj: ?): Cloneable = {
+      val cloned = obj.clone()
+      obj.reset
+      cloned
+    }
+
+The question arises what the type of the parameter `obj` is. If it's `Cloneable` then the object can be `clone`d, but not `reset`; if it's `Resetable` we can `reset` it, but there is no `clone` operation. To avoid type casts in such a situation, we can specify the type of `obj` to be both `Cloneable` and `Resetable`. This compound type is written like this in Scala: `Cloneable with Resetable`.
+
+Here's the updated function:
+
+    def cloneAndReset(obj: Cloneable with Resetable): Cloneable = {
+      //...
+    }
+
+Compound types can consist of several object types and they may have a single refinement which can be used to narrow the signature of existing object members.
+The general form is: `A with B with C ... { refinement }`
+
+An example for the use of refinements is given on the page about [abstract types](abstract-types.html). 

tour/generic-classes.md

@@ -0,0 +1,34 @@
+---
+layout: overview
+title: Generic Classes
+---
+
+Like in Java 5 (aka. [JDK 1.5](http://java.sun.com/j2se/1.5/)), Scala has built-in support for classes parameterized with types. Such generic classes are particularly useful for the development of collection classes.
+Here is an example which demonstrates this:
+
+    class Stack[T] {
+      var elems: List[T] = Nil
+      def push(x: T) { elems = x :: elems }
+      def top: T = elems.head
+      def pop() { elems = elems.tail }
+    }
+
+Class `Stack` models imperative (mutable) stacks of an arbitrary element type `T`. The type parameters enforces that only legal elements (that are of type `T`) are pushed onto the stack. Similarly, with type parameters we can express that method `top` will only yield elements of the given type.
+
+Here are some usage examples:
+
+    object GenericsTest extends Application {
+      val stack = new Stack[Int]
+      stack.push(1)
+      stack.push('a')
+      println(stack.top)
+      stack.pop()
+      println(stack.top)
+    }
+
+The output of this program will be:
+
+    97
+    1
+
+_Note: subtyping of generic types is *invariant*. This means that if we have a stack of characters of type `Stack[Char]` then it cannot be used as an integer stack of type `Stack[Int]`. This would be unsound because it would enable us to enter true integers into the character stack. To conclude, `Stack[T]` is only a subtype of `Stack[S]` if and only if `S = T`. Since this can be quite restrictive, Scala offers a [type parameter annotation mechanism](variances.html) to control the subtyping behavior of generic types._

tour/index.md

@@ -15,14 +15,14 @@ Furthermore, Scala's notion of pattern matching naturally extends to the process
 
 ## Scala is statically typed ##
 Scala is equipped with an expressive type system that enforces statically that abstractions are used in a safe and coherent manner. In particular, the type system supports:
-* generic classes
-* variance annotations
-* upper and lower type bounds,
-* inner classes and abstract types as object members
-* compound types
+* [generic classes](generic-classes.html)
+* [variance annotations](variances.html)
+* [upper](upper-type-bounds.html) and [lower](lower-type-bouunds.html) type bounds,
+* [inner classes](inner-classes.html) and [abstract types](abstract-types.html) as object members
+* [compound types](compound-types.html)
 * explicitly typed self references
 * views
-* polymorphic methods
+* [polymorphic methods](polymorphic-methods.html)
 
 A local type inference mechanism takes care that the user is not required to annotate the program with redundant type information. In combination, these features provide a powerful basis for the safe reuse of programming abstractions and for the type-safe extension of software.
 

tour/inner-classes.md

@@ -0,0 +1,79 @@
+---
+layout: overview
+title: Inner Classes
+---
+
+In Scala it is possible to let classes have other classes as members. Opposed to Java-like languages where such inner classes are members of the enclosing class, in Scala such inner classes are bound to the outer object. To illustrate the difference, we quickly sketch the implementation of a graph datatype:
+ 
+    class Graph {
+      class Node {
+        var connectedNodes: List[Node] = Nil
+        def connectTo(node: Node) {
+          if (connectedNodes.find(node.equals).isEmpty) {
+            connectedNodes = node :: connectedNodes
+          }
+        }
+      }
+      var nodes: List[Node] = Nil
+      def newNode: Node = {
+        val res = new Node
+        nodes = res :: nodes
+        res
+      }
+    }
+ 
+In our program, graphs are represented by a list of nodes. Nodes are objects of inner class `Node`. Each node has a list of neighbours, which get stored in the list `connectedNodes`. Now we can set up a graph with some nodes and connect the nodes incrementally:
+ 
+    object GraphTest extends Application {
+      val g = new Graph
+      val n1 = g.newNode
+      val n2 = g.newNode
+      val n3 = g.newNode
+      n1.connectTo(n2)
+      n3.connectTo(n1)
+    }
+ 
+We now enrich the following example with types to state explicitly what the type of the various defined entities is:
+ 
+    object GraphTest extends Application {
+      val g: Graph = new Graph
+      val n1: g.Node = g.newNode
+      val n2: g.Node = g.newNode
+      val n3: g.Node = g.newNode
+      n1.connectTo(n2)
+      n3.connectTo(n1)
+    }
+ 
+This code clearly shows that a node type is prefixed with its outer instance (which is object g in our example). If we now have two graphs, the type system of Scala does not allow us to mix nodes defined within one graph with the nodes of another graph, since the nodes of the other graph have a different type.
+Here is an illegal program:
+ 
+    object IllegalGraphTest extends Application {
+      val g: Graph = new Graph
+      val n1: g.Node = g.newNode
+      val n2: g.Node = g.newNode
+      n1.connectTo(n2)      // legal
+      val h: Graph = new Graph
+      val n3: h.Node = h.newNode
+      n1.connectTo(n3)      // illegal!
+    }
+ 
+Please note that in Java the last line in the previous example program would have been correct. For nodes of both graphs, Java would assign the same type `Graph.Node`; i.e. `Node` is prefixed with class `Graph`. In Scala such a type can be expressed as well, it is written `Graph#Node`. If we want to be able to connect nodes of different graphs, we have to change the definition of our initial graph implementation in the following way:
+ 
+    class Graph {
+      class Node {
+        var connectedNodes: List[Graph#Node] = Nil
+        def connectTo(node: Graph#Node) {
+          if (connectedNodes.find(node.equals).isEmpty) {
+            connectedNodes = node :: connectedNodes
+          }
+        }
+      }
+      var nodes: List[Node] = Nil
+      def newNode: Node = {
+        val res = new Node
+        nodes = res :: nodes
+        res
+      }
+    }
+ 
+> Please note that this program doesn't allow us to attach a node to two different graphs. If we want to remove this restriction as well, we have to change the type of variable nodes and the return type of method `newNode` to `Graph#Node`.

tour/lower-type-bounds.md

@@ -0,0 +1,42 @@
+---
+layout: overview
+title: Lower Type Bounds
+---
+
+While [upper type bounds](upper-type-bounds.html) limit a type to a subtype of another type, *lower type bounds* declare a type to be a supertype of another type. The term `T >: A` expresses that the type parameter `T` or the abstract type `T` refer to a supertype of type `A`.
+
+Here is an example where this is useful:
+
+    case class ListNode[T](h: T, t: ListNode[T]) {
+      def head: T = h
+      def tail: ListNode[T] = t
+      def prepend(elem: T): ListNode[T] =
+        ListNode(elem, this)
+    }
+
+The program above implements a linked list with a prepend operation. Unfortunately, this type is invariant in the type parameter of class `ListNode`; i.e. type `ListNode[String]` is not a subtype of type `List[Object]`. With the help of [variance annotations](variances.html) we can express such a subtype semantics:
+
+    case class ListNode[+T](h: T, t: ListNode[T]) { ... }
+
+Unfortunately, this program does not compile, because a covariance annotation is only possible if the type variable is used only in covariant positions. Since type variable `T` appears as a parameter type of method `prepend`, this rule is broken. With the help of a *lower type bound*, though, we can implement a prepend method where `T` only appears in covariant positions.
+
+Here is the corresponding code:
+
+    case class ListNode[+T](h: T, t: ListNode[T]) {
+      def head: T = h
+      def tail: ListNode[T] = t
+      def prepend[U >: T](elem: U): ListNode[U] =
+        ListNode(elem, this)
+    }
+
+_Note:_ the new `prepend` method has a slightly less restrictive type. It allows, for instance, to prepend an object of a supertype to an existing list. The resulting list will be a list of this supertype.
+
+Here is some code which illustrates this:
+
+    object LowerBoundTest extends Application {
+      val empty: ListNode[Null] = ListNode(null, null)
+      val strList: ListNode[String] = empty.prepend("hello")
+                                           .prepend("world")
+      val anyList: ListNode[Any] = strList.prepend(12345)
+    }
+

tour/polymorphic-methods.md

@@ -0,0 +1,19 @@
+---
+layout: overview
+title: Polymorphic Methods
+---
+
+Methods in Scala can be parameterized with both values and types. Like on the class level, value parameters are enclosed in a pair of parentheses, while type parameters are declared within a pair of brackets.
+
+Here is an example:
+ 
+    object PolyTest extends Application {
+      def dup[T](x: T, n: Int): List[T] =
+        if (n == 0) Nil
+        else x :: dup(x, n - 1)
+      println(dup[Int](3, 4))
+      println(dup("three", 3))
+    }
+ 
+Method `dup` in object PolyTest is parameterized with type T and with the value parameters `x: T` and `n: Int`. When method `dup` is called, the programmer provides the required parameters _(see line 5 in the program above)_, but as line 6 in the program above shows, the programmer is not required to give actual type parameters explicitly. The type system of Scala can infer such types. This is done by looking at the types of the given value parameters and at the context where the method is called.
+Please note that the trait `Application` is designed for writing short test programs, but should be avoided for production code (for scala versions 2.8.x and earlier) as it may affect the ability of the JVM to optimize the resulting code; please use `def main()` instead.

tour/upper-type-bounds.md

@@ -0,0 +1,28 @@
+---
+layout: overview
+title: Upper Type Bounds
+---
+
+In Scala, [type parameters](generic-classes.html) and [abstract types](abstract-types.html) may be constrained by a type bound. Such type bounds limit the concrete values of the type variables and possibly reveal more information about the members of such types. An _upper type bound_ `T <: A` declares that type variable `T` refers to a subtype of type `A`.
+Here is an example which relies on an upper type bound for the implementation of the polymorphic method `findSimilar`:
+
+    trait Similar {
+      def isSimilar(x: Any): Boolean
+    }
+    case class MyInt(x: Int) extends Similar {
+      def isSimilar(m: Any): Boolean =
+        m.isInstanceOf[MyInt] &&
+        m.asInstanceOf[MyInt].x == x
+    }
+    object UpperBoundTest extends Application {
+      def findSimilar[T <: Similar](e: T, xs: List[T]): Boolean =
+        if (xs.isEmpty) false
+        else if (e.isSimilar(xs.head)) true
+        else findSimilar[T](e, xs.tail)
+      val list: List[MyInt] = List(MyInt(1), MyInt(2), MyInt(3))
+      println(findSimilar[MyInt](MyInt(4), list))
+      println(findSimilar[MyInt](MyInt(2), list))
+    }
+
+Without the upper type bound annotation it would not be possible to call method `isSimilar` in method `findSimilar`.
+The usage of lower type bounds is discussed [here](lower-type-bounds.html). 

tour/variances.md

@@ -0,0 +1,31 @@
+---
+layout: overview
+title: Variances
+---
+
+Scala supports variance annotations of type parameters of [generic classes](generic-classes.html). In contrast to Java 5 (aka. [JDK 1.5](http://java.sun.com/j2se/1.5/)), variance annotations may be added when a class abstraction is defined, whereas in Java 5, variance annotations are given by clients when a class abstraction is used.
+
+In the page about generic classes an example for a mutable stack was given. We explained that the type defined by the class `Stack[T]` is subject to invariant subtyping regarding the type parameter. This can restrict the reuse of the class abstraction. We now derive a functional (i.e. immutable) implementation for stacks which does not have this restriction. Please note that this is an advanced example which combines the use of [polymorphic methods](polymorphic-methods.html), [lower type bounds](lower-type-bounds.html), and covariant type parameter annotations in a non-trivial fashion. Furthermore we make use of [inner classes](inner-classes.html) to chain the stack elements without explicit links.
+
+    class Stack[+A] {
+      def push[B >: A](elem: B): Stack[B] = new Stack[B] {
+        override def top: B = elem
+        override def pop: Stack[B] = Stack.this
+        override def toString() = elem.toString() + " " +
+                                  Stack.this.toString()
+      }
+      def top: A = error("no element on stack")
+      def pop: Stack[A] = error("no element on stack")
+      override def toString() = ""
+    }
+    
+    object VariancesTest extends Application {
+      var s: Stack[Any] = new Stack().push("hello");
+      s = s.push(new Object())
+      s = s.push(7)
+      Console.println(s)
+    }
+
+The annotation `+T` declares type `T` to be used only in covariant positions. Similarly, `-T` would declare `T` to be used only in contravariant positions. For covariant type parameters we get a covariant subtype relationship regarding this type parameter. For our example this means `Stack[T]` is a subtype of `Stack[S]` if `T` is a subtype of `S`. The opposite holds for type parameters that are tagged with a `-`.
+
+For the stack example we would have to use the covariant type parameter `T` in a contravariant position for being able to define method `push`. Since we want covariant subtyping for stacks, we use a trick and abstract over the parameter type of method `push`. We get a polymorphic method in which we use the element type `T` as a lower bound of `push`'s type variable. This has the effect of bringing the variance of `T` in sync with its declaration as a covariant type parameter. Now stacks are covariant, but our solution allows that e.g. it's possible to push a string on an integer stack. The result will be a stack of type `Stack[Any]`; so only if the result is used in a context where we expect an integer stack, we actually detect the error. Otherwise we just get a stack with a more general element type.