APX Virtual Machine v1
======================

APX virtual machine currently implemented in py-apx. Note that qt-apx implements an even earlier version that was never documented. (Implementation needs to be updated).

Instructions
------------

+---------------+-----------------+--------+----------------------------------------+--------------------------+
| Opcode Number | Opcode Name     |  Size  | Opcode arguments (additional bytes)    | Description              |
+===============+=================+========+========================================+==========================+
| 0             |    NOP          |   1    |                                        | No operation             |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
| 1             | PACK_PROG_HDR   |   5    | 1. progLenType0 (LSB)                  | pack program header      |
|               |                 |        | 2. progLenType1                        |                          |
|               |                 |        | 3. progLenType2                        |                          |
|               |                 |        | 4. progLenType3 (MSB)                  |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
| 2             | UNPACK_PROG_HDR |   5    | 1. progLenType0 (LSB)                  | pack program header      |
|               |                 |        | 2. progLenType1                        |                          |
|               |                 |        | 3. progLenType2                        |                          |
|               |                 |        | 4. progLenType3 (MSB)                  |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  3            | PACK_U8         |   1    |                                        | pack single uint8        |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  4            | PACK_U16        |   1    |                                        | pack single uint16       |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  5            | PACK_U32        |   1    |                                        | pack single uint32       |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  6            | PACK_S8         |   1    |                                        | pack single sint8        |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  7            | PACK_S16        |   1    |                                        | pack single sint16       |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  8            | PACK_S32        |   1    |                                        | pack single sint32       |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  9            | PACK_STR        |   3    | 1. LengthByte0(LSB)                    | pack string              |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  10           | PACK_U8AR       |   3    | 1. LengthByte0(LSB)                    | pack uint8 array         |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  11           | PACK_U16AR      |   3    | 1. LengthByte0(LSB)                    | pack uint16 array        |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  12           | PACK_U32AR      |   3    | 1. LengthByte0(LSB)                    | pack uint32 array        |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  13           | PACK_S8AR       |   3    | 1. LengthByte0(LSB)                    | pack uint8 array         |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  14           | PACK_S16AR      |   3    | 1. LengthByte0(LSB)                    | pack uint16 array        |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  15           | PACK_S32AR      |   3    | 1. LengthByte0(LSB)                    | pack uint32 array        |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  16           | UNPACK_U8       |   1    |                                        | unpack single uint8      |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  17           | UNPACK_U16      |   1    |                                        | unpack single uint16     |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  18           | UNPACK_U32      |   1    |                                        | unpack single uint32     |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  19           | UNPACK_S8       |   1    |                                        | unpack single sint8      |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  20           | UNPACK_S16      |   1    |                                        | unpack single sint16     |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  21           | UNPACK_S32      |   1    |                                        | unpack single sint32     |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  22           | UNPPACK_STR     |   3    | 1. LengthByte0(LSB)                    | unpack string            |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  23           | UNPACK_U8AR     |   3    | 1. LengthByte0(LSB)                    | unpack uint8 array       |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  24           | UNPACK_U16AR    |   3    | 1. LengthByte0(LSB)                    | unpack uint16 array      |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  25           | UNPACK_U32AR    |   3    | 1. LengthByte0(LSB)                    | unpack uint32 array      |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  26           | UNPACK_S8AR     |   3    | 1. LengthByte0(LSB)                    | unpack sint8 array       |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  27           | UNPACK_S16AR    |   3    | 1. LengthByte0(LSB)                    | unpack sint16 array      |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  28           | UNPACK_S32AR    |   3    | 1. LengthByte0(LSB)                    | unpack sint32 array      |
|               |                 |        | 2. LengthByte1(MSB)                    |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  29           | RECORD_ENTER    |   1    |                                        | record inside of record  |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  30           | RECORD_SELECT   |  VAR   | null-terminated utf-8 string           | name of record element   |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  31           | RECORD_LEAVE    |   1    |                                        |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  32           | ARRAY_ENTER     |   1    |                                        | Used for array of        |
|               |                 |        |                                        | records                  |
+---------------+-----------------+--------+----------------------------------------+--------------------------+
|  33           | ARRAY_LEAVE     |   1    |                                        |                          |
+---------------+-----------------+--------+----------------------------------------+--------------------------+

APX Variants
------------

Variants are variables that can store values of different types. They are supported in one way or another in most programming languages.

**Types of variants:**

- Scalars (integers, strings)
- Lists (list of variants)
- Maps (key-value map to variants)

Variant types are identified internally using integers according to the following table:

+-------+---------------+
| Value |     Name      |
+=======+===============+
| -1    | VTYPE_INVALID |
+-------+---------------+
| 0     | VTYPE_SCALAR  |
+-------+---------------+
| 1     | VTYPE_LIST    |
+-------+---------------+
| 2     | VTYPE_MAP     |
+-------+---------------+

Variant Language Mapping
~~~~~~~~~~~~~~~~~~~~~~~~

Each APX implementation maps the APX variant according to what is available to the language.

+-----------------------------------------------------------------+--------------+--------------+----------------------+
| Programming Language                                            | VTYPE_SCALAR | VTYPE_LIST   | VTYPE_MAP            |
+=================================================================+==============+==============+======================+
| C (with `dtl_type <https://github.com/cogu/dtl_type>`_ library) | dtl_sv_t     | dtl_av_t     | dtl_hv_t             |
+-----------------------------------------------------------------+--------------+--------------+----------------------+
| C++ (with Qt variants)                                          | QVariant     | QVariantList | QVariantMap          |  
+-----------------------------------------------------------------+--------------+--------------+----------------------+
| Python                                                          | (int, str)   | list         | dict                 |
+-----------------------------------------------------------------+--------------+--------------+----------------------+
| Visual Basic (Excel)                                            | Variant      | Variant      | Scripting.Dictionary |
+-----------------------------------------------------------------+--------------+--------------+----------------------+