+++ /dev/null
-// Copyright 2014 The Go Authors. All rights reserved.
-// Use of this source code is governed by a BSD-style
-// license that can be found in the LICENSE file.
-
-// Package eg implements the example-based refactoring tool whose
-// command-line is defined in golang.org/x/tools/cmd/eg.
-package eg // import "golang.org/x/tools/refactor/eg"
-
-import (
- "bytes"
- "fmt"
- "go/ast"
- "go/format"
- "go/printer"
- "go/token"
- "go/types"
- "os"
-)
-
-const Help = `
-This tool implements example-based refactoring of expressions.
-
-The transformation is specified as a Go file defining two functions,
-'before' and 'after', of identical types. Each function body consists
-of a single statement: either a return statement with a single
-(possibly multi-valued) expression, or an expression statement. The
-'before' expression specifies a pattern and the 'after' expression its
-replacement.
-
- package P
- import ( "errors"; "fmt" )
- func before(s string) error { return fmt.Errorf("%s", s) }
- func after(s string) error { return errors.New(s) }
-
-The expression statement form is useful when the expression has no
-result, for example:
-
- func before(msg string) { log.Fatalf("%s", msg) }
- func after(msg string) { log.Fatal(msg) }
-
-The parameters of both functions are wildcards that may match any
-expression assignable to that type. If the pattern contains multiple
-occurrences of the same parameter, each must match the same expression
-in the input for the pattern to match. If the replacement contains
-multiple occurrences of the same parameter, the expression will be
-duplicated, possibly changing the side-effects.
-
-The tool analyses all Go code in the packages specified by the
-arguments, replacing all occurrences of the pattern with the
-substitution.
-
-So, the transform above would change this input:
- err := fmt.Errorf("%s", "error: " + msg)
-to this output:
- err := errors.New("error: " + msg)
-
-Identifiers, including qualified identifiers (p.X) are considered to
-match only if they denote the same object. This allows correct
-matching even in the presence of dot imports, named imports and
-locally shadowed package names in the input program.
-
-Matching of type syntax is semantic, not syntactic: type syntax in the
-pattern matches type syntax in the input if the types are identical.
-Thus, func(x int) matches func(y int).
-
-This tool was inspired by other example-based refactoring tools,
-'gofmt -r' for Go and Refaster for Java.
-
-
-LIMITATIONS
-===========
-
-EXPRESSIVENESS
-
-Only refactorings that replace one expression with another, regardless
-of the expression's context, may be expressed. Refactoring arbitrary
-statements (or sequences of statements) is a less well-defined problem
-and is less amenable to this approach.
-
-A pattern that contains a function literal (and hence statements)
-never matches.
-
-There is no way to generalize over related types, e.g. to express that
-a wildcard may have any integer type, for example.
-
-It is not possible to replace an expression by one of a different
-type, even in contexts where this is legal, such as x in fmt.Print(x).
-
-The struct literals T{x} and T{K: x} cannot both be matched by a single
-template.
-
-
-SAFETY
-
-Verifying that a transformation does not introduce type errors is very
-complex in the general case. An innocuous-looking replacement of one
-constant by another (e.g. 1 to 2) may cause type errors relating to
-array types and indices, for example. The tool performs only very
-superficial checks of type preservation.
-
-
-IMPORTS
-
-Although the matching algorithm is fully aware of scoping rules, the
-replacement algorithm is not, so the replacement code may contain
-incorrect identifier syntax for imported objects if there are dot
-imports, named imports or locally shadowed package names in the input
-program.
-
-Imports are added as needed, but they are not removed as needed.
-Run 'goimports' on the modified file for now.
-
-Dot imports are forbidden in the template.
-
-
-TIPS
-====
-
-Sometimes a little creativity is required to implement the desired
-migration. This section lists a few tips and tricks.
-
-To remove the final parameter from a function, temporarily change the
-function signature so that the final parameter is variadic, as this
-allows legal calls both with and without the argument. Then use eg to
-remove the final argument from all callers, and remove the variadic
-parameter by hand. The reverse process can be used to add a final
-parameter.
-
-To add or remove parameters other than the final one, you must do it in
-stages: (1) declare a variant function f' with a different name and the
-desired parameters; (2) use eg to transform calls to f into calls to f',
-changing the arguments as needed; (3) change the declaration of f to
-match f'; (4) use eg to rename f' to f in all calls; (5) delete f'.
-`
-
-// TODO(adonovan): expand upon the above documentation as an HTML page.
-
-// A Transformer represents a single example-based transformation.
-type Transformer struct {
- fset *token.FileSet
- verbose bool
- info *types.Info // combined type info for template/input/output ASTs
- seenInfos map[*types.Info]bool
- wildcards map[*types.Var]bool // set of parameters in func before()
- env map[string]ast.Expr // maps parameter name to wildcard binding
- importedObjs map[types.Object]*ast.SelectorExpr // objects imported by after().
- before, after ast.Expr
- afterStmts []ast.Stmt
- allowWildcards bool
-
- // Working state of Transform():
- nsubsts int // number of substitutions made
- currentPkg *types.Package // package of current call
-}
-
-// NewTransformer returns a transformer based on the specified template,
-// a single-file package containing "before" and "after" functions as
-// described in the package documentation.
-// tmplInfo is the type information for tmplFile.
-//
-func NewTransformer(fset *token.FileSet, tmplPkg *types.Package, tmplFile *ast.File, tmplInfo *types.Info, verbose bool) (*Transformer, error) {
- // Check the template.
- beforeSig := funcSig(tmplPkg, "before")
- if beforeSig == nil {
- return nil, fmt.Errorf("no 'before' func found in template")
- }
- afterSig := funcSig(tmplPkg, "after")
- if afterSig == nil {
- return nil, fmt.Errorf("no 'after' func found in template")
- }
-
- // TODO(adonovan): should we also check the names of the params match?
- if !types.Identical(afterSig, beforeSig) {
- return nil, fmt.Errorf("before %s and after %s functions have different signatures",
- beforeSig, afterSig)
- }
-
- for _, imp := range tmplFile.Imports {
- if imp.Name != nil && imp.Name.Name == "." {
- // Dot imports are currently forbidden. We
- // make the simplifying assumption that all
- // imports are regular, without local renames.
- return nil, fmt.Errorf("dot-import (of %s) in template", imp.Path.Value)
- }
- }
- var beforeDecl, afterDecl *ast.FuncDecl
- for _, decl := range tmplFile.Decls {
- if decl, ok := decl.(*ast.FuncDecl); ok {
- switch decl.Name.Name {
- case "before":
- beforeDecl = decl
- case "after":
- afterDecl = decl
- }
- }
- }
-
- before, err := soleExpr(beforeDecl)
- if err != nil {
- return nil, fmt.Errorf("before: %s", err)
- }
- afterStmts, after, err := stmtAndExpr(afterDecl)
- if err != nil {
- return nil, fmt.Errorf("after: %s", err)
- }
-
- wildcards := make(map[*types.Var]bool)
- for i := 0; i < beforeSig.Params().Len(); i++ {
- wildcards[beforeSig.Params().At(i)] = true
- }
-
- // checkExprTypes returns an error if Tb (type of before()) is not
- // safe to replace with Ta (type of after()).
- //
- // Only superficial checks are performed, and they may result in both
- // false positives and negatives.
- //
- // Ideally, we would only require that the replacement be assignable
- // to the context of a specific pattern occurrence, but the type
- // checker doesn't record that information and it's complex to deduce.
- // A Go type cannot capture all the constraints of a given expression
- // context, which may include the size, constness, signedness,
- // namedness or constructor of its type, and even the specific value
- // of the replacement. (Consider the rule that array literal keys
- // must be unique.) So we cannot hope to prove the safety of a
- // transformation in general.
- Tb := tmplInfo.TypeOf(before)
- Ta := tmplInfo.TypeOf(after)
- if types.AssignableTo(Tb, Ta) {
- // safe: replacement is assignable to pattern.
- } else if tuple, ok := Tb.(*types.Tuple); ok && tuple.Len() == 0 {
- // safe: pattern has void type (must appear in an ExprStmt).
- } else {
- return nil, fmt.Errorf("%s is not a safe replacement for %s", Ta, Tb)
- }
-
- tr := &Transformer{
- fset: fset,
- verbose: verbose,
- wildcards: wildcards,
- allowWildcards: true,
- seenInfos: make(map[*types.Info]bool),
- importedObjs: make(map[types.Object]*ast.SelectorExpr),
- before: before,
- after: after,
- afterStmts: afterStmts,
- }
-
- // Combine type info from the template and input packages, and
- // type info for the synthesized ASTs too. This saves us
- // having to book-keep where each ast.Node originated as we
- // construct the resulting hybrid AST.
- tr.info = &types.Info{
- Types: make(map[ast.Expr]types.TypeAndValue),
- Defs: make(map[*ast.Ident]types.Object),
- Uses: make(map[*ast.Ident]types.Object),
- Selections: make(map[*ast.SelectorExpr]*types.Selection),
- }
- mergeTypeInfo(tr.info, tmplInfo)
-
- // Compute set of imported objects required by after().
- // TODO(adonovan): reject dot-imports in pattern
- ast.Inspect(after, func(n ast.Node) bool {
- if n, ok := n.(*ast.SelectorExpr); ok {
- if _, ok := tr.info.Selections[n]; !ok {
- // qualified ident
- obj := tr.info.Uses[n.Sel]
- tr.importedObjs[obj] = n
- return false // prune
- }
- }
- return true // recur
- })
-
- return tr, nil
-}
-
-// WriteAST is a convenience function that writes AST f to the specified file.
-func WriteAST(fset *token.FileSet, filename string, f *ast.File) (err error) {
- fh, err := os.Create(filename)
- if err != nil {
- return err
- }
-
- defer func() {
- if err2 := fh.Close(); err != nil {
- err = err2 // prefer earlier error
- }
- }()
- return format.Node(fh, fset, f)
-}
-
-// -- utilities --------------------------------------------------------
-
-// funcSig returns the signature of the specified package-level function.
-func funcSig(pkg *types.Package, name string) *types.Signature {
- if f, ok := pkg.Scope().Lookup(name).(*types.Func); ok {
- return f.Type().(*types.Signature)
- }
- return nil
-}
-
-// soleExpr returns the sole expression in the before/after template function.
-func soleExpr(fn *ast.FuncDecl) (ast.Expr, error) {
- if fn.Body == nil {
- return nil, fmt.Errorf("no body")
- }
- if len(fn.Body.List) != 1 {
- return nil, fmt.Errorf("must contain a single statement")
- }
- switch stmt := fn.Body.List[0].(type) {
- case *ast.ReturnStmt:
- if len(stmt.Results) != 1 {
- return nil, fmt.Errorf("return statement must have a single operand")
- }
- return stmt.Results[0], nil
-
- case *ast.ExprStmt:
- return stmt.X, nil
- }
-
- return nil, fmt.Errorf("must contain a single return or expression statement")
-}
-
-// stmtAndExpr returns the expression in the last return statement as well as the preceding lines.
-func stmtAndExpr(fn *ast.FuncDecl) ([]ast.Stmt, ast.Expr, error) {
- if fn.Body == nil {
- return nil, nil, fmt.Errorf("no body")
- }
-
- n := len(fn.Body.List)
- if n == 0 {
- return nil, nil, fmt.Errorf("must contain at least one statement")
- }
-
- stmts, last := fn.Body.List[:n-1], fn.Body.List[n-1]
-
- switch last := last.(type) {
- case *ast.ReturnStmt:
- if len(last.Results) != 1 {
- return nil, nil, fmt.Errorf("return statement must have a single operand")
- }
- return stmts, last.Results[0], nil
-
- case *ast.ExprStmt:
- return stmts, last.X, nil
- }
-
- return nil, nil, fmt.Errorf("must end with a single return or expression statement")
-}
-
-// mergeTypeInfo adds type info from src to dst.
-func mergeTypeInfo(dst, src *types.Info) {
- for k, v := range src.Types {
- dst.Types[k] = v
- }
- for k, v := range src.Defs {
- dst.Defs[k] = v
- }
- for k, v := range src.Uses {
- dst.Uses[k] = v
- }
- for k, v := range src.Selections {
- dst.Selections[k] = v
- }
-}
-
-// (debugging only)
-func astString(fset *token.FileSet, n ast.Node) string {
- var buf bytes.Buffer
- printer.Fprint(&buf, fset, n)
- return buf.String()
-}
projects / dotfiles / .git / blobdiff