.GO File Format – Declarations and scope

Blocks

Block         = "{" StatementList "}" .
StatementList = { Statement ";" } .

A block is a possibly empty sequence of declarations and statements in matching braces. There are also implicit blocks (spec: Blocks):

1. The universe block holds all Go source text.
2. Each package has a package block with all its source text.
3. Each file has a file block with all its source text.
4. Each if, for and switch statement is in its own implicit block.
5. Each clause in a switch or select statement is an implicit block.

Scope

Go is lexically scoped using blocks. The scope of an identifier is the extent of source in which it denotes the declared thing.

• An identifier may be redeclared in an inner block. While the inner declaration is in scope, it hides the outer one.
• Top-level declarations are visible throughout the package, regardless of order, in all its files. An identifier may not be declared in both the file block and the package block.
• The scope of a local variable starts after its declaration, so x := x + 1 in an inner block uses the outer x on the right. The scope of a local type starts at its name, so a local type can refer to itself.
• init may be used in the package block only to declare init functions, and introduces no binding (see Packages and modules).

x := 1
if x := 2; x > 0 {       // a new x, in the if statement's implicit block
	fmt.Println(x)       // prints 2
}
fmt.Println(x)           // prints 1

for i := 0; i < 3; i++ {
	i := i * 10          // a new i in the body; the loop's i is untouched
	fmt.Println(i)
}

var _ io.Reader = (*File)(nil)  // compile-time check that *File implements io.Reader
_, err := os.Open(name)         // ignore the first result
import _ "net/http/pprof"       // import only for its side effects

Constants

Constants are boolean, rune, integer, floating-point, complex or string. A constant may be written as a literal, a constant identifier, a constant expression, a conversion that yields a constant, or a call to certain built-in functions such as min, max, len or unsafe.Sizeof (spec: Constants).

• Numeric constants are exact values of arbitrary precision and do not overflow. There are no constants for negative zero, infinity or NaN. Implementations must hold integers with at least 256 bits.
• A constant may be typed or untyped. Literals, true, false, iota and many constant expressions are untyped.
• An untyped constant has a default type: bool, rune, int, float64, complex128 or string, used when a typed value is needed.
• A typed constant must be representable in its type: uint(-1) and int(3.14) are errors. An untyped constant is not bound until used, so const Huge = 1 << 100 is valid. See Constant expressions.

ConstDecl      = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) .
ConstSpec      = IdentifierList [ [ Type ] "=" ExpressionList ] .
IdentifierList = identifier { "," identifier } .
ExpressionList = Expression { "," Expression } .

const Pi float64 = 3.14159265358979323846
const zero = 0.0         // untyped floating-point constant
const (
	size int64 = 1024
	eof        = -1  // untyped integer constant
)
const a, b, c = 3, 4, "foo"  // a = 3, b = 4, c = "foo"
const u, v float32 = 0, 3    // u = 0.0, v = 3.0

const (
	c0 = iota  // c0 == 0
	c1 = iota  // c1 == 1
	c2 = iota  // c2 == 2
)

const (
	a = 1 << iota  // a == 1  (iota == 0)
	b = 1 << iota  // b == 2  (iota == 1)
	c = 3          // c == 3  (iota == 2, unused)
	d = 1 << iota  // d == 8  (iota == 3)
)

const (
	bit0, mask0 = 1 << iota, 1<<iota - 1  // bit0 == 1, mask0 == 0  (iota == 0)
	bit1, mask1                           // bit1 == 2, mask1 == 1  (iota == 1)
	_, _                                  //                        (iota == 2, unused)
	bit3, mask3                           // bit3 == 8, mask3 == 7  (iota == 3)
)

const x = iota  // x == 0: iota restarts at each const declaration
const y = iota  // y == 0

type Weekday int

const (
	Sunday Weekday = iota
	Monday
	Tuesday
)

Variable declarations

VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) .
VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) .

var i int
var U, V, W float64
var k = 0
var x, y float32 = -1, -2
var (
	u, v, s = 2.0, 3.0, "bar"
)
var re, im = complexSqrt(-1)
var _, found = entries[name]  // map lookup; only interested in "found"

• With a list of expressions, the variables are initialised by the assignment rules. Without one, each gets its zero value.
• Without a type, each variable takes the type of its initial value. An untyped constant takes its default type first; an untyped boolean value becomes bool. nil cannot initialise a variable with no type.
• A compiler may reject a variable declared in a function body and never used. The gc compiler does.

Short variable declarations

ShortVarDecl = IdentifierList ":=" ExpressionList .

A short variable declaration is shorthand for a variable declaration with initial values and no types. It may appear only inside functions. It can redeclare a variable that was declared earlier in the same block (or the parameter list, if the block is the function body) with the same type, provided at least one non-blank variable on the left is new. Redeclaration assigns to the original variable; it does not make a new one. The non-blank names on the left must be unique.

i, j := 0, 10
f := func() int { return 7 }
ch := make(chan int)
r, w, _ := os.Pipe()

field1, offset := nextField(str, 0)
field2, offset := nextField(str, offset)  // redeclares offset
x, y, x := 1, 2, 3                        // illegal: x repeated on left side of :=

Short declarations are also used in the headers of if, for and switch statements to declare variables local to them.

Type declarations

TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) .
TypeSpec = AliasDecl | TypeDef .

AliasDecl = identifier [ TypeParameters ] "=" Type .

type (
	nodeList = []*Node  // nodeList and []*Node are identical types
	Polar    = polar    // Polar and polar denote identical types
)

type set[P comparable] = map[P]bool

TypeDef = identifier [ TypeParameters ] Type .

type (
	Point struct{ x, y float64 }  // Point and struct{ x, y float64 } are different types
	polar Point                   // polar and Point denote different types
)

type TimeZone int

const (
	EST TimeZone = -(5 + iota)
	CST
	MST
	PST
)

func (tz TimeZone) String() string {
	return fmt.Sprintf("GMT%+dh", tz)
}

// NewMutex has the same composition as Mutex but its method set is empty.
type NewMutex Mutex

// The method set of PtrMutex's underlying type *Mutex remains unchanged,
// but the method set of PtrMutex is empty.
type PtrMutex *Mutex

// The method set of *PrintableMutex contains the methods
// Lock and Unlock bound to its embedded field Mutex.
type PrintableMutex struct {
	Mutex
}