src

Documentation

Index

• Constants
• type Pos
  • func MakePos(base *PosBase, line, col uint) Pos
  • func (p Pos) AbsFilename() string
  • func (p Pos) After(q Pos) bool
  • func (p Pos) Base() *PosBase
  • func (p Pos) Before(q Pos) bool
  • func (x Pos) Col() uint
  • func (p Pos) Filename() string
  • func (p Pos) Format(showCol, showOrig bool) string
  • func (p Pos) IsKnown() bool
  • func (x Pos) IsStmt() uint
  • func (x Pos) Line() uint
  • func (p Pos) LineNumber() string
  • func (p Pos) LineNumberHTML() string
  • func (p Pos) RelCol() uint
  • func (p Pos) RelFilename() string
  • func (p Pos) RelLine() uint
  • func (x Pos) SameLine(y lico) bool
  • func (p *Pos) SetBase(base *PosBase)
  • func (p Pos) String() string
  • func (p Pos) SymFilename() string
  • func (p Pos) WriteTo(w io.Writer, showCol, showOrig bool)
  • func (x Pos) Xlogue() PosXlogue
• type PosBase
  • func NewFileBase(filename, absFilename string) *PosBase
  • func NewInliningBase(old *PosBase, inlTreeIndex int) *PosBase
  • func NewLinePragmaBase(pos Pos, filename, absFilename string, line, col uint) *PosBase
  • func (b *PosBase) AbsFilename() string
  • func (b *PosBase) Col() uint
  • func (b *PosBase) Filename() string
  • func (b *PosBase) InliningIndex() int
  • func (b *PosBase) Line() uint
  • func (b *PosBase) Pos() *Pos
  • func (b *PosBase) SymFilename() string
• type PosTable
  • func (t *PosTable) DebugLinesFileTable() []string
  • func (t *PosTable) FileIndex(filename string) int
  • func (t *PosTable) Pos(p XPos) Pos
  • func (t *PosTable) XPos(pos Pos) XPos
• type PosXlogue
• type XPos
  • func (p XPos) After(q XPos) bool
  • func (p XPos) AtColumn1() XPos
  • func (p XPos) Before(q XPos) bool
  • func (x XPos) Col() uint
  • func (p XPos) FileIndex() int32
  • func (p XPos) IsKnown() bool
  • func (x XPos) IsStmt() uint
  • func (x XPos) Line() uint
  • func (p XPos) LineNumber() string
  • func (p XPos) LineNumberHTML() string
  • func (p XPos) SameFile(q XPos) bool
  • func (p XPos) SameFileAndLine(q XPos) bool
  • func (x XPos) SameLine(y lico) bool
  • func (p XPos) WithBogusLine() XPos
  • func (p XPos) WithDefaultStmt() XPos
  • func (p XPos) WithIsStmt() XPos
  • func (p XPos) WithNotStmt() XPos
  • func (p XPos) WithXlogue(x PosXlogue) XPos
  • func (x XPos) Xlogue() PosXlogue

Constants

const (
	// It is expected that the front end or a phase in SSA will usually generate positions tagged with
	// PosDefaultStmt, but note statement boundaries with PosIsStmt.  Simple statements will have a single
	// boundary; for loops with initialization may have one for their entry and one for their back edge
	// (this depends on exactly how the loop is compiled; the intent is to provide a good experience to a
	// user debugging a program; the goal is that a breakpoint set on the loop line fires both on entry
	// and on iteration).  Proper treatment of non-gofmt input with multiple simple statements on a single
	// line is TBD.
	//
	// Optimizing compilation will move instructions around, and some of these will become known-bad as
	// step targets for debugging purposes (examples: register spills and reloads; code generated into
	// the entry block; invariant code hoisted out of loops) but those instructions will still have interesting
	// positions for profiling purposes. To reflect this these positions will be changed to PosNotStmt.
	//
	// When the optimizer removes an instruction marked PosIsStmt; it should attempt to find a nearby
	// instruction with the same line marked PosDefaultStmt to be the new statement boundary.  I.e., the
	// optimizer should make a best-effort to conserve statement boundary positions, and might be enhanced
	// to note when a statement boundary is not conserved.
	//
	// Code cloning, e.g. loop unrolling or loop unswitching, is an exception to the conservation rule
	// because a user running a debugger would expect to see breakpoints active in the copies of the code.
	//
	// In non-optimizing compilation there is still a role for PosNotStmt because of code generation
	// into the entry block.  PosIsStmt statement positions should be conserved.
	//
	// When code generation occurs any remaining default-marked positions are replaced with not-statement
	// positions.
	//
	PosDefaultStmt uint = iota // Default; position is not a statement boundary, but might be if optimization removes the designated statement boundary
	PosIsStmt                  // Position is a statement boundary; if optimization removes the corresponding instruction, it should attempt to find a new instruction to be the boundary.
	PosNotStmt                 // Position should not be a statement boundary, but line should be preserved for profiling and low-level debugging purposes.
)

const FileSymPrefix = "gofile.."

Types

type Pos

type Pos struct {
	// contains filtered or unexported fields
}

A Pos encodes a source position consisting of a (line, column) number pair and a position base. A zero Pos is a ready to use "unknown" position (nil position base and zero line number).

The (line, column) values refer to a position in a file independent of any position base ("absolute" file position).

The position base is used to determine the "relative" position, that is the filename and line number relative to the position base. If the base refers to the current file, there is no difference between absolute and relative positions. If it refers to a //line directive, a relative position is relative to that directive. A position base in turn contains the position at which it was introduced in the current file.

var NoPos Pos

NoPos is a valid unknown position.

func MakePos

func MakePos(base *PosBase, line, col uint) Pos

MakePos creates a new Pos value with the given base, and (file-absolute) line and column.

func (Pos) AbsFilename

func (p Pos) AbsFilename() string

AbsFilename() returns the absolute filename recorded with the position's base.

func (Pos) After

func (p Pos) After(q Pos) bool

After reports whether the position p comes after q in the source. For positions in different files, ordering is by filename.

func (Pos) Base

func (p Pos) Base() *PosBase

Base returns the position base.

func (Pos) Before

func (p Pos) Before(q Pos) bool

Before reports whether the position p comes before q in the source. For positions in different files, ordering is by filename.

func (Pos) Col

func (x Pos) Col() uint

func (Pos) Filename

func (p Pos) Filename() string

Filename returns the name of the actual file containing this position.

func (Pos) Format

func (p Pos) Format(showCol, showOrig bool) string

Format formats a position as "filename:line" or "filename:line:column", controlled by the showCol flag and if the column is known (!= 0). For positions relative to line directives, the original position is shown as well, as in "filename:line[origfile:origline:origcolumn] if showOrig is set.

func (Pos) IsKnown

func (p Pos) IsKnown() bool

IsKnown reports whether the position p is known. A position is known if it either has a non-nil position base, or a non-zero line number.

func (Pos) IsStmt

func (x Pos) IsStmt() uint

func (Pos) Line

func (x Pos) Line() uint

func (Pos) LineNumber

func (p Pos) LineNumber() string

func (Pos) LineNumberHTML

func (p Pos) LineNumberHTML() string

func (Pos) RelCol

func (p Pos) RelCol() uint

RelCol returns the column number relative to the position's base.

func (Pos) RelFilename

func (p Pos) RelFilename() string

RelFilename returns the filename recorded with the position's base.

func (Pos) RelLine

func (p Pos) RelLine() uint

RelLine returns the line number relative to the position's base.

func (Pos) SameLine

func (x Pos) SameLine(y lico) bool

func (*Pos) SetBase

func (p *Pos) SetBase(base *PosBase)

SetBase sets the position base.

func (Pos) String

func (p Pos) String() string

func (Pos) SymFilename

func (p Pos) SymFilename() string

SymFilename() returns the absolute filename recorded with the position's base, prefixed by FileSymPrefix to make it appropriate for use as a linker symbol.

func (Pos) WriteTo

func (p Pos) WriteTo(w io.Writer, showCol, showOrig bool)

WriteTo a position to w, formatted as Format does.

func (Pos) Xlogue

func (x Pos) Xlogue() PosXlogue

type PosBase

type PosBase struct {
	// contains filtered or unexported fields
}

A PosBase encodes a filename and base position. Typically, each file and line directive introduce a PosBase.

func NewFileBase

func NewFileBase(filename, absFilename string) *PosBase

NewFileBase returns a new *PosBase for a file with the given (relative and absolute) filenames.

func NewInliningBase

func NewInliningBase(old *PosBase, inlTreeIndex int) *PosBase

NewInliningBase returns a copy of the old PosBase with the given inlining index. If old == nil, the resulting PosBase has no filename.

func NewLinePragmaBase

func NewLinePragmaBase(pos Pos, filename, absFilename string, line, col uint) *PosBase

NewLinePragmaBase returns a new *PosBase for a line directive of the form

//line filename:line:col
/*line filename:line:col*/

at position pos.

func (*PosBase) AbsFilename

func (b *PosBase) AbsFilename() string

AbsFilename returns the absolute filename recorded with the base. If b == nil, the result is the empty string.

func (*PosBase) Col

func (b *PosBase) Col() uint

Col returns the column number recorded with the base. If b == nil, the result is 0.

func (*PosBase) Filename

func (b *PosBase) Filename() string

Filename returns the filename recorded with the base. If b == nil, the result is the empty string.

func (*PosBase) InliningIndex

func (b *PosBase) InliningIndex() int

InliningIndex returns the index into the global inlining tree recorded with the base. If b == nil or the base has not been inlined, the result is < 0.

func (*PosBase) Line

func (b *PosBase) Line() uint

Line returns the line number recorded with the base. If b == nil, the result is 0.

func (*PosBase) Pos

func (b *PosBase) Pos() *Pos

Pos returns the position at which base is located. If b == nil, the result is the zero position.

func (*PosBase) SymFilename

func (b *PosBase) SymFilename() string

SymFilename returns the absolute filename recorded with the base, prefixed by FileSymPrefix to make it appropriate for use as a linker symbol. If b is nil, SymFilename returns FileSymPrefix + "??".

type PosTable

type PosTable struct {
	// contains filtered or unexported fields
}

A PosTable tracks Pos -> XPos conversions and vice versa. Its zero value is a ready-to-use PosTable.

func (*PosTable) DebugLinesFileTable

func (t *PosTable) DebugLinesFileTable() []string

DebugLinesFiles returns the file table for the debug_lines DWARF section.

func (*PosTable) FileIndex

func (t *PosTable) FileIndex(filename string) int

FileIndex returns the index of the given filename(symbol) in the PosTable, or -1 if not found.

func (*PosTable) Pos

func (t *PosTable) Pos(p XPos) Pos

Pos returns the corresponding Pos for the given p. If p cannot be translated via t, the function panics.

func (*PosTable) XPos

func (t *PosTable) XPos(pos Pos) XPos

XPos returns the corresponding XPos for the given pos, adding pos to t if necessary.

type PosXlogue

type PosXlogue uint

const (
	PosDefaultLogue PosXlogue = iota
	PosPrologueEnd
	PosEpilogueBegin
)

type XPos

type XPos struct {
	// contains filtered or unexported fields
}

XPos is a more compact representation of Pos.

var NoXPos XPos

NoXPos is a valid unknown position.

func (XPos) After

func (p XPos) After(q XPos) bool

After reports whether the position p comes after q in the source. For positions with different bases, ordering is by base index.

func (XPos) AtColumn1

func (p XPos) AtColumn1() XPos

AtColumn1 returns the same location but shifted to column 1.

func (XPos) Before

func (p XPos) Before(q XPos) bool

Before reports whether the position p comes before q in the source. For positions with different bases, ordering is by base index.

func (XPos) Col

func (x XPos) Col() uint

func (XPos) FileIndex

func (p XPos) FileIndex() int32

FileIndex returns a smallish non-negative integer corresponding to the file for this source position. Smallish is relative; it can be thousands large, but not millions.

func (XPos) IsKnown

func (p XPos) IsKnown() bool

IsKnown reports whether the position p is known. XPos.IsKnown() matches Pos.IsKnown() for corresponding positions.

func (XPos) IsStmt

func (x XPos) IsStmt() uint

func (XPos) Line

func (x XPos) Line() uint

func (XPos) LineNumber

func (p XPos) LineNumber() string

LineNumber returns a string for the line number, "?" if it is not known.

func (XPos) LineNumberHTML

func (p XPos) LineNumberHTML() string

func (XPos) SameFile

func (p XPos) SameFile(q XPos) bool

SameFile reports whether p and q are positions in the same file.

func (XPos) SameFileAndLine

func (p XPos) SameFileAndLine(q XPos) bool

SameFileAndLine reports whether p and q are positions on the same line in the same file.

func (XPos) SameLine

func (x XPos) SameLine(y lico) bool

func (XPos) WithBogusLine

func (p XPos) WithBogusLine() XPos

WithBogusLine returns a bogus line that won't match any recorded for the source code. Its use is to disrupt the statements within an infinite loop so that the debugger will not itself loop infinitely waiting for the line number to change. gdb chooses not to display the bogus line; delve shows it with a complaint, but the alternative behavior is to hang.

func (XPos) WithDefaultStmt

func (p XPos) WithDefaultStmt() XPos

WithDefaultStmt returns the same location with undetermined is_stmt

func (XPos) WithIsStmt

func (p XPos) WithIsStmt() XPos

WithIsStmt returns the same location to be marked with DWARF is_stmt=1

func (XPos) WithNotStmt

func (p XPos) WithNotStmt() XPos

WithNotStmt returns the same location to be marked with DWARF is_stmt=0

func (XPos) WithXlogue

func (p XPos) WithXlogue(x PosXlogue) XPos

WithXlogue returns the same location but marked with DWARF function prologue/epilogue

func (XPos) Xlogue

func (x XPos) Xlogue() PosXlogue