doc/developer_notes.txt

   1
   2 Engine
   3  - stores the all data associated with a mala instance
   4  - usually one only needs one engine to run mala programs
   5  - stores a StringBucket holding all Strings used.
   6  - the Strings in the StringBucket also store the bound Actions (see Strings)
   7  - each engine has its own independent GC
   8
   9 StringBucket
  10  - efficent lookup for Strings
  11  - acts as cache for Strings which become unused but might be reused soon
  12  - ensures that Strings are uniqe and singleton, same Strings are
  13    guranteed to be identifyable by only one unique address
  14
  15 String
  16  - thin layer above C-strings
  17  - can store optional data, used to store associated Actions as stack
  18
  19 Action
  20  - Descriptor associating a String with a C function and data
  21  - stores extra data (void*) used for the action
  22  - Actions are linked with 1:N parent/childs relationships (childs become attached to parents)
  23    when a parent gets deleted, its childs are automatically deleted with them.
  24  - if no parent is defined then a action shall be the child of "--WORLD"
  25
  26 StringList
  27  - Just a list of strings
  28
  29 Program
  30  - a StringList with state information for program execution
  31  - program pointer
  32  - resulting state of the last program step
  33
  34
  35 Semantics:
  36
  37 a Mala program is just a sequence of words (StringList)
  38 the program pointer is initialized to the leftmost word
  39 if the Programs state is higher than MALA_EFAULT then evaluation is stopped and control is handed back to the calling program
  40 else if the word is not bound to an action it is just set one step rightwards pointing to the next word
  41 else if it is bound to an action it's associated C function is called with the current Program and the data
  42    stored in the Action as parameter.
  43    The function can freely modify the program (usually taking parameters following it, maybe recursively evaluating them)
  44    If the state of the Program is 'MALA_REMOVE' the function shall not do any actions except removing itself and (maybe recursively) its parameters from the program (This is used to eleminate not taken branches)
  45    The function is responsible for removing itself and any parameters from the Program and set the program pointer to the next word.
  46
  47 recursive deduction steps:
  48  there are several destination states for recursive evaluation and a function can ask to stop evaluation when a certain level is reached. Internally these states are a enumeration counting down. Some values are used as special markers:
  49
  50  state == EINVALID              The Engine is in a illegal undefined condition,
  51                                 prepare for the worst and abort() (should never happen)
  52
  53  EINVALID > state > EFATAL      the Engine is in a unuseable (but defined) condition,
  54                                 you can only query it's state and free it then.
  55
  56  EFATAL > state > EFAULT        Mala runtime error, your app might handle it.
  57
  58  state < EFAULT                 States while the engine is running
  59
  60  state == EXCEPTION             a error happend, if no handler is present this will become ENOACTION
  61  state == REMOVE                action shall only remove itself and its arguments
  62  state == CONTINUE              last action resulted in a new word (substitution)
  63  state == MACRO                 last action resulted in a macro (StringList with % positional parameters)
  64  state == LIST                  last action resulted in a list (StringList, expanded macro,...)
  65  state == LITERAL               last action resulted in a single literal word
  66  state == FAILURE               last action was a predicate and failed
  67  state == SUCCESS               last action was a predicate and succeeded
  68
  69
  70 Blocks and Macros:
  71 Blocks are encapsulated in --BEGIN .. --END pairs, the defined action of --BEGIN is to define a new action of either a macro expansion (if the block contains % positional parameters) or a just a List expansion (when there are no parameters)
  72 This new actions is named --M_xxxx when the block is a macro or -L_xxxx when the block is a list. xxxx is a unique identifier of this block. These actions are not childs of "--WORLD" and become garbage collected when not used anymore.
  73
  74 that results in:
  75  - a block appears as single word for all further actions
  76  - the most generic form of a block is a unnamed macro (hidden named rather)
  77
  78
  79
  80
  81 Errors & Exceptions:
  82 when a action discovers an error it preceeds itself with --ERROR-xyz and puts a --BEFORE-HERE at the place of the wrong argument (or just after itself) and the state is set to MALA_EXCEPTION
  83
  84 Example: --DIV 1 0   becomes  --ERROR-DIVISION-BY-ZERO --DIV 1 0 --BEFORE-HERE
  85
  86 a user can define a proper handler for --ERROR-DIVISION-BY-ZERO, if no handler is defined the engine stops with ENOACTION