Finished type safe section of tour

Author: jsuereth

tour/explicitly-typed-self-references.md

@@ -0,0 +1,93 @@
+---
+layout: overview
+title: Explicitly Typed Self References
+---
+
+When developing extensible software it is sometimes handy to declare the type of the value `this` explicitly. To motivate this, we will derive a small extensible representation of a graph data structure in Scala.
+
+Here is a definition describing graphs:
+
+    abstract class Graph {
+      type Edge
+      type Node <: NodeIntf
+      abstract class NodeIntf {
+        def connectWith(node: Node): Edge
+      }
+      def nodes: List[Node]
+      def edges: List[Edge]
+      def addNode: Node
+    }
+
+Graphs consist of a list of nodes and edges where both the node and the edge type are left abstract. The use of [abstract types](abstract-types.html) allows implementations of trait Graph to provide their own concrete classes for nodes and edges. Furthermore, there is a method `addNode` for adding new nodes to a graph. Nodes are connected using `methodconnectWith`.
+
+A possible implementation of class `Graph` is given in the next program:
+
+    abstract class DirectedGraph extends Graph {
+      type Edge <: EdgeImpl
+      class EdgeImpl(origin: Node, dest: Node) {
+        def from = origin
+        def to = dest
+      }
+      class NodeImpl extends NodeIntf {
+        def connectWith(node: Node): Edge = {
+          val edge = newEdge(this, node)
+          edges = edge :: edges
+          edge
+        }
+      }
+      protected def newNode: Node
+      protected def newEdge(from: Node, to: Node): Edge
+      var nodes: List[Node] = Nil
+      var edges: List[Edge] = Nil
+      def addNode: Node = {
+        val node = newNode
+        nodes = node :: nodes
+        node
+      }
+    }
+
+Class `DirectedGraph` specializes the `Graph` class by providing a partial implementation. The implementation is only partial, because we would like to be able to extend `DirectedGraph` further. Therefore this class leaves all implementation details open and thus both the edge and the node type are left abstract. Nevertheless, class `DirectedGraph` reveals some additional details about the implementation of the edge type by tightening the bound to class `EdgeImpl`. Furthermore, we have some preliminary implementations of edges and nodes represented by the classes `EdgeImpl` and `NodeImpl`. Since it is necessary to create new node and edge objects within our partial graph implementation, we also have to add the factory methods `newNode` and `newEdge`. The methods `addNode` and `connectWith` are both defined in terms of these factory methods. A closer look at the implementation of method `connectWith` reveals that for creating an edge, we have to pass the self reference `this` to the factory method `newEdge`. But this is assigned the type `NodeImpl`, so it's not compatible with type `Node` which is required by the corresponding factory method. As a consequence, the program above is not well-formed and the Scala compiler will issue an error message.
+
+In Scala it is possible to tie a class to another type (which will be implemented in future) by giving self reference thisthe other type explicitly. We can use this mechanism for fixing our code above. The explicit self type is specified within the body of the class `DirectedGraph`.
+
+Here is the fixed program:
+
+    abstract class DirectedGraph extends Graph {
+      ...
+      class NodeImpl extends NodeIntf {
+        self: Node =>
+        def connectWith(node: Node): Edge = {
+          val edge = newEdge(this, node)  // now legal
+          edges = edge :: edges
+          edge
+        }
+      }
+      ...
+    }
+
+In this new definition of class `NodeImpl`, `this` has type `Node`. Since type `Node` is abstract and we therefore don't know yet if `NodeImpl` is really a subtype of `Node`, the type system of Scala will not allow us to instantiate this class. But nevertheless, we state with the explicit type annotation of this that at some point, (a subclass of) `NodeImpl` has to denote a subtype of type `Node` in order to be instantiatable.
+
+Here is a concrete specialization of `DirectedGraph` where all abstract class members are turned into concrete ones:
+
+    class ConcreteDirectedGraph extends DirectedGraph {
+      type Edge = EdgeImpl
+      type Node = NodeImpl
+      protected def newNode: Node = new NodeImpl
+      protected def newEdge(f: Node, t: Node): Edge =
+        new EdgeImpl(f, t)
+    }
+
+Please note that in this class, we can instantiate `NodeImpl` because now we know that `NodeImpl` denotes a subtype of type `Node` (which is simply an alias for `NodeImpl`).
+
+Here is a usage example of class `ConcreteDirectedGraph`:
+
+    object GraphTest extends Application {
+      val g: Graph = new ConcreteDirectedGraph
+      val n1 = g.addNode
+      val n2 = g.addNode
+      val n3 = g.addNode
+      n1.connectWith(n2)
+      n2.connectWith(n3)
+      n1.connectWith(n3)
+    }
+

tour/implicit-parameters.md

@@ -0,0 +1,41 @@
+---
+layout: overview
+title: Implicit Parameters
+---
+
+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 fall into two categories:
+* First, eligible are all identifiers x that can be accessed at the point of the method call without a prefix and that denote an implicit definition or an implicit parameter.
+* Second, eligible are also all members of companion modules of the implicit parameter's type that are labeled implicit.
+
+In the following example we define a method `sum` which computes the sum of a list of elements using the monoid's add and unit operations. Please note that implicit values can not be top-level, they have to be members of a template.
+ 
+    abstract class SemiGroup[A] {
+      def add(x: A, y: A): A
+    }
+    abstract class Monoid[A] extends SemiGroup[A] {
+      def unit: A
+    }
+    object ImplicitTest extends Application {
+      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
+      }
+      def sum[A](xs: List[A])(implicit m: Monoid[A]): A =
+        if (xs.isEmpty) m.unit
+        else m.add(xs.head, sum(xs.tail))
+
+      println(sum(List(1, 2, 3)))
+      println(sum(List("a", "b", "c")))
+    }
+  
+ 
+Here is the output of the Scala program:
+
+    6
+    abc

tour/index.md

@@ -20,11 +20,11 @@ Scala is equipped with an expressive type system that enforces statically that a
 * [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
+* [explicitly typed self references](explicitly-typed-self-references.html)
+* [views](views.html)
 * [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.
+A [local type inference mechanism](local-type-inference.html) 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.
 
 ## Scala is extensible ##
 

tour/local-type-inference.md

@@ -0,0 +1,45 @@
+---
+layout: overview
+title: Local Type Inference
+---
+Scala has a built-in type inference mechanism which allows the programmer to omit certain type annotations. It is, for instance, often not necessary in Scala to specify the type of a variable, since the compiler can deduce the type from the initialization expression of the variable. Also return types of methods can often be omitted since they corresponds to the type of the body, which gets inferred by the compiler.
+
+Here is an example:
+
+    object InferenceTest1 extends Application {
+      val x = 1 + 2 * 3         // the type of x is Int
+      val y = x.toString()      // the type of y is String
+      def succ(x: Int) = x + 1  // method succ returns Int values
+    }
+
+For recursive methods, the compiler is not able to infer a result type. Here is a program which will fail the compiler for this reason:
+
+    object InferenceTest2 {
+      def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1)
+    }
+
+It is also not compulsory to specify type parameters when [polymorphic methods](polymorphic-methods.html) are called or [generic classes](generic-classes.html) are instantiated. The Scala compiler will infer such missing type parameters from the context and from the types of the actual method/constructor parameters.
+
+Here is an example which illustrates this:
+
+    case class MyPair[A, B](x: A, y: B);
+    object InferenceTest3 extends Application {
+      def id[T](x: T) = x
+      val p = new MyPair(1, "scala") // type: MyPair[Int, String]
+      val q = id(1)                  // type: Int
+    }
+
+The last two lines of this program are equivalent to the following code where all inferred types are made explicit:
+
+    val x: MyPair[Int, String] = new MyPair[Int, String](1, "scala")
+    val y: Int = id[Int](1)
+
+In some situations it can be quite dangerous to rely on Scala's type inference mechanism as the following program shows:
+
+    object InferenceTest4 {
+      var obj = null
+      obj = new Object()
+    }
+
+This program does not compile because the type inferred for variable `obj` is `Null`. Since the only value of that type is `null`, it is impossible to make this variable refer to another value.
+

tour/views.md

@@ -0,0 +1,45 @@
+---
+layout: overview
+title: Views
+---
+
+[Implicit parameters](implicit-parameters.html) and methods can also define implicit conversions called _views_. A view from type `S` to type `T` is defined by an implicit value which has function type `S => T`, or by a method convertible to a value of that type.
+
+Views are applied in two situations:
+* If an expression `e` is of type `T`, and `T` does not conform to the expression's expected type `pt`.
+* In a selection `e.m` with `e` of type `T`, if the selector `m` does not denote a member of `T`.
+
+In the first case, a view `v` is searched which is applicable to `e` and whose result type conforms to `pt`. In the second case, a view `v` is searched which is applicable to `e` and whose result contains a member named `m`.
+
+The following operation on the two lists xs and ys of type `List[Int]` is legal:
+
+    xs <= ys
+
+assuming the implicit methods `list2ordered` and `int2ordered` defined below are in scope:
+
+    implicit def list2ordered[A](x: List[A])
+        (implicit elem2ordered: a => Ordered[A]): Ordered[List[A]] =
+      new Ordered[List[A]] { /* .. */ }
+    
+    implicit def int2ordered(x: Int): Ordered[Int] = 
+      new Ordered[Int] { /* .. */ }
+  
+The `list2ordered` function can also be expressed with the use of a _view bound_ for a type parameter:
+
+    implicit def list2ordered[A <% Ordered[A]](x: List[A]): Ordered[List[A]] = ...
+  
+The Scala compiler then generates code equivalent to the definition of `list2ordered` given above.
+
+The implicitly imported object `scala.Predef` declares several predefined types (e.g. `Pair`) and methods (e.g. `error`) but also several views. The following example gives an idea of the predefined view `charWrapper`:
+
+    final class RichChar(c: Char) {
+      def isDigit: Boolean = Character.isDigit(c)
+      // isLetter, isWhitespace, etc.
+    }
+    object RichCharTest {
+      implicit def charWrapper(c: char) = new RichChar(c)
+      def main(args: Array[String]) {
+        println('0'.isDigit)
+      }
+    }
+