Package src

import "cmd/internal/src"
Overview
Index

Overview ▾

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) FileIndex() int
    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) WriteTo(w io.Writer, showCol, showOrig bool)
    func (x Pos) Xlogue() PosXlogue
type PosBase
    func NewFileBase(filename, absFilename string) *PosBase
    func NewInliningBase(orig *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) FileIndex() int
    func (b *PosBase) Filename() string
    func (b *PosBase) InliningIndex() int
    func (b *PosBase) Line() uint
    func (b *PosBase) Pos() *Pos
type PosTable
    func (t *PosTable) FileTable() []string
    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

Package files

pos.go xpos.go

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.
)

FileSymPrefix is the linker symbol prefix that used to be used for linker pseudo-symbols representing file names.

const FileSymPrefix = "gofile.."

type Pos

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

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) FileIndex

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 (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) 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

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

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(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

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) FileIndex

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 (*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.

type PosTable

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 (*PosTable) FileTable

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

FileTable returns a slice of all files used to build this package.

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

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 (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