From 250767174b355e51e79a34f2314dbe73e03c0234 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Thu, 6 Mar 2008 19:40:52 -0800 Subject: [PATCH] add HTML formatting; use /home/sanjay/bin/makehtml --mode=document go_lang.txt to generate the html output. SVN=111681 --- doc/go_lang.txt | 477 +++++++++++++++++++++++++++--------------------- 1 file changed, 273 insertions(+), 204 deletions(-) diff --git a/doc/go_lang.txt b/doc/go_lang.txt index f722346e583..3002d0cda20 100644 --- a/doc/go_lang.txt +++ b/doc/go_lang.txt @@ -1,4 +1,5 @@ The Go Programming Language +---- (March 7, 2008) This document is an informal specification/proposal for a new systems programming @@ -6,6 +7,7 @@ language. Guiding principles +---- Go is a new systems programming language intended as an alternative to C++ at Google. Its main purpose is to provide a productive and efficient programming @@ -28,11 +30,12 @@ written in itself. Modularity, identifiers and scopes +---- A Go program consists of one or more `packages' compiled separately, though not independently. A single package may make individual identifiers visible to other files by marking them as -exported; there is no "header file". +exported; there is no ``header file''. A package collects types, constants, functions, and so on into a named entity that may be exported to enable its constituents be used in @@ -45,6 +48,7 @@ Scoping is essentially the same as in C. Program structure +---- A compilation unit (usually a single source file) consists of a package specifier followed by import @@ -63,6 +67,7 @@ still under development. Typing, polymorphism, and object-orientation +---- Go programs are strongly typed. Certain expressions, in particular map and channel accesses, can also be polymorphic. The language provides @@ -80,7 +85,7 @@ An interface is implemented by associating methods with structures. If a structure implements all methods of an interface, it implements that interface and thus can be used where that interface is required. Unless used through a variable of interface type, methods -can always be statically bound (they are not "virtual"), and incur no +can always be statically bound (they are not ``virtual''), and incur no runtime overhead compared to an ordinary function. Go has no explicit notion of classes, sub-classes, or inheritance. @@ -93,6 +98,7 @@ use of abstract data types operating on interface types. Pointers and garbage collection +---- Variables may be allocated automatically (when entering the scope of the variable) or explicitly on the heap. Pointers are used to refer @@ -103,6 +109,7 @@ they are no longer accessible. There is no pointer arithmetic in Go. Functions +---- Functions contain declarations and statements. They may be recursive. Functions may be anonymous and appear as @@ -110,6 +117,7 @@ literals in expressions. Multithreading and channels +---- Go supports multithreaded programming directly. A function may be invoked as a parallel thread of execution. Communication and @@ -118,6 +126,7 @@ language support. Values and references +---- All objects have value semantics, but its contents may be accessed through different pointers referring to the same object. @@ -131,6 +140,7 @@ byte strings. Syntax +---- The syntax of statements and expressions in Go borrows from the C tradition; declarations are loosely derived from the Pascal tradition to allow more @@ -138,56 +148,56 @@ comprehensible composability of types. Here is a complete example Go program that implements a concurrent prime sieve: -============================ -package Main -// Send the sequence 2, 3, 4, ... to channel 'ch'. -func Generate(ch *chan> int) { - for i := 2; ; i++ { - >ch = i; // Send 'i' to channel 'ch'. - } -} - -// Copy the values from channel 'in' to channel 'out', -// removing those divisible by 'prime'. -func Filter(in *chan< int, out *chan> int, prime int) { - for ; ; { - i := out = i; // Send 'i' to channel 'out'. + package Main + + // Send the sequence 2, 3, 4, ... to channel 'ch'. + func Generate(ch *chan> int) { + for i := 2; ; i++ { + >ch = i; // Send 'i' to channel 'ch'. } } -} - -// The prime sieve: Daisy-chain Filter processes together. -func Sieve() { - ch := new(chan int); // Create a new channel. - go Generate(ch); // Start Generate() as a subprocess. - for ; ; { - prime := int, prime int) { + for ; ; { + i := out = i; // Send 'i' to channel 'out'. + } + } + } + + // The prime sieve: Daisy-chain Filter processes together. + func Sieve() { + ch := new(chan int); // Create a new channel. + go Generate(ch); // Start Generate() as a subprocess. + for ; ; { + prime := ' ] ValueType . + ChannelType = 'chan' [ '<' | '>' ] ValueType . chan any // a generic channel chan int // a channel that can exchange only ints @@ -639,6 +673,7 @@ There are no channel literals. Function types +---- A function type denotes the set of all functions with the same signature. @@ -646,13 +681,13 @@ A method is a function with a receiver, which is of type pointer to struct. Functions can return multiple values simultaneously. -FunctionType = 'func' AnonymousSignature . -AnonymousSignature = [ Receiver '.' ] Parameters [ Result ] . -Receiver = '(' identifier Type ')' . -Parameters = '(' [ ParameterList ] ')' . -ParameterList = ParameterSection { ',' ParameterSection } . -ParameterSection = [ IdentifierList ] Type . -Result = [ Type ] | '(' ParameterList ')' . + FunctionType = 'func' AnonymousSignature . + AnonymousSignature = [ Receiver '.' ] Parameters [ Result ] . + Receiver = '(' identifier Type ')' . + Parameters = '(' [ ParameterList ] ')' . + ParameterList = ParameterSection { ',' ParameterSection } . + ParameterSection = [ IdentifierList ] Type . + Result = [ Type ] | '(' ParameterList ')' . // Function types func () @@ -673,11 +708,12 @@ pointer. Function Literals +---- Function literals represent anonymous functions. -FunctionLit = FunctionType Block . -Block = '{' [ StatementList ] '}' . + FunctionLit = FunctionType Block . + Block = '{' [ StatementList ] '}' . A function literal can be invoked or assigned to a variable of the corresponding function pointer type. @@ -692,6 +728,7 @@ variables, and variables declared within the function literal. Methods +---- A method is a function bound to a particular struct type T. When defined, a method indicates the type of the struct by declaring a receiver of type @@ -721,17 +758,19 @@ For instance, given a Point variable pt, one may call Interface of a struct +---- The interface of a struct is defined to be the unordered set of methods associated with that struct. Interface types +---- An interface type denotes a set of methods. -InterfaceType = 'interface' '{' { MethodDecl } '}' . -MethodDecl = identifier Parameters [ Result ] ';' . + InterfaceType = 'interface' '{' { MethodDecl } '}' . + MethodDecl = identifier Parameters [ Result ] ';' . // A basic file interface. type File interface { @@ -774,27 +813,30 @@ There are no interface literals. Literals +---- -Literal = BasicLit | CompoundLit . -BasicLit = CharLit | StringLit | IntLit | FloatLit . -CompoundLit = ArrayLit | MapLit | StructLit | FunctionLit . + Literal = BasicLit | CompoundLit . + BasicLit = CharLit | StringLit | IntLit | FloatLit . + CompoundLit = ArrayLit | MapLit | StructLit | FunctionLit . Declarations +---- A declaration associates a name with a language entity such as a type, constant, variable, or function. -Declaration = ConstDecl | TypeDecl | VarDecl | FunctionDecl | ExportDecl . + Declaration = ConstDecl | TypeDecl | VarDecl | FunctionDecl | ExportDecl . Const declarations +---- A constant declaration gives a name to the value of a constant expression. -ConstDecl = 'const' ( ConstSpec | '(' ConstSpecList [ ';' ] ')' ). -ConstSpec = identifier [ Type ] '=' Expression . -ConstSpecList = ConstSpec { ';' ConstSpec }. + ConstDecl = 'const' ( ConstSpec | '(' ConstSpecList [ ';' ] ')' ). + ConstSpec = identifier [ Type ] '=' Expression . + ConstSpecList = ConstSpec { ';' ConstSpec }. const pi float = 3.14159265 const e = 2.718281828 @@ -805,14 +847,15 @@ ConstSpecList = ConstSpec { ';' ConstSpec }. Type declarations +---- A type declaration introduces a name as a shorthand for a type. In certain situations, such as conversions, it may be necessary to use such a type name. -TypeDecl = 'type' ( TypeSpec | '(' TypeSpecList [ ';' ] ')' ). -TypeSpec = identifier Type . -TypeSpecList = TypeSpec { ';' TypeSpec }. + TypeDecl = 'type' ( TypeSpec | '(' TypeSpecList [ ';' ] ')' ). + TypeSpec = identifier Type . + TypeSpecList = TypeSpec { ';' TypeSpec }. type IntArray [16] int @@ -823,14 +866,15 @@ TypeSpecList = TypeSpec { ';' TypeSpec }. Variable declarations +---- A variable declaration creates a variable and gives it a type and a name. It may optionally give the variable an initial value; in some forms of declaration the type of the initial value defines the type of the variable. -VarDecl = 'var' ( VarSpec | '(' VarSpecList [ ';' ] ')' ) | SimpleVarDecl . -VarSpec = IdentifierList ( Type [ '=' ExpressionList ] | '=' ExpressionList ) . -VarSpecList = VarSpec { ';' VarSpec } . + VarDecl = 'var' ( VarSpec | '(' VarSpecList [ ';' ] ')' ) | SimpleVarDecl . + VarSpec = IdentifierList ( Type [ '=' ExpressionList ] | '=' ExpressionList ) . + VarSpecList = VarSpec { ';' VarSpec } . var i int var u, v, w float @@ -848,7 +892,7 @@ The syntax SimpleVarDecl = identifier ':=' Expression . -is syntactic shorthand for +is shorthand for var identifer = Expression. @@ -861,14 +905,15 @@ declare local temporary variables. Function and method declarations +---- Functions and methods have a special declaration syntax, slightly different from the type syntax because an identifier must be present in the signature. For now, functions and methods can only be declared at the global level. -FunctionDecl = 'func' NamedSignature ( ';' | Block ) . -NamedSignature = [ Receiver ] identifier Parameters [ Result ] . + FunctionDecl = 'func' NamedSignature ( ';' | Block ) . + NamedSignature = [ Receiver ] identifier Parameters [ Result ] . func min(x int, y int) int { if x < y { @@ -904,6 +949,7 @@ Functions and methods can be forward declared by omitting the body: Export declarations +---- Global identifiers may be exported, thus making the exported identifer visible outside the package. Another package may @@ -921,8 +967,8 @@ source than the export directive itself, but it is an error to specify an identifier not declared anywhere in the source file containing the export directive. -ExportDecl = 'export' ExportIdentifier { ',' ExportIdentifier } . -ExportIdentifier = QualifiedIdent . + ExportDecl = 'export' ExportIdentifier { ',' ExportIdentifier } . + ExportIdentifier = QualifiedIdent . export sin, cos export Math.abs @@ -931,39 +977,40 @@ ExportIdentifier = QualifiedIdent . Expressions +---- Expression syntax is based on that of C but with fewer precedence levels. -Expression = BinaryExpr | UnaryExpr | PrimaryExpr . -BinaryExpr = Expression binary_op Expression . -UnaryExpr = unary_op Expression . + Expression = BinaryExpr | UnaryExpr | PrimaryExpr . + BinaryExpr = Expression binary_op Expression . + UnaryExpr = unary_op Expression . -PrimaryExpr = - identifier | Literal | '(' Expression ')' | 'iota' | - Call | Conversion | - Expression '[' Expression [ ':' Expression ] ']' | Expression '.' identifier . + PrimaryExpr = + identifier | Literal | '(' Expression ')' | 'iota' | + Call | Conversion | + Expression '[' Expression [ ':' Expression ] ']' | Expression '.' identifier . -Call = Expression '(' [ ExpressionList ] ')' . -Conversion = TypeName '(' [ ExpressionList ] ')' . + Call = Expression '(' [ ExpressionList ] ')' . + Conversion = TypeName '(' [ ExpressionList ] ')' . -binary_op = log_op | rel_op | add_op | mul_op . -log_op = '||' | '&&' . -rel_op = '==' | '!=' | '<' | '<=' | '>' | '>='. -add_op = '+' | '-' | '|' | '^'. -mul_op = '*' | '/' | '%' | '<<' | '>>' | '&'. + binary_op = log_op | rel_op | add_op | mul_op . + log_op = '||' | '&&' . + rel_op = '==' | '!=' | '<' | '<=' | '>' | '>='. + add_op = '+' | '-' | '|' | '^'. + mul_op = '*' | '/' | '%' | '<<' | '>>' | '&'. -unary_op = '+' | '-' | '!' | '^' | '<' | '>' | '*' | '&' . + unary_op = '+' | '-' | '!' | '^' | '<' | '>' | '*' | '&' . Field selection ('.') binds tightest, followed by indexing ('[]') and then calls and conversions. The remaining precedence levels are as follows (in increasing precedence order): -Precedence Operator - 1 || - 2 && - 3 == != < <= > >= - 4 + - | ^ - 5 * / % << >> & - 6 + - ! ^ < > * & (unary) + Precedence Operator + 1 || + 2 && + 3 == != < <= > >= + 4 + - | ^ + 5 * / % << >> & + 6 + - ! ^ < > * & (unary) For integer values, / and % satisfy the following relationship: @@ -1014,6 +1061,7 @@ General expressions The constant generator 'iota' +---- Within a declaration, each appearance of the keyword 'iota' represents a successive element of an integer sequence. It is reset to zero whenever the keyword 'const', 'type' @@ -1037,32 +1085,35 @@ a set of related constants: Statements +---- Statements control execution. -Statement = - Declaration | - SimpleStat | CompoundStat | - GoStat | - ReturnStat | - IfStat | SwitchStat | - ForStat | RangeStat | - BreakStat | ContinueStat | GotoStat | LabelStat . - -SimpleStat = - ExpressionStat | IncDecStat | Assignment | SimpleVarDecl . + Statement = + Declaration | + SimpleStat | CompoundStat | + GoStat | + ReturnStat | + IfStat | SwitchStat | + ForStat | RangeStat | + BreakStat | ContinueStat | GotoStat | LabelStat . + + SimpleStat = + ExpressionStat | IncDecStat | Assignment | SimpleVarDecl . Expression statements +---- -ExpressionStat = Expression . + ExpressionStat = Expression . f(x+y) IncDec statements +---- -IncDecStat = Expression ( '++' | '--' ) . + IncDecStat = Expression ( '++' | '--' ) . a[i]++ @@ -1070,8 +1121,9 @@ Note that ++ and -- are not operators for expressions. Compound statements +---- -CompoundStat = '{' { Statement } '}' . + CompoundStat = '{' { Statement } '}' . { x := 1; @@ -1083,13 +1135,14 @@ from the declaration to the end of the compound statement. Assignments +---- -Assignment = SingleAssignment | TupleAssignment | Send . -SimpleAssignment = Designator assign_op Expression . -TupleAssignment = DesignatorList assign_op ExpressionList . -Send = '>' Expression = Expression . - -assign_op = [ add_op | mul_op ] '=' . + Assignment = SingleAssignment | TupleAssignment | Send . + SimpleAssignment = Designator assign_op Expression . + TupleAssignment = DesignatorList assign_op ExpressionList . + Send = '>' Expression = Expression . + + assign_op = [ add_op | mul_op ] '=' . The designator must be an l-value such as a variable, pointer indirection, or an array indexing. @@ -1141,24 +1194,28 @@ In assignments, the type of the expression must match the type of the designator Go statements +---- A go statement starts the execution of a function as an independent concurrent thread of control within the same address space. Unlike with a function, the next line of the program does not wait for the function to complete. -GoStat = 'go' Call . + GoStat = 'go' Call . + go Server() go func(ch chan> bool) { for ;; { sleep(10); >ch = true; }} (c) Return statements +---- A return statement terminates execution of the containing function and optionally provides a result value or values to the caller. -ReturnStat = 'return' [ ExpressionList ] . + ReturnStat = 'return' [ ExpressionList ] . + There are two ways to return values from a function. The first is to explicitly list the return value or values in the return statement: @@ -1190,12 +1247,13 @@ first form of return statement is used: If statements +---- If statements have the traditional form except that the condition need not be parenthesized and the "then" statement must be in brace brackets. -IfStat = 'if' [ SimpleVarDecl ';' ] Expression Block [ 'else' Statement ] . + IfStat = 'if' [ SimpleVarDecl ';' ] Expression Block [ 'else' Statement ] . if x > 0 { return true; @@ -1215,13 +1273,14 @@ the variable is initialized once before the statement is entered. Switch statements +---- Switches provide multi-way execution. -SwitchStat = 'switch' [ [ SimpleVarDecl ';' ] [ Expression ] ] '{' { CaseClause } '}' . -CaseClause = CaseList { Statement } [ 'fallthrough' ] . -CaseList = Case { Case } . -Case = ( 'case' ExpressionList | 'default' ) ':' . + SwitchStat = 'switch' [ [ SimpleVarDecl ';' ] [ Expression ] ] '{' { CaseClause } '}' . + CaseClause = CaseList { Statement } [ 'fallthrough' ] . + CaseList = Case { Case } . + Case = ( 'case' ExpressionList | 'default' ) ':' . There can be at most one default case in a switch statement. @@ -1268,15 +1327,16 @@ If the expression is omitted, it is equivalent to 'true'. For statements +---- For statements are a combination of the 'for' and 'while' loops of C. -ForStat = 'for' [ Condition | ForClause ] Block . -ForClause = [ InitStat ] ';' [ Condition ] ';' [ PostStat ] . - -InitStat = SimpleStat . -Condition = Expression . -PostStat = SimpleStat . + ForStat = 'for' [ Condition | ForClause ] Block . + ForClause = [ InitStat ] ';' [ Condition ] ';' [ PostStat ] . + + InitStat = SimpleStat . + Condition = Expression . + PostStat = SimpleStat . A SimpleStat is a simple statement such as an assignment, a SimpleVarDecl, or an increment or decrement statement. Therefore one may declare a loop @@ -1301,12 +1361,13 @@ If the condition is absent, it is equivalent to 'true'. Range statements +---- Range statements are a special control structure for iterating over the contents of arrays and maps. -RangeStat = 'range' IdentifierList ':=' RangeExpression Block . -RangeExpression = Expression . + RangeStat = 'range' IdentifierList ':=' RangeExpression Block . + RangeExpression = Expression . A range expression must evaluate to an array, map or string. The identifier list must contain either one or two identifiers. If the range expression is a map, a single identifier is declared @@ -1327,11 +1388,12 @@ array elements (the values). Break statements +---- Within a 'for' or 'switch' statement, a 'break' statement terminates execution of the innermost 'for' or 'switch' statement. -BreakStat = 'break' [ identifier ]. + BreakStat = 'break' [ identifier ]. If there is an identifier, it must be the label name of an enclosing 'for' or' 'switch' statement, and that is the one whose execution terminates. @@ -1344,29 +1406,32 @@ statement, and that is the one whose execution terminates. Continue statements +---- Within a 'for' loop a continue statement begins the next iteration of the loop at the post statement. -ContinueStat = 'continue' [ identifier ]. + ContinueStat = 'continue' [ identifier ]. The optional identifier is analogous to that of a 'break' statement. Goto statements +---- A goto statement transfers control to the corresponding label statement. -GotoStat = 'goto' identifier . + GotoStat = 'goto' identifier . goto Error Label statement +---- A label statement serves as the target of a 'goto', 'break' or 'continue' statement. -LabelStat = identifier ':' . + LabelStat = identifier ':' . Error: @@ -1374,22 +1439,24 @@ There are various restrictions [TBD] as to where a label statement can be used. Packages +---- Every source file identifies the package to which it belongs. The file must begin with a package clause. -PackageClause = 'package' PackageName . + PackageClause = 'package' PackageName . package Math Import declarations +---- A program can gain access to exported items from another package through an import declaration: -ImportDecl = 'import' [ '.' | PackageName ] PackageFileName . -PackageFileName = string_lit . + ImportDecl = 'import' [ '.' | PackageName ] PackageFileName . + PackageFileName = string_lit . An import statement makes the exported contents of the named package file accessible in this package. @@ -1427,14 +1494,16 @@ an error if the import introduces name conflicts. Program +---- A program is package clause, optionally followed by import declarations, followed by a series of declarations. Program = PackageClause { ImportDecl } { Declaration } . -------------------------------------------------------------------------- +TODO +---- -TODO: type switch? -TODO: select -TODO: words about slices +- TODO: type switch? +- TODO: select +- TODO: words about slices