Some tidying up of ANSI-C transformation

3 files changed, 231 insertions, 0 deletions

diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md
new file mode 100644
index 0000000..94e8d3b
--- /dev/null
+++ b/docs/COMPARISON.md
@@ -0,0 +1,89 @@
+# Comparison of SCXML Interpreters
+
+In this document, I will make an attempt to compare and measure the performance
+of the various, freely available SCXML interpreters. If you are the author of
+one of these interpreters and feel that I misrepresented your work, please do
+not hesitate to contact me and I will reevaluate / correct any factual errors.
+
+This selection is based on the list of available implementations on the [SCXML
+wiki](https://en.wikipedia.org/wiki/SCXML) page, plus a few interpreters I know
+from the [W3C mailing list](https://lists.w3.org/Archives/Public/www-voice/)
+and the [SCXML workshops](http://scxmlworkshop.de). I will list all
+interpreters known to me, but only benchmark those that pass the W3C IRP tests
+as is required for an actual SCXML interpreter.
+
+# Methodology
+
+The benchmarks were performed with a [huge
+SCXML](https://github.com/tklab-tud/uscxml/tree/master/test/w3c/compound) file
+containing all of the automatic W3C IRP tests that do not rely on timeouts to
+pass.
+
+## scxmlcc
+
+| Platforms     | Tested on           | Tested           | Website       |
+|---------------|---------------------|------------------|---------------|
+| Linux only    | Debian Jessie 64Bit | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [http://scxmlcc.org](http://scxmlcc.org) |
+
+### How to build
+
+    $ sudo apt-get install build-essential libboost-all-dev autorevision
+    $ git clone https://github.com/jp-embedded/scxmlcc.git
+    $ cd scxmlcc/src
+    $ make
+    
+### Evaluation
+
+    $ ./scxmlcc -i ./test-ecma-all.scxml |sort |uniq
+    warning: event asteriks not currently supported
+    warning: event tokens not currently supported
+    warning: parallel support is not fully implemented/tested
+    warning: unknown action type 'script'
+    warning: unknown item 'assign' in <onentry> or <onexit>
+    warning: unknown item 'assign' in <transition>
+    warning: unknown item 'cancel' in <transition>
+    warning: unknown item 'datamodel' in <state>
+    warning: unknown item 'donedata' in <state>
+    warning: unknown item 'foreach' in <onentry> or <onexit>
+    warning: unknown item 'if' in <onentry> or <onexit>
+    warning: unknown item 'invoke' in <state>
+    warning: unknown item 'send' in <onentry> or <onexit>
+    warning: unknown item 'send' in <transition>
+
+The subset of SCXML implemented in <tt>scxmlcc</tt> is insufficient to run the
+performance / compliance benchmarks.
+
+## SCXML Lab
+
+| Platforms     | Tested on           | Tested    | Website       |
+|---------------|---------------------|-----------|---------------|
+| HTML5         | Safari 9.0.3        | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [http://www.ling.gu.se/~lager/Labs/SCXML-Lab/](http://www.ling.gu.se/~lager/Labs/SCXML-Lab/) |
+
+I pasted the file above into their web-frontend and got a <tt>validation-error</tt>
+
+    Unexpected attribute 'datamodel' in <scxml>. Hint: 
+    Valid attributes are: 'id', 'initialstate', 'version', 'xmlns'.
+
+The <tt>datamodel</tt> is indeed not required for a compliant interpreter, but
+we will not be able to pass any meaningful subset of the SCXML IRP tests
+without support for a datamodel.
+
+## Legian
+
+| Platforms     | Tested on           | Tested    | Website       |
+|---------------|---------------------|-----------|---------------|
+| Java          | Java(TM) SE (build 1.8.0_45-b14) | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [https://github.com/pelatimtt/Legian](https://github.com/pelatimtt/Legian/) |
+
+Does not claim W3C compliance and will, therefore, not pass the compound IRP tests.
+
+## Qt SCXML Engine
+
+| Platforms     | Tested on           | Tested    | Website       |
+|---------------|---------------------|-----------|---------------|
+| Any           | Mac OSX 10.11.3 with Macports 2.3.4 | **No**: Subset of SCXML implemented is insufficient for SCXML IRP tests. | [https://qt.gitorious.org/qt-labs/scxml](https://qt.gitorious.org/qt-labs/scxml/) |
+
+[No
+support](https://qt.gitorious.org/qt-labs/scxml?p=qt-labs:scxml.git;a=blob_plain;f=doc/scxml.qdoc;hb=HEAD) 
+for <tt>&lt;donedata></tt>, <tt>&lt;finalize></tt>. Furthermore the
+<tt>profile</tt> (now <tt>datamodel</tt> with finalized SCXML recommendation) 
+attribute is ignored.
diff --git a/docs/untitled.txt b/docs/GETTING_STARTED.md
index 8c585bf..8c585bf 100644
--- a/docs/untitled.txt
+++ b/docs/GETTING_STARTED.md
diff --git a/docs/NATIVE_CODE.md b/docs/NATIVE_CODE.md
new file mode 100644
index 0000000..91af599
--- /dev/null
+++ b/docs/NATIVE_CODE.md
@@ -0,0 +1,142 @@
+# Generating Native Code
+
+You can use the <tt>uscxml-transform</tt> tool to create native code from an
+SCXML document. In this case, you will not use an instance of the
+<tt>uscxml::Interpreter</tt> class, but instantiate an SCXML context from a
+native description of the state-chart.
+
+## Embedding ANSI C
+
+To embed the control flow described within an SCXML document in most variances
+of the C language, we provide a transformation onto ANSI C (C89) as a proper
+subset of virtually any more modern C/C++ dialect. There are two general
+approaches to achieve this. In any case, you need to transform your SCXML
+state-chart onto ANSI C by invoking <tt>uscxml-transform</tt>:
+
+    $ uscxml-transform -tc -i INPUT_FILE -o OUTPUT_FILE
+
+This transformation will create a single file that you can compile and link or
+include directly. I advice to include the file into another compilation unit
+and not to compile it directly, as it allows for more convenience and is
+generally a more flexible approach. The file will contain:
+
+1. A set of pre-processor **macros** for convenience and definitions, all starting
+with an <tt>USCXML_</tt> prefix. Of special note are the following macros that
+allow you to influence important characteristics of you state-machine.
+
+    * <tt>**USCXML_NR_STATES_TYPE** / **USCXML_NR_TRANS_TYPE**</tt>: 
+    
+        The type for unsigned integers that is of sufficient size to contain
+        the number of states / transitions of your largest state machine. The
+        transformation will automatically choose one of the <tt>uint*_t</tt>
+        types, though a popular extension, they are only available in C99
+        (<tt>stdint.h</tt>). Also, if you like to reuse parts of the file (e.g.
+        the types below) in another compilation unit, you might need to
+        predefine them explicitly to a sufficient size.
+
+    * <tt>**USCXML_MAX_NR_STATES_BYTES** / **USCXML_MAX_NR_TRANS_BYTES**</tt>: 
+
+        The minimial size for the bit-arrays as <tt>char[N]</tt> containing the
+        states and transitions in the various types and on the stack during a
+        microstep. It has to be larger or equal to the smallest positive
+        integer that, when multiplied by 8 is larger or equal to the number of
+        states and transitions repsectively. 
+        
+        In other words, make sure that
+        <tt>states[USCXML_MAX_NR_STATES_BYTES]</tt> has room for one bit per
+        state and <tt>transitions[USCXML_MAX_NR_TRANS_BYTES]</tt> for one bit
+        per transition.
+
+    * There are some other macros defined, but they are rather for
+      micro-optimizations. Have a look at a generated file.
+
+2. All compound data **types** (<tt>struct</tt>) to encode an SCXML state-machine.
+These will refer to the macros above to require memory for a state-chart's
+states and transitions, so make sure that the macros are set if you
+conditionally include parts of the generated file and double-check that the
+type definitions are the same in every compilation unit if you want to access
+state-machines from other units (i.e. same value for macros above!).
+
+3. The actual **symbols** for one or many state-machines from the input SCXML
+file. Their identifiers are all prefixed by an identifier derived from the
+content of a given SCXML document. As such, if you transform any given SCXML
+document twice, you might end up with duplicate symbols, yet again, the
+state-chart's will be functionally identical as they contained the same content.
+
+    In order for not having to guess the prefix when referring to any machine
+    in application code, the tranformation will define three additional macros:
+
+        #ifndef USCXML_MACHINE
+        #  define USCXML_MACHINE _uscxml_BC220711_machine
+        #endif
+        #define USCXML_MACHINE_0 _uscxml_BC220711_machine
+        #define USCXML_MACHINE_NAME_HERE _uscxml_BC220711_machine
+
+    The first macro is useful if you only transformed a single SCXML
+    state-chart as it will always refer to the very first state-chart
+    encountered. If there is more than one SCXML state-chart within a document
+    (i.e. an invocation of nested machines) you can also refer to them by index
+    or their eventual name.
+
+4. Some **helper functions**, most notably bit operations for arbitrary length
+bit arrays.
+
+5. The **micro-step function** <tt>uscxml_step</tt>, which will perform a
+micro-step on a given context and delegate control flow accordingly.
+
+These elements are always contained and you can, selectively, disable their
+inclusion by pre-defining respective macros (have a look at a generated source
+file).
+
+Now in order to actually use an SCXML document to manage the control flow among
+a set of functions, there are two general approaches. Both use the generated
+ANSI C source code above, but require more or less resources at runtime as
+detailled below.
+
+### Fully Compliant
+
+An SCXML interpreter does more than to perform a series of microsteps for event
+over a set of states and transitions and there are quite a few responsibilities
+not implemented in the generated ANSI C code:
+
+1. **Event Queues**:
+
+    A compliant interpreter is required to maintain two event queues, an
+    internal and an external one. With the generated ANSI C source, these are
+    integrated via four callbacks and will need to be implemented in
+    user-supplied code:
+    
+    1. <tt>**uscxml_ctx.dequeue_internal**</tt>: This callback is invoked
+    whenever the interpreter needs an event from the internal event queue. It
+    is passed an instance of a <tt>uscxml_ctx</tt> structure and is supposed to
+    return an opaque pointer to an event. If the internal queue is empty,
+    <tt>NULL</tt> is to be returned.
+    
+    2. <tt>**uscxml_ctx.dequeue_external**</tt>: This callback is functionally
+    equivalent to <tt>uscxml_ctx.dequeue_internal</tt> but invoked, when an
+    external event is to be dequeued.
+
+    3. <tt>**uscxml_ctx.exec_content_send**</tt>: Whenever there is an
+    <tt>&lt;send></tt> element encountered in executable content, the generated
+    ANSI C code will invoke this callback with a context and an
+    <tt>uscxml_elem_send</tt> instance and the user code registered at the
+    callback is expected to handle the send request as per recommendation.
+
+    4. <tt>**uscxml_ctx.exec_content_raise**</tt>: This callback is invoked for
+    any <tt>&lt;raise></tt> element processed as part of executable content and
+    is expected to deliver an event to the internal event queue.
+    
+2. **Transition Matching / Enabling**
+
+    An event will match and enable a set of transitions. The generated ANSI C
+    source will already make sure that only valid sets of transitions can be
+    selected to constitute the optimal transition set for a microstep, but
+    user-supplied code will have to decide whether a transition is matched and
+    enabled. This is done via the <tt>**uscxml_ctx.is_enabled**</tt> callback.
+    It receives a context, a <tt>uscxml_transition</tt> structure and the
+    opaque event pointer and will have to return <tt>0</tt> for when the
+    transition is not matched and enabled by the given event and <tt>1</tt> if
+    it is.
+
+
+### Light-Weight