

**********************
Lua function reference
**********************

This section covers functions provided by the debugger module, grouped
by family for easy reference.

.. index:: lua; execution control

Execution
=========

db:stepInstruction()
--------------------

Steps once at the instruction level.

The result indicates only if the target was notified to start. An error
result means the target is not in a state to start.

To monitor progress and result of execution, you need to listen to
notifications.

.. index:: lua; breakpoints

Breakpoint
==========


db:breakDelete(number(s))
-------------------------

Removes one or more breakpoints.

The argument is the breakpoint number(s) to remove (an integer or array
of integers).


db:breakInsert(location, &callBack)
-----------------------------------

Inserts a new breakpoint.

The first argument, a Lua table, may contain breakpoint attributes:

.. table:: Breakpoint attributes
 :widths: 1 1 3
 :column-dividers: none single none


 +------------+---------+---------------------------------------+
 | field      | type    | description                           |
 +============+=========+=======================================+
 | temporary  | boolean | set a temporary (one-time) breakpoint |
 +------------+---------+---------------------------------------+
 | hardware   | boolean | Use a hardware breakpoint.            |
 +------------+---------+---------------------------------------+
 | pending    | boolean | Allow pending breakpoint.             |
 +------------+---------+---------------------------------------+
 | disabled   | boolean | Start with the breakpoint disabled.   |
 +------------+---------+---------------------------------------+
 | tracePoint | boolean | This is a tracepoint.                 |
 +------------+---------+---------------------------------------+
 | condition  | expr    | Set a conditional expression.         |
 +------------+---------+---------------------------------------+
 | ignore     | integer | Set initial ignore count.             |
 +------------+---------+---------------------------------------+
 | thread     | integer | Breakpoint is valid for a given       |
 |            |         | thread.                               |
 +------------+---------+---------------------------------------+


The second argument describes the breakpoint's location, which can be:

.. table:: Breakpoint location
 :widths: 1 1 2
 :column-dividers: none single none

 +---------------+--------+---------------------------------+
 | kind          | type   |                                 |
 +===============+========+=================================+
 | address       | table  | an address table                |
 +---------------+--------+---------------------------------+
 | file and line | table  | { file : string, line : integer |
 +---------------+--------+---------------------------------+
 | function      | string | function name or symbol         |
 +---------------+--------+---------------------------------+


The third if present should be a Lua function. This function will be
called as followed when the breakpoint is hit:

   cont = callBack(object, breakpointNumber)


The `callBack`'s first argument is the object table used during breakpoint
creation; the second is the breakpoint number. If `callBack` returns
boolean `false`, the breakpoint is not taken, and execution resumes
silently, without user interface feedback.

The callback occurs in the execution thread and blocks execution. If
you intend to continue, return as quickly as possible.

If execution stops, you can process it within the callback or detect
the stop via notifications. Be aware that processing in the callback
will prevent user feedback until it returns.
