Jargon Implementation Details
Arrays
An array is a pointer to the following structure:
| Name | Type | Description |
|---|---|---|
| len | unsigned int | The length of the array. |
| data | structure | The elements of the array. |
Arrays with multiple dimensions can be supported either by using arrays of arrays or by calculating the offsets within the program.
Handlers
A handler is a function which is invoked when a "handled" message is sent to a module or object. A message can be handled by a module or object when a handler within the module has the same name as the message and takes the same arguments. If a module does not have a handler capable of handling a message, the message is passed to the parent module (if any). If there is no parent module, the program will abort.
Message Dispatch
When a message is passed to a module or object, the following sequence of events takes place:
- The object or module's handler list is located.
- A string comparison is done for each of the handlers until a match is found. If no matches are found, the module's parent is located and the process repeats.
- If a handler is found for the message, it is invoked. Otherwise a default handler is invoked that aborts the program.
Modules
A module is a static object containing handlers and data. Modules may be dynamically instanciated to form objects. The structure for a module is:
Module Structure| Name | Type | Description |
|---|---|---|
| name | pointer | A pointer to the zero terminated name of the module. |
| parent | pointer | A pointer to the parent of the module or NULL. |
| handlers | pointer | A pointer to a list of handlers in the module. |
| handler | pointer | A pointer to the function to perform handler execution. |
| data | structure | The static data for the module. |
A module must have at least one handler otherwise the module is pointless. The handlers are stored in an array. Each element has the following structure:
Handler List Structure| Name | Type | Description |
|---|---|---|
| name | pointer | A pointer to the zero terminated name of the handler. This includes the encoded arguments after a period character. See the Argument Encoding table. |
| code | pointer | A pointer to the entry point of the handler. |
In order to distinguish between handlers that have the same name but take different arguments, a period character is appended to the handler name and then the argument types (if any), encoded using the following table, are appended. If an argument is an array, a decimal number is appended after the argument type to indicate the level of indirection.
Argument Encoding| Encoding | Type |
|---|---|
| B | bool |
| C | char |
| I | int |
| F | float |
| S | string |
| O | object |
Objects
An "object" is an instance of a module. An object points to an object data structure:
Object Structure| Name | Type | Description |
|---|---|---|
| module | pointer | A pointer to the static module data. |
| data | structure | The data associated with the object. |
Objects are allocated and instanciated using the "new" keyword. Objects are finalized and deallocated using the "delete" keyword.
Strings
A "string" object is a data structure having the following attributes:
String Structure| Name | Type | Description |
|---|---|---|
| max | unsigned int | The maximum length of the string before reallocation will be required. |
| count | unsigned int | Reference count. |
| str | pointer | A pointer to the zero terminated string of characters. Note that the zero is not considered for len and max. |
When a string object is first created, it is allocated STRING_BLOCK_SIZE characters. The len field is set to 0, and the first element of str is also set to 0. If the string is created with an initial value, max and len are both set to the length of the string. When a string grows beyond the max field, it is reallocated in increments of STRING_BLOCK_SIZE. If a string length falls below max - STRING_BLOCK_SIZE, it is reallocated to the length of the string.
When passed as message arguments strings are passed by-reference.