scope.go

     1  // Copyright 2013 The Go 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  
     5  // This file implements Scopes.
     6  
     7  package types2
     8  
     9  import (
    10  	"cmd/compile/internal/syntax"
    11  	"fmt"
    12  	"io"
    13  	"slices"
    14  	"strings"
    15  	"sync"
    16  )
    17  
    18  // A Scope maintains a set of objects and links to its containing
    19  // (parent) and contained (children) scopes. Objects may be inserted
    20  // and looked up by name. The zero value for Scope is a ready-to-use
    21  // empty scope.
    22  type Scope struct {
    23  	parent   *Scope
    24  	children []*Scope
    25  	number   int               // parent.children[number-1] is this scope; 0 if there is no parent
    26  	elems    map[string]Object // lazily allocated
    27  	pos, end syntax.Pos        // scope extent; may be invalid
    28  	comment  string            // for debugging only
    29  	isFunc   bool              // set if this is a function scope (internal use only)
    30  }
    31  
    32  // NewScope returns a new, empty scope contained in the given parent
    33  // scope, if any. The comment is for debugging only.
    34  func NewScope(parent *Scope, pos, end syntax.Pos, comment string) *Scope {
    35  	s := &Scope{parent, nil, 0, nil, pos, end, comment, false}
    36  	// don't add children to Universe scope!
    37  	if parent != nil && parent != Universe {
    38  		parent.children = append(parent.children, s)
    39  		s.number = len(parent.children)
    40  	}
    41  	return s
    42  }
    43  
    44  // Parent returns the scope's containing (parent) scope.
    45  func (s *Scope) Parent() *Scope { return s.parent }
    46  
    47  // Len returns the number of scope elements.
    48  func (s *Scope) Len() int { return len(s.elems) }
    49  
    50  // Names returns the scope's element names in sorted order.
    51  func (s *Scope) Names() []string {
    52  	names := make([]string, len(s.elems))
    53  	i := 0
    54  	for name := range s.elems {
    55  		names[i] = name
    56  		i++
    57  	}
    58  	slices.Sort(names)
    59  	return names
    60  }
    61  
    62  // NumChildren returns the number of scopes nested in s.
    63  func (s *Scope) NumChildren() int { return len(s.children) }
    64  
    65  // Child returns the i'th child scope for 0 <= i < NumChildren().
    66  func (s *Scope) Child(i int) *Scope { return s.children[i] }
    67  
    68  // Lookup returns the object in scope s with the given name if such an
    69  // object exists; otherwise the result is nil.
    70  func (s *Scope) Lookup(name string) Object {
    71  	obj := resolve(name, s.elems[name])
    72  	// Hijack Lookup for "any": with gotypesalias=1, we want the Universe to
    73  	// return an Alias for "any", and with gotypesalias=0 we want to return
    74  	// the legacy representation of aliases.
    75  	//
    76  	// This is rather tricky, but works out after auditing of the usage of
    77  	// s.elems. The only external API to access scope elements is Lookup.
    78  	//
    79  	// TODO: remove this once gotypesalias=0 is no longer supported.
    80  	if obj == universeAnyAlias && !aliasAny() {
    81  		return universeAnyNoAlias
    82  	}
    83  	return obj
    84  }
    85  
    86  // lookupIgnoringCase returns the objects in scope s whose names match
    87  // the given name ignoring case. If exported is set, only exported names
    88  // are returned.
    89  func (s *Scope) lookupIgnoringCase(name string, exported bool) []Object {
    90  	var matches []Object
    91  	for _, n := range s.Names() {
    92  		if (!exported || isExported(n)) && strings.EqualFold(n, name) {
    93  			matches = append(matches, s.Lookup(n))
    94  		}
    95  	}
    96  	return matches
    97  }
    98  
    99  // Insert attempts to insert an object obj into scope s.
   100  // If s already contains an alternative object alt with
   101  // the same name, Insert leaves s unchanged and returns alt.
   102  // Otherwise it inserts obj, sets the object's parent scope
   103  // if not already set, and returns nil.
   104  func (s *Scope) Insert(obj Object) Object {
   105  	name := obj.Name()
   106  	if alt := s.Lookup(name); alt != nil {
   107  		return alt
   108  	}
   109  	s.insert(name, obj)
   110  	// TODO(gri) Can we always set the parent to s (or is there
   111  	// a need to keep the original parent or some race condition)?
   112  	// If we can, than we may not need environment.lookupScope
   113  	// which is only there so that we get the correct scope for
   114  	// marking "used" dot-imported packages.
   115  	if obj.Parent() == nil {
   116  		obj.setParent(s)
   117  	}
   118  	return nil
   119  }
   120  
   121  // InsertLazy is like Insert, but allows deferring construction of the
   122  // inserted object until it's accessed with Lookup. The Object
   123  // returned by resolve must have the same name as given to InsertLazy.
   124  // If s already contains an alternative object with the same name,
   125  // InsertLazy leaves s unchanged and returns false. Otherwise it
   126  // records the binding and returns true. The object's parent scope
   127  // will be set to s after resolve is called.
   128  func (s *Scope) InsertLazy(name string, resolve func() Object) bool {
   129  	if s.elems[name] != nil {
   130  		return false
   131  	}
   132  	s.insert(name, &lazyObject{parent: s, resolve: resolve})
   133  	return true
   134  }
   135  
   136  func (s *Scope) insert(name string, obj Object) {
   137  	if s.elems == nil {
   138  		s.elems = make(map[string]Object)
   139  	}
   140  	s.elems[name] = obj
   141  }
   142  
   143  // WriteTo writes a string representation of the scope to w,
   144  // with the scope elements sorted by name.
   145  // The level of indentation is controlled by n >= 0, with
   146  // n == 0 for no indentation.
   147  // If recurse is set, it also writes nested (children) scopes.
   148  func (s *Scope) WriteTo(w io.Writer, n int, recurse bool) {
   149  	const ind = ".  "
   150  	indn := strings.Repeat(ind, n)
   151  
   152  	fmt.Fprintf(w, "%s%s scope %p {\n", indn, s.comment, s)
   153  
   154  	indn1 := indn + ind
   155  	for _, name := range s.Names() {
   156  		fmt.Fprintf(w, "%s%s\n", indn1, s.Lookup(name))
   157  	}
   158  
   159  	if recurse {
   160  		for _, s := range s.children {
   161  			s.WriteTo(w, n+1, recurse)
   162  		}
   163  	}
   164  
   165  	fmt.Fprintf(w, "%s}\n", indn)
   166  }
   167  
   168  // String returns a string representation of the scope, for debugging.
   169  func (s *Scope) String() string {
   170  	var buf strings.Builder
   171  	s.WriteTo(&buf, 0, false)
   172  	return buf.String()
   173  }
   174  
   175  // A lazyObject represents an imported Object that has not been fully
   176  // resolved yet by its importer.
   177  type lazyObject struct {
   178  	parent  *Scope
   179  	resolve func() Object
   180  	obj     Object
   181  	once    sync.Once
   182  }
   183  
   184  // resolve returns the Object represented by obj, resolving lazy
   185  // objects as appropriate.
   186  func resolve(name string, obj Object) Object {
   187  	if lazy, ok := obj.(*lazyObject); ok {
   188  		lazy.once.Do(func() {
   189  			obj := lazy.resolve()
   190  
   191  			if _, ok := obj.(*lazyObject); ok {
   192  				panic("recursive lazy object")
   193  			}
   194  			if obj.Name() != name {
   195  				panic("lazy object has unexpected name")
   196  			}
   197  
   198  			if obj.Parent() == nil {
   199  				obj.setParent(lazy.parent)
   200  			}
   201  			lazy.obj = obj
   202  		})
   203  
   204  		obj = lazy.obj
   205  	}
   206  	return obj
   207  }
   208  
   209  // stub implementations so *lazyObject implements Object and we can
   210  // store them directly into Scope.elems.
   211  func (*lazyObject) Parent() *Scope                     { panic("unreachable") }
   212  func (*lazyObject) Pos() syntax.Pos                    { panic("unreachable") }
   213  func (*lazyObject) Pkg() *Package                      { panic("unreachable") }
   214  func (*lazyObject) Name() string                       { panic("unreachable") }
   215  func (*lazyObject) Type() Type                         { panic("unreachable") }
   216  func (*lazyObject) Exported() bool                     { panic("unreachable") }
   217  func (*lazyObject) Id() string                         { panic("unreachable") }
   218  func (*lazyObject) String() string                     { panic("unreachable") }
   219  func (*lazyObject) order() uint32                      { panic("unreachable") }
   220  func (*lazyObject) color() color                       { panic("unreachable") }
   221  func (*lazyObject) setType(Type)                       { panic("unreachable") }
   222  func (*lazyObject) setOrder(uint32)                    { panic("unreachable") }
   223  func (*lazyObject) setColor(color color)               { panic("unreachable") }
   224  func (*lazyObject) setParent(*Scope)                   { panic("unreachable") }
   225  func (*lazyObject) sameId(*Package, string, bool) bool { panic("unreachable") }
   226  func (*lazyObject) scopePos() syntax.Pos               { panic("unreachable") }
   227  func (*lazyObject) setScopePos(syntax.Pos)             { panic("unreachable") }
   228
View as plain text