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.
)
FileSymPrefix is the linker symbol prefix that used to be used for linker pseudo-symbols representing file names.
const FileSymPrefix = "gofile.."
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.
type Pos struct {
// contains filtered or unexported fields
}
NoPos is a valid unknown position.
var NoPos Pos
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 (p Pos) AbsFilename() string
AbsFilename() returns the absolute filename recorded with the position's base.
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 (p Pos) Base() *PosBase
Base returns the position base.
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 (x Pos) Col() uint
func (p Pos) FileIndex() int
FileIndex returns the file index of the position's base's absolute filename within the PosTable that it was registered.
func (p Pos) Filename() string
Filename returns the name of the actual file containing this position.
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 (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 (x Pos) IsStmt() uint
func (x Pos) Line() uint
func (p Pos) LineNumber() string
func (p Pos) LineNumberHTML() string
func (p Pos) RelCol() uint
RelCol returns the column number relative to the position's base.
func (p Pos) RelFilename() string
RelFilename returns the filename recorded with the position's base.
func (p Pos) RelLine() uint
RelLine returns the line number relative to the position's base.
func (x Pos) SameLine(y lico) bool
func (p *Pos) SetBase(base *PosBase)
SetBase sets the position base.
func (p Pos) String() string
func (p Pos) WriteTo(w io.Writer, showCol, showOrig bool)
WriteTo a position to w, formatted as Format does.
func (x Pos) Xlogue() PosXlogue
A PosBase encodes a filename and base position. Typically, each file and line directive introduce a PosBase.
type PosBase struct {
// contains filtered or unexported fields
}
func NewFileBase(filename, absFilename string) *PosBase
NewFileBase returns a new *PosBase for a file with the given (relative and absolute) filenames.
func NewInliningBase(orig *PosBase, inlTreeIndex int) *PosBase
NewInliningBase returns a copy of the orig PosBase with the given inlining index. If orig == nil, NewInliningBase panics.
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 (b *PosBase) AbsFilename() string
AbsFilename returns the absolute filename recorded with the base. If b == nil, the result is the empty string.
func (b *PosBase) Col() uint
Col returns the column number recorded with the base. If b == nil, the result is 0.
func (b *PosBase) FileIndex() int
FileIndex returns the index of the base's absolute filename within its PosTable's FileTable. It panics if it hasn't been registered with a PosTable. If b == nil, the result is -1.
func (b *PosBase) Filename() string
Filename returns the filename recorded with the base. If b == nil, the result is the empty string.
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 (b *PosBase) Line() uint
Line returns the line number recorded with the base. If b == nil, the result is 0.
func (b *PosBase) Pos() *Pos
Pos returns the position at which base is located. If b == nil, the result is the zero position.
A PosTable tracks Pos -> XPos conversions and vice versa. Its zero value is a ready-to-use PosTable.
type PosTable struct {
// contains filtered or unexported fields
}
func (t *PosTable) FileTable() []string
FileTable returns a slice of all files used to build this package.
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 (t *PosTable) XPos(pos Pos) XPos
XPos returns the corresponding XPos for the given pos, adding pos to t if necessary.
type PosXlogue uint
const (
PosDefaultLogue PosXlogue = iota
PosPrologueEnd
PosEpilogueBegin
)
XPos is a more compact representation of Pos.
type XPos struct {
// contains filtered or unexported fields
}
NoXPos is a valid unknown position.
var NoXPos XPos
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 (p XPos) AtColumn1() XPos
AtColumn1 returns the same location but shifted to column 1.
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 (x XPos) Col() uint
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 (p XPos) IsKnown() bool
IsKnown reports whether the position p is known. XPos.IsKnown() matches Pos.IsKnown() for corresponding positions.
func (x XPos) IsStmt() uint
func (x XPos) Line() uint
func (p XPos) LineNumber() string
LineNumber returns a string for the line number, "?" if it is not known.
func (p XPos) LineNumberHTML() string
func (p XPos) SameFile(q XPos) bool
SameFile reports whether p and q are positions in the same file.
func (p XPos) SameFileAndLine(q XPos) bool
SameFileAndLine reports whether p and q are positions on the same line in the same file.
func (x XPos) SameLine(y lico) bool
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 (p XPos) WithDefaultStmt() XPos
WithDefaultStmt returns the same location with undetermined is_stmt
func (p XPos) WithIsStmt() XPos
WithIsStmt returns the same location to be marked with DWARF is_stmt=1
func (p XPos) WithNotStmt() XPos
WithNotStmt returns the same location to be marked with DWARF is_stmt=0
func (p XPos) WithXlogue(x PosXlogue) XPos
WithXlogue returns the same location but marked with DWARF function prologue/epilogue
func (x XPos) Xlogue() PosXlogue