

************************
Lua data types reference
************************

This section describes the data structures used. Complex types (beyond
booleans, numbers, or strings) are represented by tables.


.. index:: lua; address type

Address
=======

The debugger uses internal addresses, composed of a numeric value, memory
type, and optional bank number. In Lua, addresses are represented by a
table with these fields:

.. table:: Address type
 :widths: 1 1 3
 :column-dividers: none single none

 +-----------+---------+-----------------------------------------------------+
 | field     | type    | description                                         |
 +===========+=========+=====================================================+
 | formatted | string  | The complete print value of the address location.   |
 +-----------+---------+-----------------------------------------------------+
 | address   | integer | The raw address bits of the location.               |
 +-----------+---------+-----------------------------------------------------+
 | memory    | string  | The kind of the memory the address points to,       |
 |           |         | can typically be "code" or "data" (string).         |
 +-----------+---------+-----------------------------------------------------+
 | bank      | integer | The bank number, or *nil* if this address           |
 |           |         | location does not have any bank associated with it. |
 +-----------+---------+-----------------------------------------------------+

The ``formatted`` field is set when the value is returned to Lua. If
you provide an address as an argument to a function call in the API,
you do not need to provide a ``formatted`` field.


.. index:: lua; adapted MI functions

Adapted MI functions
====================

Many Lua functions are adapted from *machine interface* (MI) commands,
used for communication between a debugger front end (like VS Code) and the
debugger.

Functions are available in the ``db`` table. The Lua interface translates
arguments for these functions and passes them to the debugger command handler.

Results are passed back and translated to Lua. As the underlying
mechanism is a command protocol, the result table is a bit more
elaborate than what might be expected.

A top-level result has the following fields:

 +-----------+---------+------------------------------------------------------+
 | field     | type    | description                                          |
 +===========+=========+======================================================+
 | class     | string  | The result class (e.g., ``done`` for success,        |
 |           |         | ``error`` for failures). A complete list is below.   |
 +-----------+---------+------------------------------------------------------+
 | value     | integer | The result, which depends on the function called.    |
 +-----------+---------+------------------------------------------------------+
 | type      | string  | The reply type. For function calls, this is          |
 |           |         | ``result``.                                          |
 +-----------+---------+------------------------------------------------------+
