locspec

Documentation

Overview

Package locspec implements code to parse a string into a specific location specification.

Location spec examples:

locStr ::= <filename>:<line> | <function>[:<line>] | /<regex>/ | (+|-)<offset> | <line> | *<address>

* <filename> can be the full path of a file or just a suffix
* <function> ::= <package>.<receiver type>.<name> | <package>.(*<receiver type>).<name> | <receiver type>.<name> | <package>.<name> | (*<receiver type>).<name> | <name>
  <function> must be unambiguous
* /<regex>/ will return a location for each function matched by regex
* +<offset> returns a location for the line that is <offset> lines after the current line
* -<offset> returns a location for the line that is <offset> lines before the current line
* <line> returns a location for a line in the current file
* *<address> returns the location corresponding to the specified address

Index

• func SubstitutePath(path string, rules [][2]string) string
• type AddrLocationSpec
  • func (loc *AddrLocationSpec) Find(t *proc.Target, _ []string, scope *proc.EvalScope, locStr string, ...) ([]api.Location, string, error)
• type AmbiguousLocationError
  • func (ale AmbiguousLocationError) Error() string
• type FuncLocationSpec
  • func (spec *FuncLocationSpec) Match(sym *proc.Function, packageMap map[string][]string) bool
• type LineLocationSpec
  • func (loc *LineLocationSpec) Find(t *proc.Target, _ []string, scope *proc.EvalScope, _ string, ...) ([]api.Location, string, error)
• type LocationSpec
  • func Parse(locStr string) (LocationSpec, error)
• type NormalLocationSpec
  • func (loc *NormalLocationSpec) FileMatch(path string) bool
  • func (loc *NormalLocationSpec) Find(t *proc.Target, processArgs []string, scope *proc.EvalScope, locStr string, ...) ([]api.Location, string, error)
• type OffsetLocationSpec
  • func (loc *OffsetLocationSpec) Find(t *proc.Target, _ []string, scope *proc.EvalScope, _ string, ...) ([]api.Location, string, error)
• type RegexLocationSpec
  • func (loc *RegexLocationSpec) Find(t *proc.Target, _ []string, scope *proc.EvalScope, locStr string, ...) ([]api.Location, string, error)

Functions

func SubstitutePath

func SubstitutePath(path string, rules [][2]string) string

SubstitutePath applies the specified path substitution rules to path.

Types

type AddrLocationSpec

type AddrLocationSpec struct {
	AddrExpr string
}

AddrLocationSpec represents an address when used as a location spec.

func (*AddrLocationSpec) Find

func (loc *AddrLocationSpec) Find(t *proc.Target, _ []string, scope *proc.EvalScope, locStr string, includeNonExecutableLines bool, _ [][2]string) ([]api.Location, string, error)

Find returns the locations specified via the address location spec.

type AmbiguousLocationError

type AmbiguousLocationError struct {
	Location           string
	CandidatesString   []string
	CandidatesLocation []api.Location
}

AmbiguousLocationError is returned when the location spec should only return one location but returns multiple instead.

func (AmbiguousLocationError) Error

func (ale AmbiguousLocationError) Error() string

type FuncLocationSpec

type FuncLocationSpec struct {
	PackageName           string
	AbsolutePackage       bool
	ReceiverName          string
	PackageOrReceiverName string
	BaseName              string
}

FuncLocationSpec represents a function in the target program.

func (*FuncLocationSpec) Match

func (spec *FuncLocationSpec) Match(sym *proc.Function, packageMap map[string][]string) bool

Match will return whether the provided function matches the location spec.

type LineLocationSpec

type LineLocationSpec struct {
	Line int
}

LineLocationSpec represents a line number in the current file.

func (*LineLocationSpec) Find

func (loc *LineLocationSpec) Find(t *proc.Target, _ []string, scope *proc.EvalScope, _ string, includeNonExecutableLines bool, _ [][2]string) ([]api.Location, string, error)

Find will return the location at the given line in the current file.

type LocationSpec

type LocationSpec interface {
	// Find returns all locations that match the location spec.
	Find(t *proc.Target, processArgs []string, scope *proc.EvalScope, locStr string, includeNonExecutableLines bool, substitutePathRules [][2]string) ([]api.Location, string, error)
}

LocationSpec is an interface that represents a parsed location spec string.

func Parse

func Parse(locStr string) (LocationSpec, error)

Parse will turn locStr into a parsed LocationSpec.

type NormalLocationSpec

type NormalLocationSpec struct {
	Base       string
	FuncBase   *FuncLocationSpec
	LineOffset int
}

NormalLocationSpec represents a basic location spec. This can be a file:line or func:line.

func (*NormalLocationSpec) FileMatch

func (loc *NormalLocationSpec) FileMatch(path string) bool

FileMatch is true if the path matches the location spec.

func (*NormalLocationSpec) Find

func (loc *NormalLocationSpec) Find(t *proc.Target, processArgs []string, scope *proc.EvalScope, locStr string, includeNonExecutableLines bool, substitutePathRules [][2]string) ([]api.Location, string, error)

Find will return a list of locations that match the given location spec. This matches each other location spec that does not already have its own spec implemented (such as regex, or addr).

type OffsetLocationSpec

type OffsetLocationSpec struct {
	Offset int
}

OffsetLocationSpec represents a location spec that is an offset of the current location (file:line).

func (*OffsetLocationSpec) Find

func (loc *OffsetLocationSpec) Find(t *proc.Target, _ []string, scope *proc.EvalScope, _ string, includeNonExecutableLines bool, _ [][2]string) ([]api.Location, string, error)

Find returns the location after adding the offset amount to the current line number.

type RegexLocationSpec

type RegexLocationSpec struct {
	FuncRegex string
}

RegexLocationSpec represents a regular expression location expression such as /^myfunc$/.

func (*RegexLocationSpec) Find

func (loc *RegexLocationSpec) Find(t *proc.Target, _ []string, scope *proc.EvalScope, locStr string, includeNonExecutableLines bool, _ [][2]string) ([]api.Location, string, error)

Find will search all functions in the target program and filter them via the regex location spec. Only functions matching the regex will be returned.