Documentation
¶
Overview ¶
Package debugger is the core of Kukel's debuggers (TODO.md Q60, Q77): breakpoints, stepping, the stop at an exception nothing catches, and reading and changing the program's values. Its front ends are kukel debug (commands on a terminal) and kukel dap (the Debug Adapter Protocol, for editors).
The program runs a copy of its code with a BREAK at the start of every line (bytecode.Debuggable); the VM calls Session.Hook there, and Session.UncaughtHook where an exception nothing catches is thrown. Where the session decides to stop, it calls its Front, on the program's goroutine: the program waits until Stopped returns. Only the main interpreter stops; workers run on.
Index ¶
- func Assign(m *vm.VM, i int, name string, v value.Value) bool
- func Check(src string) error
- func CheckHit(cond string) error
- func Eval(m *vm.VM, i int, src string) (value.Value, error)
- func Interpolate(m *vm.VM, frame int, msg string) string
- func Lookup(m *vm.VM, i int, name string) (value.Value, bool)
- func SameFile(file, name string) bool
- func Show(v value.Value) string
- type Breakpoint
- type Front
- type Session
- func (s *Session) Attach(m *vm.VM)
- func (s *Session) Breaks() []Breakpoint
- func (s *Session) Clear(drop func(b *Breakpoint) bool)
- func (s *Session) CodeLine(file string, line int) (string, int, error)
- func (s *Session) Continue()
- func (s *Session) Finish(depth int)
- func (s *Session) Function(name string) *bytecode.Function
- func (s *Session) Hook(m *vm.VM) error
- func (s *Session) Next(depth int)
- func (s *Session) Pause()
- func (s *Session) Paused() bool
- func (s *Session) SetBreak(b Breakpoint) (bp *Breakpoint, note string, err error)
- func (s *Session) SetUncaught(stop bool)
- func (s *Session) Step()
- func (s *Session) UncaughtHook(m *vm.VM, re *vm.RuntimeError) error
- type Sources
- type Stop
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Assign ¶
Assign gives the variable name, as Lookup finds it in frame i, the value v: a variable of the frame, a data member of this, a static data member, a global variable. It reports whether there is one that can change.
func Check ¶ added in v0.31.0
Check reports what keeps Eval from evaluating src anywhere (it does not parse, or it has a call, an assignment, ...), or nil: for the condition of a breakpoint, when it is set.
func Eval ¶
Eval evaluates an expression as the function of frame i sees its names: literals, names (Lookup), the operators, ?:, indexing and members, vector and map literals. Nothing it does changes the program: calls, assignments, ++, new and function literals are refused.
func Interpolate ¶
Interpolate gives msg with each {expression} in it replaced by its value (as print shows it), or the error; {{ and }} are a { and a }.
func Lookup ¶
Lookup finds a name as the function of frame i sees it: this, a variable, a data member of this, a static data member of its class, a global of its module, a global; or a qualified name: C::x (a static data member, of the module's class C first) or a module's global (util::count).
func SameFile ¶
SameFile tells whether the file of a function is the one a breakpoint names: the same path, or the same name.
Types ¶
type Breakpoint ¶
type Breakpoint struct {
ID int
File string // the file of the function whose line it is
Line int
Func string
Cond, Hit, Log string
// contains filtered or unexported fields
}
Breakpoint stops the program at a line of a file. A function breakpoint (Func names the function) stops where a call of it starts, at its first line, and not where a loop on that line comes back to it. With Cond, it stops only when the condition is true there; with Hit, only when the count of its hits so far meets it ("3": the 3rd time, ">= 3", "% 2", ...); with Log, it shows the message instead of stopping, with {expression}s in it replaced by their values.
type Front ¶
type Front interface {
// Stopped is called when the program stops (on the program's
// goroutine); the program goes on when it returns: as one of Continue,
// Step, Next and Finish said, or ended by the error it returns.
Stopped(m *vm.VM, s Stop) error
// Log shows the message of a logpoint.
Log(msg string)
}
Front is what a debugger shows the user and asks.
type Session ¶
Session is the state of a debugger.
func New ¶
New starts a session of prog (made by bytecode.Debuggable); with stopOnEntry it stops at the first line that runs.
func (*Session) Breaks ¶
func (s *Session) Breaks() []Breakpoint
Breaks gives the breakpoints, in the order they were set.
func (*Session) Clear ¶
func (s *Session) Clear(drop func(b *Breakpoint) bool)
Clear removes the breakpoints for which drop is true.
func (*Session) CodeLine ¶
CodeLine gives the first line with code at or after line in file, and the file's name as the program has it.
func (*Session) Continue ¶
func (s *Session) Continue()
Continue, Step, Next and Finish say how the program goes on after a stop, at the frame depth of the stop (len(m.Frames())).
func (*Session) Function ¶
Function finds a function by its name ("main", "Shape::area", "util::f").
func (*Session) Hook ¶
Hook runs at the start of every line (VM.Debug): it stops where the mode, a pause or a breakpoint says.
func (*Session) SetBreak ¶
func (s *Session) SetBreak(b Breakpoint) (bp *Breakpoint, note string, err error)
SetBreak sets a breakpoint at a line of a file (the first line with code at or after it: the breakpoint's Line), or with a function's name at its first line. A note says when the line moved. A condition must be one Eval can evaluate (Check), a hit count one CheckHit takes.
func (*Session) SetUncaught ¶
SetUncaught says whether the program stops where an exception nothing catches is thrown (it does when the session starts); from any goroutine.
func (*Session) UncaughtHook ¶
UncaughtHook stops where an exception is thrown that nothing catches (VM.DebugUncaught), unless SetUncaught(false): the frames can be looked at; the program ends when the front end lets it go on.
Source Files