1 // Copyright 2014 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.
5 // Package rename contains the implementation of the 'gorename' command
6 // whose main function is in golang.org/x/tools/cmd/gorename.
7 // See the Usage constant for the command documentation.
8 package rename // import "golang.org/x/tools/refactor/rename"
20 exec "golang.org/x/sys/execabs"
31 "golang.org/x/tools/go/loader"
32 "golang.org/x/tools/go/types/typeutil"
33 "golang.org/x/tools/refactor/importgraph"
34 "golang.org/x/tools/refactor/satisfy"
37 const Usage = `gorename: precise type-safe renaming of identifiers in Go source code.
41 gorename (-from <spec> | -offset <file>:#<byte-offset>) -to <name> [-force]
43 You must specify the object (named entity) to rename using the -offset
44 or -from flag. Exactly one must be specified.
48 -offset specifies the filename and byte offset of an identifier to rename.
49 This form is intended for use by text editors.
51 -from specifies the object to rename using a query notation;
52 This form is intended for interactive use at the command line.
53 A legal -from query has one of the following forms:
55 "encoding/json".Decoder.Decode method of package-level named type
56 (*"encoding/json".Decoder).Decode ditto, alternative syntax
57 "encoding/json".Decoder.buf field of package-level named struct type
58 "encoding/json".HTMLEscape package member (const, func, var, type)
59 "encoding/json".Decoder.Decode::x local object x within a method
60 "encoding/json".HTMLEscape::x local object x within a function
61 "encoding/json"::x object x anywhere within a package
62 json.go::x object x within file json.go
64 Double-quotes must be escaped when writing a shell command.
65 Quotes may be omitted for single-segment import paths such as "fmt".
67 For methods, the parens and '*' on the receiver type are both
70 It is an error if one of the ::x queries matches multiple
75 -force causes the renaming to proceed even if conflicts were reported.
76 The resulting program may be ill-formed, or experience a change
79 WARNING: this flag may even cause the renaming tool to crash.
80 (In due course this bug will be fixed by moving certain
81 analyses into the type-checker.)
83 -d display diffs instead of rewriting files
85 -v enables verbose logging.
87 gorename automatically computes the set of packages that might be
88 affected. For a local renaming, this is just the package specified by
89 -from or -offset, but for a potentially exported name, gorename scans
90 the workspace ($GOROOT and $GOPATH).
92 gorename rejects renamings of concrete methods that would change the
93 assignability relation between types and interfaces. If the interface
94 change was intentional, initiate the renaming at the interface method.
96 gorename rejects any renaming that would create a conflict at the point
97 of declaration, or a reference conflict (ambiguity or shadowing), or
98 anything else that could cause the resulting program not to compile.
103 $ gorename -offset file.go:#123 -to foo
105 Rename the object whose identifier is at byte offset 123 within file file.go.
107 $ gorename -from '"bytes".Buffer.Len' -to Size
109 Rename the "Len" method of the *bytes.Buffer type to "Size".
115 // - handle dot imports correctly
116 // - document limitations (reflection, 'implements' algorithm).
117 // - sketch a proof of exhaustiveness.
120 // - support running on packages specified as *.go files on the command line
121 // - support running on programs containing errors (loader.Config.AllowErrors)
122 // - allow users to specify a scope other than "global" (to avoid being
123 // stuck by neglected packages in $GOPATH that don't build).
124 // - support renaming the package clause (no object)
125 // - support renaming an import path (no ident or object)
126 // (requires filesystem + SCM updates).
127 // - detect and reject edits to autogenerated files (cgo, protobufs)
128 // and optionally $GOROOT packages.
129 // - report all conflicts, or at least all qualitatively distinct ones.
130 // Sometimes we stop to avoid redundancy, but
131 // it may give a disproportionate sense of safety in -force mode.
132 // - support renaming all instances of a pattern, e.g.
133 // all receiver vars of a given type,
134 // all local variables of a given type,
135 // all PkgNames for a given package.
136 // - emit JSON output for other editors and tools.
139 // Force enables patching of the source files even if conflicts were reported.
140 // The resulting program may be ill-formed.
141 // It may even cause gorename to crash. TODO(adonovan): fix that.
144 // Diff causes the tool to display diffs instead of rewriting files.
147 // DiffCmd specifies the diff command used by the -d feature.
148 // (The command must accept a -u flag and two filename arguments.)
151 // ConflictError is returned by Main when it aborts the renaming due to conflicts.
152 // (It is distinguished because the interesting errors are the conflicts themselves.)
153 ConflictError = errors.New("renaming aborted due to conflicts")
155 // Verbose enables extra logging.
159 var stdout io.Writer = os.Stdout
161 type renamer struct {
162 iprog *loader.Program
163 objsToUpdate map[types.Object]bool
166 satisfyConstraints map[satisfy.Constraint]bool
167 packages map[*types.Package]*loader.PackageInfo // subset of iprog.AllPackages to inspect
168 msets typeutil.MethodSetCache
172 var reportError = func(posn token.Position, message string) {
173 fmt.Fprintf(os.Stderr, "%s: %s\n", posn, message)
176 // importName renames imports of fromPath within the package specified by info.
177 // If fromName is not empty, importName renames only imports as fromName.
178 // If the renaming would lead to a conflict, the file is left unchanged.
179 func importName(iprog *loader.Program, info *loader.PackageInfo, fromPath, fromName, to string) error {
181 return nil // no-op (e.g. rename x/foo to y/foo)
183 for _, f := range info.Files {
184 var from types.Object
185 for _, imp := range f.Imports {
186 importPath, _ := strconv.Unquote(imp.Path.Value)
187 importName := path.Base(importPath)
189 importName = imp.Name.Name
191 if importPath == fromPath && (fromName == "" || importName == fromName) {
192 from = info.Implicits[imp]
201 objsToUpdate: make(map[types.Object]bool),
203 packages: map[*types.Package]*loader.PackageInfo{info.Pkg: info},
207 reportError(iprog.Fset.Position(f.Imports[0].Pos()),
208 "skipping update of this file")
209 continue // ignore errors; leave the existing name
211 if err := r.update(); err != nil {
218 func Main(ctxt *build.Context, offsetFlag, fromFlag, to string) error {
219 // -- Parse the -from or -offset specifier ----------------------------
221 if (offsetFlag == "") == (fromFlag == "") {
222 return fmt.Errorf("exactly one of the -from and -offset flags must be specified")
225 if !isValidIdentifier(to) {
226 return fmt.Errorf("-to %q: not a valid identifier", to)
230 defer func(saved func(string, []byte) error) { writeFile = saved }(writeFile)
237 spec, err = parseFromFlag(ctxt, fromFlag)
239 spec, err = parseOffsetFlag(ctxt, offsetFlag)
245 if spec.fromName == to {
246 return fmt.Errorf("the old and new names are the same: %s", to)
249 // -- Load the program consisting of the initial package -------------
251 iprog, err := loadProgram(ctxt, map[string]bool{spec.pkg: true})
256 fromObjects, err := findFromObjects(iprog, spec)
261 // -- Load a larger program, for global renamings ---------------------
263 if requiresGlobalRename(fromObjects, to) {
264 // For a local refactoring, we needn't load more
265 // packages, but if the renaming affects the package's
266 // API, we we must load all packages that depend on the
267 // package defining the object, plus their tests.
270 log.Print("Potentially global renaming; scanning workspace...")
273 // Scan the workspace and build the import graph.
274 _, rev, errors := importgraph.Build(ctxt)
276 // With a large GOPATH tree, errors are inevitable.
277 // Report them but proceed.
278 fmt.Fprintf(os.Stderr, "While scanning Go workspace:\n")
279 for path, err := range errors {
280 fmt.Fprintf(os.Stderr, "Package %q: %s.\n", path, err)
284 // Enumerate the set of potentially affected packages.
285 affectedPackages := make(map[string]bool)
286 for _, obj := range fromObjects {
287 // External test packages are never imported,
288 // so they will never appear in the graph.
289 for path := range rev.Search(obj.Pkg().Path()) {
290 affectedPackages[path] = true
294 // TODO(adonovan): allow the user to specify the scope,
295 // or -ignore patterns? Computing the scope when we
296 // don't (yet) support inputs containing errors can make
297 // the tool rather brittle.
299 // Re-load the larger program.
300 iprog, err = loadProgram(ctxt, affectedPackages)
305 fromObjects, err = findFromObjects(iprog, spec)
311 // -- Do the renaming -------------------------------------------------
315 objsToUpdate: make(map[types.Object]bool),
318 packages: make(map[*types.Package]*loader.PackageInfo),
321 // A renaming initiated at an interface method indicates the
322 // intention to rename abstract and concrete methods as needed
323 // to preserve assignability.
324 for _, obj := range fromObjects {
325 if obj, ok := obj.(*types.Func); ok {
326 recv := obj.Type().(*types.Signature).Recv()
327 if recv != nil && isInterface(recv.Type().Underlying()) {
328 r.changeMethods = true
334 // Only the initially imported packages (iprog.Imported) and
335 // their external tests (iprog.Created) should be inspected or
336 // modified, as only they have type-checked functions bodies.
337 // The rest are just dependencies, needed only for package-level
339 for _, info := range iprog.Imported {
340 r.packages[info.Pkg] = info
342 for _, info := range iprog.Created { // (tests)
343 r.packages[info.Pkg] = info
346 for _, from := range fromObjects {
349 if r.hadConflicts && !Force {
355 // loadProgram loads the specified set of packages (plus their tests)
356 // and all their dependencies, from source, through the specified build
357 // context. Only packages in pkgs will have their functions bodies typechecked.
358 func loadProgram(ctxt *build.Context, pkgs map[string]bool) (*loader.Program, error) {
359 conf := loader.Config{
361 ParserMode: parser.ParseComments,
363 // TODO(adonovan): enable this. Requires making a lot of code more robust!
366 // Optimization: don't type-check the bodies of functions in our
367 // dependencies, since we only need exported package members.
368 conf.TypeCheckFuncBodies = func(p string) bool {
369 return pkgs[p] || pkgs[strings.TrimSuffix(p, "_test")]
374 for pkg := range pkgs {
375 list = append(list, pkg)
378 for _, pkg := range list {
379 log.Printf("Loading package: %s", pkg)
383 for pkg := range pkgs {
384 conf.ImportWithTests(pkg)
387 // Ideally we would just return conf.Load() here, but go/types
388 // reports certain "soft" errors that gc does not (Go issue 14596).
389 // As a workaround, we set AllowErrors=true and then duplicate
390 // the loader's error checking but allow soft errors.
391 // It would be nice if the loader API permitted "AllowErrors: soft".
392 conf.AllowErrors = true
393 prog, err := conf.Load()
399 // Report hard errors in indirectly imported packages.
400 for _, info := range prog.AllPackages {
401 if containsHardErrors(info.Errors) {
402 errpkgs = append(errpkgs, info.Pkg.Path())
407 if len(errpkgs) > 3 {
408 more = fmt.Sprintf(" and %d more", len(errpkgs)-3)
409 errpkgs = errpkgs[:3]
411 return nil, fmt.Errorf("couldn't load packages due to errors: %s%s",
412 strings.Join(errpkgs, ", "), more)
417 func containsHardErrors(errors []error) bool {
418 for _, err := range errors {
419 if err, ok := err.(types.Error); ok && err.Soft {
427 // requiresGlobalRename reports whether this renaming could potentially
428 // affect other packages in the Go workspace.
429 func requiresGlobalRename(fromObjects []types.Object, to string) bool {
431 for _, from := range fromObjects {
435 switch objectKind(from) {
436 case "type", "field", "method":
440 if ast.IsExported(to) && tfm {
441 // A global renaming may be necessary even if we're
442 // exporting a previous unexported name, since if it's
443 // the name of a type, field or method, this could
444 // change selections in other packages.
445 // (We include "type" in this list because a type
446 // used as an embedded struct field entails a field
453 // update updates the input files.
454 func (r *renamer) update() error {
455 // We use token.File, not filename, since a file may appear to
456 // belong to multiple packages and be parsed more than once.
457 // token.File captures this distinction; filename does not.
460 var filesToUpdate = make(map[*token.File]bool)
461 docRegexp := regexp.MustCompile(`\b` + r.from + `\b`)
462 for _, info := range r.packages {
463 // Mutate the ASTs and note the filenames.
464 for id, obj := range info.Defs {
465 if r.objsToUpdate[obj] {
468 filesToUpdate[r.iprog.Fset.File(id.Pos())] = true
469 // Perform the rename in doc comments too.
470 if doc := r.docComment(id); doc != nil {
471 for _, comment := range doc.List {
472 comment.Text = docRegexp.ReplaceAllString(comment.Text, r.to)
478 for id, obj := range info.Uses {
479 if r.objsToUpdate[obj] {
482 filesToUpdate[r.iprog.Fset.File(id.Pos())] = true
487 // Renaming not supported if cgo files are affected.
488 var generatedFileNames []string
489 for _, info := range r.packages {
490 for _, f := range info.Files {
491 tokenFile := r.iprog.Fset.File(f.Pos())
492 if filesToUpdate[tokenFile] && generated(f, tokenFile) {
493 generatedFileNames = append(generatedFileNames, tokenFile.Name())
497 if !Force && len(generatedFileNames) > 0 {
498 return fmt.Errorf("refusing to modify generated file%s containing DO NOT EDIT marker: %v", plural(len(generatedFileNames)), generatedFileNames)
501 // Write affected files.
503 for _, info := range r.packages {
505 for _, f := range info.Files {
506 tokenFile := r.iprog.Fset.File(f.Pos())
507 if filesToUpdate[tokenFile] {
512 log.Printf("Updating package %s", info.Pkg.Path())
516 filename := tokenFile.Name()
518 if err := format.Node(&buf, r.iprog.Fset, f); err != nil {
519 log.Printf("failed to pretty-print syntax tree: %v", err)
523 if err := writeFile(filename, buf.Bytes()); err != nil {
531 fmt.Printf("Renamed %d occurrence%s in %d file%s in %d package%s.\n",
532 nidents, plural(nidents),
533 len(filesToUpdate), plural(len(filesToUpdate)),
534 npkgs, plural(npkgs))
537 return fmt.Errorf("failed to rewrite %d file%s", nerrs, plural(nerrs))
542 // docComment returns the doc for an identifier.
543 func (r *renamer) docComment(id *ast.Ident) *ast.CommentGroup {
544 _, nodes, _ := r.iprog.PathEnclosingInterval(id.Pos(), id.End())
545 for _, node := range nodes {
546 switch decl := node.(type) {
553 // For {Type,Value}Spec, if the doc on the spec is absent,
554 // search for the enclosing GenDecl
571 func plural(n int) string {
578 // writeFile is a seam for testing and for the -d flag.
579 var writeFile = reallyWriteFile
581 func reallyWriteFile(filename string, content []byte) error {
582 return ioutil.WriteFile(filename, content, 0644)
585 func diff(filename string, content []byte) error {
586 renamed := fmt.Sprintf("%s.%d.renamed", filename, os.Getpid())
587 if err := ioutil.WriteFile(renamed, content, 0644); err != nil {
590 defer os.Remove(renamed)
592 diff, err := exec.Command(DiffCmd, "-u", filename, renamed).CombinedOutput()
594 // diff exits with a non-zero status when the files don't match.
595 // Ignore that failure as long as we get output.
600 return fmt.Errorf("computing diff: %v", err)