preface and lexical syntax chapter converted, other chapters

split into their own files

1 files changed, 177 insertions, 0 deletions

diff --git a/11-top-level-definitions.md b/11-top-level-definitions.md
new file mode 100644
index 0000000000..6d5d17246c
--- /dev/null
+++ b/11-top-level-definitions.md
@@ -0,0 +1,177 @@
+Top-Level Definitions
+=====================
+
+\section{Compilation Units}
+
+\syntax\begin{lstlisting}
+  CompilationUnit  ::=  {`package' QualId semi} TopStatSeq
+  TopStatSeq       ::=  TopStat {semi TopStat}
+  TopStat          ::=  {Annotation} {Modifier} TmplDef
+                     |  Import
+                     |  Packaging
+                     |  PackageObject
+                     |
+  QualId           ::=  id {`.' id}
+\end{lstlisting}
+
+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 
+\begin{lstlisting}
+package $p_1$;
+$\ldots$
+package $p_n$;
+$\stats$
+\end{lstlisting}
+starting with one or more package
+clauses is equivalent to a compilation unit consisting of the
+packaging 
+\begin{lstlisting}
+package $p_1$ { $\ldots$
+  package $p_n$ {
+    $\stats$
+  } $\ldots$
+}
+\end{lstlisting}
+
+Implicitly imported into every compilation unit are, in that order :
+the package \code{java.lang}, the package \code{scala}, and the object
+\code{scala.Predef} (\sref{cls:predef}). Members of a later import in
+that order hide members of an earlier import.
+
+\section{Packagings}\label{sec:packagings}
+
+\syntax\begin{lstlisting}
+  Packaging       ::=  `package' QualId [nl] `{' TopStatSeq `}'
+\end{lstlisting}
+
+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 ~\lstinline@package $p$ { $\ds$ }@~ injects all
+definitions in $\ds$ as members into the package whose qualified name
+is $p$. Members of a package are called {\em top-level} definitions.
+If a definition in $\ds$ is labeled \code{private}, it is
+visible only for other members in the package.
+
+Inside the packaging, all members of package $p$ are visible under their
+simple names. However this rule does not extend to members of enclosing
+packages of $p$ that are designated by a prefix of the path $p$.
+
+\example Given the packaging
+\begin{lstlisting}
+package org.net.prj {
+  ...
+}
+\end{lstlisting}
+all members of package \lstinline@org.net.prj@ are visible under their
+simple names, but members of packages \code{org} or \code{org.net} require
+explicit qualification or imports.
+
+Selections $p$.$m$ from $p$ as well as imports from $p$
+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.
+
+\section{Package Objects}
+\label{sec:pkg-obj}
+
+\syntax\begin{lstlisting}
+  PackageObject   ::=  `package' `object' ObjectDef
+\end{lstlisting}
+
+A package object ~\lstinline@package object $p$ extends $t$@~ adds the
+members of template $t$ to the package $p$. There can be only one
+package object per package. The standard naming convention is to place
+the definition above in a file named \lstinline@package.scala@ that's
+located in the directory corresponding to package $p$.
+
+The package object should not define a member with the same name as
+one of the top-level objects or classes defined in package $p$. 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.
+
+\section{Package References}
+
+\syntax\begin{lstlisting}
+  QualId           ::=  id {`.' id}
+\end{lstlisting}
+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 $p$ will be looked up in the
+closest enclosing scope that defines a member named $p$.
+
+The special predefined name \lstinline@_root_@  refers to the
+outermost root package which contains all top-level packages.  
+
+\example\label{ex:package-ids}
+Consider the following program:
+\begin{lstlisting}
+package b {
+  class B 
+}
+
+package a.b {
+  class A {
+    val x = new _root_.b.B
+  }
+}
+\end{lstlisting}  
+Here, the reference \code{_root_.b.B} refers to class \code{B} in the
+toplevel package \code{b}. If the \code{_root_} prefix had been
+omitted, the name \code{b} would instead resolve to the package
+\code{a.b}, and, provided that package does not also
+contain a class \code{B}, a compiler-time error would result.
+
+\section{Programs}
+
+A {\em program} is a top-level object that has a member method
+\code{main} of type ~\lstinline@(Array[String])Unit@. Programs can be
+executed from a command shell. The program's command arguments are are
+passed to the \code{main} method as a parameter of type
+\code{Array[String]}.
+
+The \code{main} method of a program can be directly defined in the
+object, or it can be inherited. The scala library defines a class
+\code{scala.Application} that defines an empty inherited \code{main} method.
+An objects $m$ inheriting from this class is thus a program, 
+which executes the initializaton code of the object $m$.
+
+\example The following example will create a hello world program by defining
+a method \code{main} in module \code{test.HelloWorld}.
+\begin{lstlisting}
+package test
+object HelloWord {
+  def main(args: Array[String]) { println("hello world") }
+}
+\end{lstlisting}
+
+This program can be started by the command
+\begin{lstlisting}
+scala test.HelloWorld
+\end{lstlisting}
+In a Java environment, the command
+\begin{lstlisting}
+java test.HelloWorld
+\end{lstlisting}
+would work as well. 
+
+\code{HelloWorld} can also be defined without a \code{main} method 
+by inheriting from \code{Application} instead:
+\begin{lstlisting}
+package test 
+object HelloWord extends Application {
+  println("hello world")
+}
+\end{lstlisting}
+