refactor

Documentation

Overview

Package refactor provides operators to compute common textual edits for refactoring tools.

This package should not use features of the analysis API other than Edit.

Index

• func FreshName(scope *types.Scope, pos token.Pos, preferred string) string
• type Edit
  • func AddImport(info *types.Info, file *ast.File, preferredName, pkgpath, member string, ...) (prefix string, edits []Edit)
  • func AddImportEdits(file *ast.File, name, pkgpath string) []Edit
  • func DeleteDecl(tokFile *token.File, curDecl inspector.Cursor) []Edit
  • func DeleteSpec(tokFile *token.File, curSpec inspector.Cursor) []Edit
  • func DeleteStmt(file *token.File, curStmt inspector.Cursor) []Edit
  • func DeleteUnusedVars(index *typeindex.Index, info *types.Info, tokFile *token.File, ...) []Edit
  • func DeleteVar(tokFile *token.File, info *types.Info, curId inspector.Cursor) []Edit

Functions

func FreshName

func FreshName(scope *types.Scope, pos token.Pos, preferred string) string

FreshName returns the name of an identifier that is undefined at the specified position, based on the preferred name.

TODO(adonovan): refine this to choose a fresh name only when there would be a conflict with the existing declaration: it's fine to redeclare a name in a narrower scope so long as there are no free references to the outer name from within the narrower scope.

Types

type Edit

type Edit = analysis.TextEdit

An Edit describes a deletion and/or an insertion.

func AddImport

func AddImport(info *types.Info, file *ast.File, preferredName, pkgpath, member string, pos token.Pos) (prefix string, edits []Edit)

AddImport returns the prefix (either "pkg." or "") that should be used to qualify references to the desired symbol (member) imported from the specified package, plus any necessary edits to the file's import declaration to add a new import.

If the import already exists, and is accessible at pos, AddImport returns the existing name and no edits. (If the existing import is a dot import, the prefix is "".)

Otherwise, it adds a new import, using a local name derived from the preferred name. To request a blank import, use a preferredName of "_", and discard the prefix result; member is ignored in this case.

AddImport accepts the caller's implicit claim that the imported package declares member.

AddImport does not mutate its arguments.

func AddImportEdits

func AddImportEdits(file *ast.File, name, pkgpath string) []Edit

AddImportEdits returns the edits to add an import of the specified package, without any analysis of whether this is necessary or safe. If name is nonempty, it is used as an explicit [ImportSpec.Name].

A sequence of calls to AddImportEdits that each add the file's first import (or in a file that does not have a grouped import) may result in multiple import declarations, rather than a single one with multiple ImportSpecs. However, a subsequent run of x/tools/cmd/goimports ([imports.Process]) will combine them.

AddImportEdits does not mutate the AST.

func DeleteDecl

func DeleteDecl(tokFile *token.File, curDecl inspector.Cursor) []Edit

DeleteDecl returns edits to delete the ast.Decl identified by curDecl.

TODO(adonovan): add test suite.

func DeleteSpec

func DeleteSpec(tokFile *token.File, curSpec inspector.Cursor) []Edit

DeleteSpec returns edits to delete the {Type,Value}Spec identified by curSpec.

TODO(adonovan): add test suite. Test for consts as well.

func DeleteStmt

func DeleteStmt(file *token.File, curStmt inspector.Cursor) []Edit

DeleteStmt returns the edits to remove the ast.Stmt identified by curStmt if it recognizes the context. It returns nil otherwise. TODO(pjw, adonovan): it should not return nil, it should return an error

DeleteStmt is called with just the AST so it has trouble deciding if a comment is associated with the statement to be deleted. For instance,

for /*A*/ init()/*B*/;/*C/cond()/*D/;/*E*/post() /*F*/ { /*G*/}

comment B and C are indistinguishable, as are D and E. That is, as the AST does not say where the semicolons are, B and C could go either with the init() or the cond(), so cannot be removed safely. The same is true for D, E, and the post(). (And there are other similar cases.) But the other comments can be removed as they are unambiguously associated with the statement being deleted. In particular, it removes whole lines like

stmt // comment

func DeleteUnusedVars

func DeleteUnusedVars(index *typeindex.Index, info *types.Info, tokFile *token.File, curDelend inspector.Cursor) []Edit

DeleteUnusedVars computes the edits required to delete the declarations of any local variables whose last uses are in the curDelend subtree, which is about to be deleted.

func DeleteVar

func DeleteVar(tokFile *token.File, info *types.Info, curId inspector.Cursor) []Edit

DeleteVar returns edits to delete the declaration of a variable or constant whose defining identifier is curId.

It handles variants including: - GenDecl > ValueSpec versus AssignStmt; - RHS expression has effects, or not; - entire statement/declaration may be eliminated; and removes associated comments.

If it cannot make the necessary edits, such as for a function parameter or result, it returns nil.