...
▽

Package cfg

import "cmd/vendor/golang.org/x/tools/go/cfg"
Overview
Index

Overview ▾

Package cfg constructs a simple control-flow graph (CFG) of the statements and expressions within a single function.

Use cfg.New to construct the CFG for a function body.

The blocks of the CFG contain all the function's non-control statements. The CFG does not contain control statements such as If, Switch, Select, and Branch, but does contain their subexpressions; also, each block records the control statement (Block.Stmt) that gave rise to it and its relationship (Block.Kind) to that statement.

For example, this source code: 

if x := f(); x != nil {
	T()
} else {
	F()
}

produces this CFG: 

1:  x := f()		Body
    x != nil
    succs: 2, 3
2:  T()			IfThen
    succs: 4
3:  F()			IfElse
    succs: 4
4:			IfDone

The CFG does contain Return statements; even implicit returns are materialized (at the position of the function's closing brace).

The CFG does not record conditions associated with conditional branch edges, nor the short-circuit semantics of the && and || operators, nor abnormal control flow caused by panic. If you need this information, use golang.org/x/tools/go/ssa instead.

type Block

A Block represents a basic block: a list of statements and expressions that are always evaluated sequentially.

A block may have 0-2 successors: zero for a return block or a block that calls a function such as panic that never returns; one for a normal (jump) block; and two for a conditional (if) block. 

type Block struct {
    Nodes []ast.Node // statements, expressions, and ValueSpecs
    Succs []*Block   // successor nodes in the graph
    Index int32      // index within CFG.Blocks
    Live  bool       // block is reachable from entry
    Kind  BlockKind  // block kind
    Stmt  ast.Stmt   // statement that gave rise to this block (see BlockKind for details)
    // contains filtered or unexported fields
}

func (*Block) Return 

func (b *Block) Return() (ret *ast.ReturnStmt)

Return returns the return statement at the end of this block if present, nil otherwise.

When control falls off the end of the function, the ReturnStmt is synthetic and its ast.Node.End position may be beyond the end of the file.

func (*Block) String 

func (b *Block) String() string

type BlockKind

A BlockKind identifies the purpose of a block. It also determines the possible types of its Stmt field. 

type BlockKind uint8
const (
    KindInvalid BlockKind = iota // Stmt=nil

    KindUnreachable     // unreachable block after {Branch,Return}Stmt / no-return call ExprStmt
    KindBody            // function body BlockStmt
    KindForBody         // body of ForStmt
    KindForDone         // block after ForStmt
    KindForLoop         // head of ForStmt
    KindForPost         // post condition of ForStmt
    KindIfDone          // block after IfStmt
    KindIfElse          // else block of IfStmt
    KindIfThen          // then block of IfStmt
    KindLabel           // labeled block of BranchStmt (Stmt may be nil for dangling label)
    KindRangeBody       // body of RangeStmt
    KindRangeDone       // block after RangeStmt
    KindRangeLoop       // head of RangeStmt
    KindSelectCaseBody  // body of SelectStmt
    KindSelectDone      // block after SelectStmt
    KindSelectAfterCase // block after a CommClause
    KindSwitchCaseBody  // body of CaseClause
    KindSwitchDone      // block after {Type.}SwitchStmt
    KindSwitchNextCase  // secondary expression of a multi-expression CaseClause
)

func (BlockKind) String 

func (kind BlockKind) String() string

type CFG

A CFG represents the control-flow graph of a single function.

The entry point is Blocks[0]; there may be multiple return blocks. 

type CFG struct {
    Blocks []*Block // block[0] is entry; order otherwise undefined
    // contains filtered or unexported fields
}

func New 

func New(body *ast.BlockStmt, mayReturn func(*ast.CallExpr) bool) *CFG

New returns a new control-flow graph for the specified function body, which must be non-nil.

The CFG builder calls mayReturn to determine whether a given function call may return. For example, calls to panic, os.Exit, and log.Fatal do not return, so the builder can remove infeasible graph edges following such calls. The builder calls mayReturn only for a CallExpr beneath an ExprStmt.

func (*CFG) Dot 

func (g *CFG) Dot(fset *token.FileSet) string

Dot returns the control-flow graph in the [Dot graph description language]. Use a command such as 'dot -Tsvg' to render it in a form viewable in a browser. This method is provided as a debugging aid; the details of the output are unspecified and may change.

[Dot graph description language]: ​​https://en.wikipedia.org/wiki/DOT_(graph_description_language)

func (*CFG) Format 

func (g *CFG) Format(fset *token.FileSet) string

Format formats the control-flow graph for ease of debugging.