Source file src/go/doc/exports.go

     1	// Copyright 2011 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 export filtering of an AST.
     6	
     7	package doc
     8	
     9	import (
    10		"go/ast"
    11		"go/token"
    12	)
    13	
    14	// filterIdentList removes unexported names from list in place
    15	// and returns the resulting list.
    16	//
    17	func filterIdentList(list []*ast.Ident) []*ast.Ident {
    18		j := 0
    19		for _, x := range list {
    20			if token.IsExported(x.Name) {
    21				list[j] = x
    22				j++
    23			}
    24		}
    25		return list[0:j]
    26	}
    27	
    28	var underscore = ast.NewIdent("_")
    29	
    30	func filterCompositeLit(lit *ast.CompositeLit, filter Filter, export bool) {
    31		n := len(lit.Elts)
    32		lit.Elts = filterExprList(lit.Elts, filter, export)
    33		if len(lit.Elts) < n {
    34			lit.Incomplete = true
    35		}
    36	}
    37	
    38	func filterExprList(list []ast.Expr, filter Filter, export bool) []ast.Expr {
    39		j := 0
    40		for _, exp := range list {
    41			switch x := exp.(type) {
    42			case *ast.CompositeLit:
    43				filterCompositeLit(x, filter, export)
    44			case *ast.KeyValueExpr:
    45				if x, ok := x.Key.(*ast.Ident); ok && !filter(x.Name) {
    46					continue
    47				}
    48				if x, ok := x.Value.(*ast.CompositeLit); ok {
    49					filterCompositeLit(x, filter, export)
    50				}
    51			}
    52			list[j] = exp
    53			j++
    54		}
    55		return list[0:j]
    56	}
    57	
    58	// updateIdentList replaces all unexported identifiers with underscore
    59	// and reports whether at least one exported name exists.
    60	func updateIdentList(list []*ast.Ident) (hasExported bool) {
    61		for i, x := range list {
    62			if token.IsExported(x.Name) {
    63				hasExported = true
    64			} else {
    65				list[i] = underscore
    66			}
    67		}
    68		return hasExported
    69	}
    70	
    71	// hasExportedName reports whether list contains any exported names.
    72	//
    73	func hasExportedName(list []*ast.Ident) bool {
    74		for _, x := range list {
    75			if x.IsExported() {
    76				return true
    77			}
    78		}
    79		return false
    80	}
    81	
    82	// removeErrorField removes anonymous fields named "error" from an interface.
    83	// This is called when "error" has been determined to be a local name,
    84	// not the predeclared type.
    85	//
    86	func removeErrorField(ityp *ast.InterfaceType) {
    87		list := ityp.Methods.List // we know that ityp.Methods != nil
    88		j := 0
    89		for _, field := range list {
    90			keepField := true
    91			if n := len(field.Names); n == 0 {
    92				// anonymous field
    93				if fname, _ := baseTypeName(field.Type); fname == "error" {
    94					keepField = false
    95				}
    96			}
    97			if keepField {
    98				list[j] = field
    99				j++
   100			}
   101		}
   102		if j < len(list) {
   103			ityp.Incomplete = true
   104		}
   105		ityp.Methods.List = list[0:j]
   106	}
   107	
   108	// filterFieldList removes unexported fields (field names) from the field list
   109	// in place and reports whether fields were removed. Anonymous fields are
   110	// recorded with the parent type. filterType is called with the types of
   111	// all remaining fields.
   112	//
   113	func (r *reader) filterFieldList(parent *namedType, fields *ast.FieldList, ityp *ast.InterfaceType) (removedFields bool) {
   114		if fields == nil {
   115			return
   116		}
   117		list := fields.List
   118		j := 0
   119		for _, field := range list {
   120			keepField := false
   121			if n := len(field.Names); n == 0 {
   122				// anonymous field
   123				fname := r.recordAnonymousField(parent, field.Type)
   124				if token.IsExported(fname) {
   125					keepField = true
   126				} else if ityp != nil && fname == "error" {
   127					// possibly the predeclared error interface; keep
   128					// it for now but remember this interface so that
   129					// it can be fixed if error is also defined locally
   130					keepField = true
   131					r.remember(ityp)
   132				}
   133			} else {
   134				field.Names = filterIdentList(field.Names)
   135				if len(field.Names) < n {
   136					removedFields = true
   137				}
   138				if len(field.Names) > 0 {
   139					keepField = true
   140				}
   141			}
   142			if keepField {
   143				r.filterType(nil, field.Type)
   144				list[j] = field
   145				j++
   146			}
   147		}
   148		if j < len(list) {
   149			removedFields = true
   150		}
   151		fields.List = list[0:j]
   152		return
   153	}
   154	
   155	// filterParamList applies filterType to each parameter type in fields.
   156	//
   157	func (r *reader) filterParamList(fields *ast.FieldList) {
   158		if fields != nil {
   159			for _, f := range fields.List {
   160				r.filterType(nil, f.Type)
   161			}
   162		}
   163	}
   164	
   165	// filterType strips any unexported struct fields or method types from typ
   166	// in place. If fields (or methods) have been removed, the corresponding
   167	// struct or interface type has the Incomplete field set to true.
   168	//
   169	func (r *reader) filterType(parent *namedType, typ ast.Expr) {
   170		switch t := typ.(type) {
   171		case *ast.Ident:
   172			// nothing to do
   173		case *ast.ParenExpr:
   174			r.filterType(nil, t.X)
   175		case *ast.ArrayType:
   176			r.filterType(nil, t.Elt)
   177		case *ast.StructType:
   178			if r.filterFieldList(parent, t.Fields, nil) {
   179				t.Incomplete = true
   180			}
   181		case *ast.FuncType:
   182			r.filterParamList(t.Params)
   183			r.filterParamList(t.Results)
   184		case *ast.InterfaceType:
   185			if r.filterFieldList(parent, t.Methods, t) {
   186				t.Incomplete = true
   187			}
   188		case *ast.MapType:
   189			r.filterType(nil, t.Key)
   190			r.filterType(nil, t.Value)
   191		case *ast.ChanType:
   192			r.filterType(nil, t.Value)
   193		}
   194	}
   195	
   196	func (r *reader) filterSpec(spec ast.Spec) bool {
   197		switch s := spec.(type) {
   198		case *ast.ImportSpec:
   199			// always keep imports so we can collect them
   200			return true
   201		case *ast.ValueSpec:
   202			s.Values = filterExprList(s.Values, token.IsExported, true)
   203			if len(s.Values) > 0 || s.Type == nil && len(s.Values) == 0 {
   204				// If there are values declared on RHS, just replace the unexported
   205				// identifiers on the LHS with underscore, so that it matches
   206				// the sequence of expression on the RHS.
   207				//
   208				// Similarly, if there are no type and values, then this expression
   209				// must be following an iota expression, where order matters.
   210				if updateIdentList(s.Names) {
   211					r.filterType(nil, s.Type)
   212					return true
   213				}
   214			} else {
   215				s.Names = filterIdentList(s.Names)
   216				if len(s.Names) > 0 {
   217					r.filterType(nil, s.Type)
   218					return true
   219				}
   220			}
   221		case *ast.TypeSpec:
   222			if name := s.Name.Name; token.IsExported(name) {
   223				r.filterType(r.lookupType(s.Name.Name), s.Type)
   224				return true
   225			} else if name == "error" {
   226				// special case: remember that error is declared locally
   227				r.errorDecl = true
   228			}
   229		}
   230		return false
   231	}
   232	
   233	// copyConstType returns a copy of typ with position pos.
   234	// typ must be a valid constant type.
   235	// In practice, only (possibly qualified) identifiers are possible.
   236	//
   237	func copyConstType(typ ast.Expr, pos token.Pos) ast.Expr {
   238		switch typ := typ.(type) {
   239		case *ast.Ident:
   240			return &ast.Ident{Name: typ.Name, NamePos: pos}
   241		case *ast.SelectorExpr:
   242			if id, ok := typ.X.(*ast.Ident); ok {
   243				// presumably a qualified identifier
   244				return &ast.SelectorExpr{
   245					Sel: ast.NewIdent(typ.Sel.Name),
   246					X:   &ast.Ident{Name: id.Name, NamePos: pos},
   247				}
   248			}
   249		}
   250		return nil // shouldn't happen, but be conservative and don't panic
   251	}
   252	
   253	func (r *reader) filterSpecList(list []ast.Spec, tok token.Token) []ast.Spec {
   254		if tok == token.CONST {
   255			// Propagate any type information that would get lost otherwise
   256			// when unexported constants are filtered.
   257			var prevType ast.Expr
   258			for _, spec := range list {
   259				spec := spec.(*ast.ValueSpec)
   260				if spec.Type == nil && len(spec.Values) == 0 && prevType != nil {
   261					// provide current spec with an explicit type
   262					spec.Type = copyConstType(prevType, spec.Pos())
   263				}
   264				if hasExportedName(spec.Names) {
   265					// exported names are preserved so there's no need to propagate the type
   266					prevType = nil
   267				} else {
   268					prevType = spec.Type
   269				}
   270			}
   271		}
   272	
   273		j := 0
   274		for _, s := range list {
   275			if r.filterSpec(s) {
   276				list[j] = s
   277				j++
   278			}
   279		}
   280		return list[0:j]
   281	}
   282	
   283	func (r *reader) filterDecl(decl ast.Decl) bool {
   284		switch d := decl.(type) {
   285		case *ast.GenDecl:
   286			d.Specs = r.filterSpecList(d.Specs, d.Tok)
   287			return len(d.Specs) > 0
   288		case *ast.FuncDecl:
   289			// ok to filter these methods early because any
   290			// conflicting method will be filtered here, too -
   291			// thus, removing these methods early will not lead
   292			// to the false removal of possible conflicts
   293			return token.IsExported(d.Name.Name)
   294		}
   295		return false
   296	}
   297	
   298	// fileExports removes unexported declarations from src in place.
   299	//
   300	func (r *reader) fileExports(src *ast.File) {
   301		j := 0
   302		for _, d := range src.Decls {
   303			if r.filterDecl(d) {
   304				src.Decls[j] = d
   305				j++
   306			}
   307		}
   308		src.Decls = src.Decls[0:j]
   309	}
   310	

View as plain text