resolve

Documentation

Overview

Package resolve defines a name-resolution pass for Starlark abstract syntax trees.

The resolver sets the Locals and FreeVars arrays of each DefStmt and the LocalIndex field of each syntax.Ident that refers to a local or free variable. It also sets the Locals array of a File for locals bound by top-level comprehensions and load statements. Identifiers for global variables do not get an index.

Index

• Variables
• func File(file *syntax.File, isPredeclared, isUniversal func(name string) bool) error
• func REPLChunk(file *syntax.File, isGlobal, isPredeclared, isUniversal func(name string) bool) error
• type Binding
  • func Expr(expr syntax.Expr, isPredeclared, isUniversal func(name string) bool) ([]*Binding, error)
  • func ExprOptions(opts *syntax.FileOptions, expr syntax.Expr, ...) ([]*Binding, error)
• type Error
  • func (e Error) Error() string
• type ErrorList
  • func (e ErrorList) Error() string
• type Function
• type Module
• type Scope
  • func (scope Scope) String() string

Variables

var (
	AllowSet            = false // allow the 'set' built-in
	AllowGlobalReassign = false // allow reassignment to top-level names; also, allow if/for/while at top-level
	AllowRecursion      = false // allow while statements and recursive functions
	LoadBindsGlobally   = false // load creates global not file-local bindings (deprecated)

	// obsolete flags for features that are now standard. No effect.
	AllowNestedDef = true
	AllowLambda    = true
	AllowFloat     = true
	AllowBitwise   = true
)

global options These features are either not standard Starlark (yet), or deprecated features of the BUILD language, so we put them behind flags.

Deprecated: use an explicit syntax.FileOptions argument instead, as it avoids all the usual problems of global variables.

Functions

func File

func File(file *syntax.File, isPredeclared, isUniversal func(name string) bool) error

File resolves the specified file and records information about the module in file.Module.

The isPredeclared and isUniversal predicates report whether a name is a pre-declared identifier (visible in the current module) or a universal identifier (visible in every module). Clients should typically pass predeclared.Has for the first and starlark.Universe.Has for the second, where predeclared is the module's StringDict of predeclared names and starlark.Universe is the standard set of built-ins. The isUniverse predicate is supplied a parameter to avoid a cyclic dependency upon starlark.Universe, not because users should ever need to redefine it.

func REPLChunk

func REPLChunk(file *syntax.File, isGlobal, isPredeclared, isUniversal func(name string) bool) error

REPLChunk is a generalization of the File function that supports a non-empty initial global block, as occurs in a REPL.

Types

type Binding

type Binding struct {
	Scope Scope

	// Index records the index into the enclosing
	// - {DefStmt,File}.Locals, if Scope==Local
	// - DefStmt.FreeVars,      if Scope==Free
	// - File.Globals,          if Scope==Global.
	// It is zero if Scope is Predeclared, Universal, or Undefined.
	Index int

	First *syntax.Ident // first binding use (iff Scope==Local/Free/Global)
}

A Binding contains resolver information about an identifier. The resolver populates the Binding field of each syntax.Identifier. The Binding ties together all identifiers that denote the same variable.

func Expr

func Expr(expr syntax.Expr, isPredeclared, isUniversal func(name string) bool) ([]*Binding, error)

Expr calls ExprOptions using syntax.LegacyFileOptions.

Deprecated: use ExprOptions with syntax.FileOptions instead, because this function relies on legacy global variables.

func ExprOptions

func ExprOptions(opts *syntax.FileOptions, expr syntax.Expr, isPredeclared, isUniversal func(name string) bool) ([]*Binding, error)

ExprOptions resolves the specified expression. It returns the local variables bound within the expression.

The isPredeclared and isUniversal predicates behave as for the File function

type Error

type Error struct {
	Pos syntax.Position
	Msg string
}

An Error describes the nature and position of a resolver error.

func (Error) Error

func (e Error) Error() string

type ErrorList

type ErrorList []Error // len > 0

An ErrorList is a non-empty list of resolver error messages.

func (ErrorList) Error

func (e ErrorList) Error() string

type Function

type Function struct {
	Pos    syntax.Position // of DEF or LAMBDA
	Name   string          // name of def, or "lambda"
	Params []syntax.Expr   // param = ident | ident=expr | * | *ident | **ident
	Body   []syntax.Stmt   // contains synthetic 'return expr' for lambda

	HasVarargs      bool       // whether params includes *args (convenience)
	HasKwargs       bool       // whether params includes **kwargs (convenience)
	NumKwonlyParams int        // number of keyword-only optional parameters
	Locals          []*Binding // this function's local/cell variables, parameters first
	FreeVars        []*Binding // enclosing cells to capture in closure
}

A Function contains resolver information about a named or anonymous function. The resolver populates the Function field of each syntax.DefStmt and syntax.LambdaExpr.

type Module

type Module struct {
	Locals  []*Binding // the file's (comprehension-)local variables
	Globals []*Binding // the file's global variables
}

A Module contains resolver information about a file. The resolver populates the Module field of each syntax.File.

type Scope

type Scope uint8

The Scope of Binding indicates what kind of scope it has.

const (
	Undefined   Scope = iota // name is not defined
	Local                    // name is local to its function or file
	Cell                     // name is function-local but shared with a nested function
	Free                     // name is cell of some enclosing function
	Global                   // name is global to module
	Predeclared              // name is predeclared for this module (e.g. glob)
	Universal                // name is universal (e.g. len)
)

func (Scope) String

func (scope Scope) String() string