From 4659685b8f5591cb539e3e52cc98672e9fc89e02 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Mon, 2 Mar 2009 16:17:29 -0800 Subject: [PATCH] Packages. DELTA=170 (73 added, 21 deleted, 76 changed) OCL=25556 CL=25594 --- doc/go_spec.html | 188 ++++++++++++++++++++++++++++++----------------- 1 file changed, 120 insertions(+), 68 deletions(-) diff --git a/doc/go_spec.html b/doc/go_spec.html index d49df958c15..3104cc6f241 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1101,9 +1101,9 @@ to receive. This constraint is called a channel's direction; either 

-chan T         // can send and receive values of type T
+chan T         // can be used to send and receive values of type T
 chan <- float  // can only be used to send floats
-<-chan int     // can only receive ints
+<-chan int     // can only be used to receive ints

@@ -3065,27 +3065,6 @@ if x := f(); x < y { - -

Switch statements

@@ -3757,81 +3736,154 @@ m := make(map[string] int, 100); # map with initial space for 100 elements

Packages

-A package is a package clause, optionally followed by import declarations, -followed by a series of declarations. +

+Go programs are constructed by linking together packages. +A package is in turn constructed from one or more source files that +together provide an interface to a set of types, constants, functions, +and variables. Those elements may be imported and used in +another package. +

+ +

Source file organization

+ +

+Each source file consists of a package clause defining the package +to which it belongs, followed by a possibly empty set of import +declarations that declare packages whose contents it wishes to use, +followed by a possibly empty set of declarations of functions, +types, variables, and constants. The source text following the +package clause acts as a block for scoping ($Declarations and scope +rules). +

-Package = PackageClause { ImportDecl [ ";" ] } { Declaration [ ";" ] } .
+SourceFile       = PackageClause { ImportDecl [ ";" ] } { Declaration [ ";" ] } .
-The source text following the package clause acts like a block for scoping -purposes ($Declarations and scope rules). +

Package clause

+

-Every source file identifies the package to which it belongs. -The file must begin with a package clause. +A package clause begins each source file and defines the package +to which the file belongs. +

-PackageClause = "package" PackageName .
-
-package Math
+PackageClause    = "package" PackageName .
+
+package math
+
-A package can gain access to exported identifiers from another package -through an import declaration: +

+A set of files sharing the same PackageName form the implementation of a package. +An implementation may require that all source files for a package inhabit the same directory. +

+ +

Import

+ +

+A source file gains access to exported identifiers (§Exported +identifiers) from another package through an import declaration. +In the general form, an import declaration provides an identifier +that code in the source file may use to access the imported package's +contents and a file name referring to the (compiled) implementation of +the package. The file name may be relative to a repository of +installed packages. +

-ImportDecl = "import" ( ImportSpec | "(" [ ImportSpecList ] ")" ) .
-ImportSpecList = ImportSpec { ";" ImportSpec } [ ";" ] .
-ImportSpec = [ "." | PackageName ] PackageFileName .
-PackageFileName = StringLit .
+ImportDecl       = "import" ( ImportSpec | "(" [ ImportSpecList ] ")" ) .
+ImportSpecList   = ImportSpec { ";" ImportSpec } [ ";" ] .
+ImportSpec       = [ "." | PackageName ] PackageFileName .
+PackageFileName  = StringLit .
-An import statement makes the exported package-level identifiers of the named -package file accessible to this package.

-In the following discussion, assume we have a package in the -file "/lib/math", called package "math", which exports the identifiers -"Sin" and "Cos" denoting the respective trigonometric functions. +After an import, in the usual case an exported name N from the imported +package P may be accessed by the qualified identifier +P.N (§Qualified identifiers). The actual +name P depends on the form of the import declaration. If +an explicit package name p1 is provided, the qualified +identifer will have the form p1.N. If no name +is provided in the import declaration, P will be the package +name declared within the source files of the imported package. +Finally, if the import declaration uses an explicit period +(.) for the package name, N will appear +in the package-level scope of the current file and the qualified name is +unnecessary and erroneous. In this form, it is an error if the import introduces +a name conflict. +

-In the general form, with an explicit package name, the import -statement declares that package name as an identifier whose -contents are the exported elements of the imported package. -For instance, after +In this table, assume we have compiled a package named +math, which exports function Sin, and +installed the compiled package in file +"lib/math". +

+
+Import syntax               Local name of Sin
+
+import M "lib/math"         M.Sin
+import   "lib/math"         math.Sin
+import . "lib/math"         Sin
+
+ +

Multi-file packages

+ +

+If a package is constructed from multiple source files, all names +at package-level scope, not just exported names, are visible to all the +files in the package. An import declaration is still necessary to +declare intention to use the names, +but the imported names do not need a qualified identifer to be +accessed. +

+ +

+The compilation of a multi-file package may require +that the files be compiled and installed in an order that satisfies +the resolution of names imported within the package. +

+ +

+If source file math1.go contains +

-import M "/lib/math"
+package math
+
+const twoPi = 6.283185307179586
+
+function Sin(x float) float { return ... }
-the contents of the package /lib/math can be accessed by -"M.Sin", "M.Cos", etc.

-In its simplest form, with no package name, the import statement -implicitly uses the imported package name itself as the local -package name. After - +and file "math2.go" begins +

-import "/lib/math"
+package math
+
+import "lib/math"
-the contents are accessible by "math.Sin", "math.Cos".

-Finally, if instead of a package name the import statement uses -an explicit period, the contents of the imported package are added -to the current package. After +then, provided "math1.go" is compiled first and +installed in "lib/math", math2.go +may refer directly to Sin and twoPi +without a qualified identifier. +

-
-import . "/lib/math"
-
+

An example package

-the contents are accessible by "Sin" and "Cos". In this instance, it is -an error if the import introduces name conflicts.

-Here is a complete example Go package that implements a concurrent prime sieve: +Here is a complete Go package that implements a concurrent prime sieve. +

 package main
 
+import "fmt"
+
 // Send the sequence 2, 3, 4, ... to channel 'ch'.
 func generate(ch chan <- int) {
 	for i := 2; ; i++ {
@@ -3856,7 +3908,7 @@ func sieve() {
 	go generate(ch);  // Start generate() as a subprocess.
 	for {
 		prime := <-ch;
-		print(prime, "\n");
+		fmt.Print(prime, "\n");
 		ch1 := make(chan int);
 		go filter(ch, ch1, prime);
 		ch = ch1
@@ -3972,7 +4024,7 @@ Program execution begins by initializing the main package and then
 invoking main.main().
 

 

-When main.main() returns, the program exits.
+When main.main() returns, the program exits.