1// Copyright 2019 The Bazel Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5package resolve
6
7import "go.starlark.net/syntax"
8
9// This file defines resolver data types saved in the syntax tree.
10// We cannot guarantee API stability for these types
11// as they are closely tied to the implementation.
12
13// A Binding contains resolver information about an identifer.
14// The resolver populates the Binding field of each syntax.Identifier.
15// The Binding ties together all identifiers that denote the same variable.
16type Binding struct {
17	Scope Scope
18
19	// Index records the index into the enclosing
20	// - {DefStmt,File}.Locals, if Scope==Local
21	// - DefStmt.FreeVars,      if Scope==Free
22	// - File.Globals,          if Scope==Global.
23	// It is zero if Scope is Predeclared, Universal, or Undefined.
24	Index int
25
26	First *syntax.Ident // first binding use (iff Scope==Local/Free/Global)
27}
28
29// The Scope of Binding indicates what kind of scope it has.
30type Scope uint8
31
32const (
33	Undefined   Scope = iota // name is not defined
34	Local                    // name is local to its function or file
35	Cell                     // name is function-local but shared with a nested function
36	Free                     // name is cell of some enclosing function
37	Global                   // name is global to module
38	Predeclared              // name is predeclared for this module (e.g. glob)
39	Universal                // name is universal (e.g. len)
40)
41
42var scopeNames = [...]string{
43	Undefined:   "undefined",
44	Local:       "local",
45	Cell:        "cell",
46	Free:        "free",
47	Global:      "global",
48	Predeclared: "predeclared",
49	Universal:   "universal",
50}
51
52func (scope Scope) String() string { return scopeNames[scope] }
53
54// A Module contains resolver information about a file.
55// The resolver populates the Module field of each syntax.File.
56type Module struct {
57	Locals  []*Binding // the file's (comprehension-)local variables
58	Globals []*Binding // the file's global variables
59}
60
61// A Function contains resolver information about a named or anonymous function.
62// The resolver populates the Function field of each syntax.DefStmt and syntax.LambdaExpr.
63type Function struct {
64	Pos    syntax.Position // of DEF or LAMBDA
65	Name   string          // name of def, or "lambda"
66	Params []syntax.Expr   // param = ident | ident=expr | * | *ident | **ident
67	Body   []syntax.Stmt   // contains synthetic 'return expr' for lambda
68
69	HasVarargs      bool       // whether params includes *args (convenience)
70	HasKwargs       bool       // whether params includes **kwargs (convenience)
71	NumKwonlyParams int        // number of keyword-only optional parameters
72	Locals          []*Binding // this function's local/cell variables, parameters first
73	FreeVars        []*Binding // enclosing cells to capture in closure
74}
75