ek9_debug_control
Continues, pauses, steps or sets breakpoints in the current debug session; answers its new runState, sequence and stops.
When to use it
'Run on', 'pause' or 'step' the current debug session is one call: {action:'continue'} (also starts a debuggee waiting at its start), {action:'pause'}, {action:'stepOver'}, or {action:'setBreakpoints', file, lines}. Stop only when i == 6, on the 3rd hit, or print and run on: {action:'setBreakpoints', file, breakpoints:[{line, condition, hitCondition, logMessage}]}. Stop when a value changes: {action:'setDataBreakpoint', path}. Feed a program reading stdin: {action:'sendInput', text}, then {action:'endInput'} (Ctrl-D). Run on to a line: {action:'runTo', file, line}. A crash stops where it is thrown (uncaught, the default); {action:'setExceptionBreakpoints', stopOn:'all'|'none'}.
When not to use it
- Starting a session - use
ek9_debug_session{action:'launch'}. - Running to a condition while collecting values - use
ek9_debug_observe.
Details
threadId picks the stopped thread to act on (default: the most recent stop). pause stops every thread running EK9 code where it is, each with a stop of its own (the main thread is the default after it); a thread already stopped keeps its stop; it ends an observation in progress. setBreakpoints replaces that file's breakpoints (removedBreakpoints names any it took away); a line still set keeps its id. Each of 'breakpoints' may have a condition (the typed condition ek9_debug_observe takes: comparison, setCheck, all, any), judged by field at each hit - never by running the program; a hitCondition {op:'==' | '>=' | '%', count} counting the hits where the condition held; a logMessage, printed with {path} replaced, which never stops. A condition that cannot be judged stops and says why. setDataBreakpoint watches the OBJECT the path reads in the stopped frame (frameId, default the top frame) through any variable, stopping once just after each change; a variable later pointed at another object is not followed, and every write to that field type slows while it is set. A step waits up to about 2 s for its landing stop; if the step runs on past that, wait with ek9_debug_session.
Arguments
| Argument | Type | Required | What it is |
|---|---|---|---|
action | string: continue | pause | stepOver | stepInto | stepOut | setBreakpoints | setDataBreakpoint | clearDataBreakpoint | sendInput | endInput | runTo | setExceptionBreakpoints | yes | what to do. |
breakpoints | array of object | setBreakpoints: breakpoints that say when they stop, with lines: {line, condition?, hitCondition?: {op, count}, logMessage?}. | |
file | string | setBreakpoints: the .ek9 file - its path from projectDir, or its name when unique. | |
frameId | integer | setDataBreakpoint: the frame the path is read in (default: the top frame). | |
id | integer | clearDataBreakpoint: the data breakpoint's id. | |
line | integer | runTo: the line to run on to (with file). | |
lines | array of integer | setBreakpoints: every line to break on in that file (empty clears them). | |
path | string | setDataBreakpoint: the value to watch, read in the stopped frame: total, rex, names. | |
stopOn | string: none | uncaught | all | setExceptionBreakpoints: stop on an EK9 Exception or Panic where it is thrown - only when nothing in the program catches it (the launch default), every one, or none. | |
text | string | sendInput: what the program reads from stdin; a line ends with \n, added when missing. | |
threadId | integer | the stopped thread to act on (default: the most recent stop). |