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}
