exports.go

Documentation: go/doc

     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