diff options
author | Iain McGinniss <iainmcgin@gmail.com> | 2012-12-20 17:06:33 +0000 |
---|---|---|
committer | Iain McGinniss <iainmcgin@gmail.com> | 2012-12-20 17:06:33 +0000 |
commit | 7066c700d831dd447a4023750a61f3ac1934547d (patch) | |
tree | e87cecb85f47cf859526ea8647f65d143e820ba2 /11-top-level-definitions.md | |
parent | dc958b2bdc81621f14cbf29bfa3081283a5f8830 (diff) | |
download | scala-7066c700d831dd447a4023750a61f3ac1934547d.tar.gz scala-7066c700d831dd447a4023750a61f3ac1934547d.tar.bz2 scala-7066c700d831dd447a4023750a61f3ac1934547d.zip |
converted xml expressions and user defined annotations chapters
Diffstat (limited to '11-top-level-definitions.md')
-rw-r--r-- | 11-top-level-definitions.md | 210 |
1 files changed, 114 insertions, 96 deletions
diff --git a/11-top-level-definitions.md b/11-top-level-definitions.md index 6d5d17246c..02c7db7bb9 100644 --- a/11-top-level-definitions.md +++ b/11-top-level-definitions.md @@ -1,75 +1,81 @@ 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} +Compilation Units +----------------- + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.grammar} +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 -\begin{lstlisting} + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala} package $p_1$; $\ldots$ package $p_n$; -$\stats$ -\end{lstlisting} +$\mathit{stats}$ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + starting with one or more package clauses is equivalent to a compilation unit consisting of the packaging -\begin{lstlisting} + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala} package $p_1$ { $\ldots$ package $p_n$ { - $\stats$ + $\mathit{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 +the package `java.lang`, the package `scala`, and the object +[`scala.Predef`](#the-predef-object). 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} +Packagings +---------- + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.grammar} +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 ~\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 +A packaging `package $p$ { $\mathit{ds}$ }`{.scala} injects all +definitions in $\mathit{ds}$ as members into the package whose qualified name +is $p$. Members of a package are called _top-level_ definitions. +If a definition in $\mathit{ds}$ is labeled `private`{.scala}, 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} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala} 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +all members of package `org.net.prj` are visible under their +simple names, but members of packages `org` or `org.net` require explicit qualification or imports. Selections $p$.$m$ from $p$ as well as imports from $p$ @@ -82,17 +88,18 @@ 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} +Package Objects +--------------- + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.grammar} +PackageObject ::= ‘package’ ‘object’ ObjectDef +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A package object ~\lstinline@package object $p$ extends $t$@~ adds the +A package object `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 +the definition above in a file named `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 @@ -101,77 +108,88 @@ 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} +Package References +------------------ + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.grammar} +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 $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 +The special predefined name `_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-ids) Consider the following program: -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. + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala} + package b { + class B + } + + package a.b { + class A { + val x = new _root_.b.B + } + } + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -\section{Programs} + 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. -A {\em program} is a top-level object that has a member method -\code{main} of type ~\lstinline@(Array[String])Unit@. Programs can be + +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 \code{main} method as a parameter of type -\code{Array[String]}. +passed to the `main` method as a parameter of type +`Array[String]`. -The \code{main} method of a program can be directly defined in the +The `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. +`scala.Application` that defines an empty inherited `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} +(@) The following example will create a hello world program by defining + a method `main` in module `test.HelloWorld`. + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala} + 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: + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala} + package test + object HelloWord extends Application { + println("hello world") + } + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |