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 (pptr) is initialized before first 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 (literal), the pptr it is set before the following word
  41 else if it is bound to an action its associated C function (parser) is called
  42    The function can freely modify the program (usually takeing parameters following it, maybe recursively evaluating them)
  43    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)
  44    The function is responsible for removing itself and any parameters from the Program and set the program pointer to the next word.
  45
  46 recursive deduction steps:
  47  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:
  48
  49
  50  state == EINVALID              The Engine is in a illegal undefined condition,
  51                                 prepare for the worst and abort()
  52                                 (should hopefully never happen)
  53
  54  EINVALID > state > EFATAL      the Engine is in a unuseable bad (but defined) condition,
  55                                 you can only query its state and free it then.
  56
  57  EFATAL > state > EFAULT        Mala runtime error, your app might handle it
  58                                 and then continue normal operation.
  59
  60  state < EFAULT                 States while the engine is running:
  61
  62 special states:
  63  state == REMOVE                action shall only remove itself and its arguments
  64  state == EXCEPTION             a error happend, if no handler is present this will become ENOACTION (a runtime error)
  65 functional states:
  66  state == START                 initial state when starting evaluation
  67  state == MACRO                 last action resulted in a macro (StringList with % positional parameters)
  68  state == LIST                  last action resulted in a list (StringList, expanded macro,...)
  69 final states:
  70  state == CONTINUE              last action removed itself (procedure), the next word is there now
  71  state == LITERAL               last action resulted in a single literal word
  72  state == FAILURE               last action failed
  73  state == SUCCESS               last action succeeded
  74
  75
  76 Blocks and Macros:
  77 Blocks are encapsulated in --BEGIN .. --END pairs, --BEGIN is defined 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)
  78 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.
  79
  80 that results in:
  81  - a block appears as single word for all further actions
  82  - the most generic form of a block is a unnamed macro (hidden named rather)
  83
  84
  85 Parameter Expansion:
  86 A Macro can have up to 9 positional parameters (%1..%9), parameter %0 is the macro name itself.
  87 %% is the percent sign. Normal parameters (%1..%9) are recursively evaluated until they yield a literal value, this can be prevented by using %-1..%-9 as parameter (%-0 expands to the definition of the macro). It is an error to have a normal and a negative form of the same parameter in one macro. All normal parameters are first evaluated from left to right. After macro expansion, all arguments up to the highest parameter number are removed.
  88 Any other character following a % is reserved!
  89 (in future there will be diffrent stages of evalutation)
  90
  91  examples:
  92   # concat the first 2 args (1 and 2 evaluated, but they are already literals)
  93   %1%2 1 2 3            -->  12 3
  94
  95   # first evaluate the --ADD and then concat
  96   %1%2 --ADD 1 2 3      -->  33
  97
  98   # don't evaluate, just concat
  99   %-1%-2 1 2 3          -->  12 3
 100
 101   # don't evaluate. --ADD and 1 are now the first 2 args
 102   %-1%-2 --ADD 1 2 3    -->  --ADD1 2 3
 103
 104   # take parameter 1 and 3, the 2 gets dropped
 105   %1%3 1 2 3            -->  13
 106
 107 %% OBSOLETE rewrite this
 108 %%Errors & Exceptions:
 109 %%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
 110 %%
 111 %%Example: --DIV 1 0   becomes  --ERROR-DIVISION-BY-ZERO --DIV 1 0 --BEFORE-HERE
 112 %%
 113 %%a user can define a proper handler for --ERROR-DIVISION-BY-ZERO, if no handler is defined the engine stops with ENOACTION
 114
 115
 116
 117