dst

The Before and After properties on a node control vertical spacing (new lines or empty lines) around that node. These spaces are rendered before any Start decorations and after any End decorations. Use dst.EmptyLine or dst.NewLine to set these. To force a newline inside a node, add a \n decoration to an attachment point.

call.Decs.Before = dst.EmptyLine
call.Decs.After = dst.EmptyLine

for _, v := range call.Args {
	v := v.(*dst.Ident)
	v.Decs.Before = dst.NewLine
	v.Decs.After = dst.NewLine
}

The standard go/ast package is not designed for source code manipulation. When you rearrange nodes in an ast.File (for example, swapping statements in a function body), comments often end up attached to the wrong lines or lose their relative positioning because they are tracked via byte offsets rather than being properties of the nodes themselves.

dst solves this by attaching decorations (comments, spacing, newlines) directly to the nodes, ensuring that when you move a node, its associated metadata moves with it.

Comments are attached to specific points on a node. You can use the convenience methods Append, Prepend, Replace, Clear, and All on these attachment points. When adding a line comment, include the // or /**/ markers; a newline is automatically rendered for line comments. Common attachment points include Start, End, Fun, Lparen, Rparen, Lbrace, Rbrace, etc.

call := f.Decls[0].(*dst.FuncDecl).Body.List[0].(*dst.ExprStmt).X.(*dst.CallExpr)

call.Decs.Start.Append("// you can add comments at the start...")
call.Decs.Fun.Append("/* ...in the middle... */")
call.Decs.End.Append("// or at the end.")

To automatically manage the import block, use decorator.NewDecoratorWithImports and decorator.NewRestorerWithImports.

When using import management, you can add qualified identifiers by simply adding a *dst.Ident node and setting its Path field to the imported package path. The restorer will automatically wrap it in a *ast.SelectorExpr and update the import block as needed.

// Adding an identifier that triggers an automatic import
b.List = append(b.List, &dst.ExprStmt{
	X: &dst.CallExpr{
		Fun: &dst.Ident{Path: "fmt", Name: "Println"},
		Args: []dst.Expr{
			&dst.BasicLit{Kind: token.STRING, Value: strconv.Quote("Hello")},
		},
	},
})

For simple tasks, use the decorator package's convenience functions. decorator.Parse converts source code into a dst.File, and decorator.Print renders a dst.File back into source code. For more control, use decorator.Decorator to convert from ast to dst and decorator.Restorer to convert back.

code := `package main

func main() {
	println("Hello World!")
}`
f, err := decorator.Parse(code)
if err != nil {
	panic(err)
}

// ... modify f ...

if err := decorator.Print(f); err != nil {
	panic(err)
}

The dst package uses three primary interfaces to categorize nodes in the decorated syntax tree. All nodes implement the Node interface, which provides access to Decorations() (containing Before, After, Start, and End information).

• Expr: Represents expression and type nodes.
• Stmt: Represents statement nodes.
• Decl: Represents declaration nodes.

The Stmt interface represents various Go statements. Common implementations include:

• AssignStmt: Assignment (=) or short variable declaration (:=).
• IfStmt: An if statement with Init, Cond, Body, and Else.
• BlockStmt: A braced list of statements ({ ... }).
• ReturnStmt: A return statement with Results.
• ForStmt: A standard for loop with Init, Cond, Post, and Body.
• RangeStmt: A for range loop.
• ExprStmt: A standalone expression used as a statement.

The Decl interface represents top-level declarations.

• GenDecl: A generic declaration for IMPORT, CONST, TYPE, or VAR. It can represent parenthesized declarations via the Lparen field.
• FuncDecl: A function or method declaration, containing Recv (receiver), Name, Type (signature), and Body.
• BadDecl: A placeholder for declarations with syntax errors.

The Walk mechanism uses a recursive visitor pattern to navigate the tree. The key to controlling the flow is the return value of the Visit method.

• Continue Traversal: Return the visitor itself (e.g., return v). This tells Walk to proceed to the children of the current node.
• Stop Traversal: Return nil. This tells Walk to skip the children of the current node.

This pattern is useful for implementing filters, search algorithms, or transformations where you might want to skip entire subtrees once a certain condition is met.