summaryrefslogtreecommitdiff
path: root/spec/09-top-level-definitions.md
diff options
context:
space:
mode:
authorAdriaan Moors <adriaan.moors@typesafe.com>2014-03-28 16:45:45 -0700
committerAdriaan Moors <adriaan.moors@typesafe.com>2014-03-28 17:40:57 -0700
commit0b48dc203e0e789646841880f49cd8ae08f6412d (patch)
treefd0bed2defecbe4d3d79cb8154d2343095fc2add /spec/09-top-level-definitions.md
parent0f1dcc41cb445eac182c8101a3e0c95594b0f95e (diff)
downloadscala-0b48dc203e0e789646841880f49cd8ae08f6412d.tar.gz
scala-0b48dc203e0e789646841880f49cd8ae08f6412d.tar.bz2
scala-0b48dc203e0e789646841880f49cd8ae08f6412d.zip
Number files like chapters. Consolidate toc & preface.
Aside from the consolidation of title & preface in index.md, this commit was produced as follows: ``` cd spec/ g mv 03-lexical-syntax.md 01-lexical-syntax.md g mv 04-identifiers-names-and-scopes.md 02-identifiers-names-and-scopes.md g mv 05-types.md 03-types.md g mv 06-basic-declarations-and-definitions.md 04-basic-declarations-and-definitions.md g mv 07-classes-and-objects.md 05-classes-and-objects.md g mv 08-expressions.md 06-expressions.md g mv 09-implicit-parameters-and-views.md 07-implicit-parameters-and-views.md g mv 10-pattern-matching.md 08-pattern-matching.md g mv 11-top-level-definitions.md 09-top-level-definitions.md g mv 12-xml-expressions-and-patterns.md 10-xml-expressions-and-patterns.md g mv 13-user-defined-annotations.md 11-user-defined-annotations.md g mv 14-the-scala-standard-library.md 12-the-scala-standard-library.md g mv 15-syntax-summary.md 13-syntax-summary.md g mv 16-references.md 14-references.md perl -pi -e 's/03-lexical-syntax/01-lexical-syntax/g' *.md perl -pi -e 's/04-identifiers-names-and-scopes/02-identifiers-names-and-scopes/g' *.md perl -pi -e 's/05-types/03-types/g' *.md perl -pi -e 's/06-basic-declarations-and-definitions/04-basic-declarations-and-definitions/g' *.md perl -pi -e 's/07-classes-and-objects/05-classes-and-objects/g' *.md perl -pi -e 's/08-expressions/06-expressions/g' *.md perl -pi -e 's/09-implicit-parameters-and-views/07-implicit-parameters-and-views/g' *.md perl -pi -e 's/10-pattern-matching/08-pattern-matching/g' *.md perl -pi -e 's/11-top-level-definitions/09-top-level-definitions/g' *.md perl -pi -e 's/12-xml-expressions-and-patterns/10-xml-expressions-and-patterns/g' *.md perl -pi -e 's/13-user-defined-annotations/11-user-defined-annotations/g' *.md perl -pi -e 's/14-the-scala-standard-library/12-the-scala-standard-library/g' *.md perl -pi -e 's/15-syntax-summary/13-syntax-summary/g' *.md perl -pi -e 's/16-references/14-references/g' *.md ```
Diffstat (limited to 'spec/09-top-level-definitions.md')
-rw-r--r--spec/09-top-level-definitions.md201
1 files changed, 201 insertions, 0 deletions
diff --git a/spec/09-top-level-definitions.md b/spec/09-top-level-definitions.md
new file mode 100644
index 0000000000..b9c78b23a1
--- /dev/null
+++ b/spec/09-top-level-definitions.md
@@ -0,0 +1,201 @@
+---
+title: Top-Level Definitions
+layout: default
+chapter: 9
+---
+
+# Top-Level Definitions
+
+## Compilation Units
+
+```ebnf
+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
+
+```scala
+package $p_1$;
+$\ldots$
+package $p_n$;
+$\mathit{stats}$
+```
+
+starting with one or more package
+clauses is equivalent to a compilation unit consisting of the
+packaging
+
+```scala
+package $p_1$ { $\ldots$
+ package $p_n$ {
+ $\mathit{stats}$
+ } $\ldots$
+}
+```
+
+Every compilation unit implicitly imports the following packages, in the given order:
+ 1. the package `java.lang`,
+ 2. the package `scala`, and
+ 3. the object [`scala.Predef`](12-the-scala-standard-library.html#the-predef-object), unless there is an explicit top-level import that references `scala.Predef`.
+
+Members of a later import in that order hide members of an earlier import.
+
+The exception to the implicit import of `scala.Predef` can be useful to hide, e.g., predefined implicit conversions.
+
+## Packagings
+
+```ebnf
+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 `package $p$ { $\mathit{ds}$ }` 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`, 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$.
+
+```scala
+package org.net.prj {
+ ...
+}
+```
+
+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$
+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.
+
+
+## Package Objects
+
+```ebnf
+PackageObject ::= ‘package’ ‘object’ ObjectDef
+```
+
+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 `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.
+
+
+## Package References
+
+```ebnf
+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 `_root_` refers to the
+outermost root package which contains all top-level packages.
+
+###### Example
+Consider the following program:
+
+```scala
+package b {
+ class B
+}
+
+package a.b {
+ class A {
+ val x = new _root_.b.B
+ }
+}
+```
+
+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.
+
+
+## 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 `main` method as a parameter of type
+`Array[String]`.
+
+The `main` method of a program can be directly defined in the
+object, or it can be inherited. The scala library defines a special class
+`scala.App` whose body acts as a `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 `main` in module `test.HelloWorld`.
+
+```scala
+package test
+object HelloWorld {
+ def main(args: Array[String]) { println("Hello World") }
+}
+```
+
+This program can be started by the command
+
+```scala
+scala test.HelloWorld
+```
+
+In a Java environment, the command
+
+```scala
+java test.HelloWorld
+```
+
+would work as well.
+
+`HelloWorld` can also be defined without a `main` method
+by inheriting from `App` instead:
+
+```scala
+package test
+object HelloWorld extends App {
+ println("Hello World")
+}
+```
+