From 0b48dc203e0e789646841880f49cd8ae08f6412d Mon Sep 17 00:00:00 2001 From: Adriaan Moors Date: Fri, 28 Mar 2014 16:45:45 -0700 Subject: 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 ``` --- spec/09-top-level-definitions.md | 201 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 spec/09-top-level-definitions.md (limited to 'spec/09-top-level-definitions.md') 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") +} +``` + -- cgit v1.2.3