Dire bug in uscxml-browser, smaller fixes and documentation

7 files changed, 102 insertions, 35 deletions

diff --git a/README.md b/README.md
index 7029b3c..ece7b75 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,58 @@
-# Major update!
+# uSCXML ReadMe
 
 [![Build Status](https://travis-ci.org/tklab-tud/uscxml.png?branch=master)](https://travis-ci.org/tklab-tud/uscxml)
 
-We deprecated the [old uscxml interpreter](https://github.com/tklab-tud/uscxml/tree/legacy-1.0) and rewrote large parts with the lessons learned from the old version. The new implementation is not yet fully done and there is some functionality that has not (yet) made it to the new version.
+**Note**: We deprecated the [old version](https://github.com/tklab-tud/uscxml/tree/legacy-1.0) and refactored quite a few classes and interaces.
 
-I will update the documentation once I finished up on some polishing and remaining issues.
+**Note**: Some of the features described below may not yet have made it into the new version, but all will eventually. If I implied functionality not yet available just call me out on it and post an issue and I will make it a priority.
 
-##What's new
+## What is it? [what]
 
-### Working
+uSCXML is a platform to work with state-charts given as
+[SCXML](http://www.w3.org/TR/scxml/) files. Currently, it consists of three principal components:
 
- * All W3C IRP tests are passed
-   * Lua datamodel
-   * ECMAScript datamodel
- * Transformer for ANSI-C
+ 1. `libuscxml`: [C++ library](#library) containing an interpreter and accompanying functionality.
 
-### Important Changes
-
- * Compiling will require a C++11 compiler now
- * Dependencies are compiled at configure-time
- * Replaced Arabica DOM implementation with Xerces-C
- * New micro-step implementation
- * Removed unsupported Invokers
- * Data-model DOM bindings now generated by SWIG
+ 2. `uscxml-browser`: A standards compliant [command-line interpreter](#cli) of SCXML documents.
  
-### Still Missing
+ 3. `uscxml-transform`: A collection of [transformation](#transform) implementations to transpile SCXML, e.g. onto ANSI-C and VHDL.
+
+## Installation [install]
+
+There are no installers yet and we do not feature any releases. Just check for [open issues](https://github.com/tklab-tud/uscxml/issues) and [build from source](http://tklab-tud.github.io/uscxml/building.html). If you did download and build locally, you can create installers via `make packages` though.
+
+## Documentation [doc]
+
+Documentation is available at our [github pages](http://tklab-tud.github.io/uscxml/). It is created from inline comments in the source along with some dedicated markdown pages via `doxygen`. We try to keep it current and will update it ever again. For the most current documentation, you can run `make docs` in your build directory.
+
+## Licensing [license]
+
+uSCXML itself is distributed under the [Simplified BSD license](http://www.opensource.org/licenses/bsd-license) as in, do not sue
+us and do not misrepresent authorship. There are currently four additional libraries that are required to compile uSCXML.
+
+| Project | License | Comment |
+|---------|---------|---------|
+| [libcurl](https://curl.haxx.se/libcurl/) | [MIT/X derivate](https://curl.haxx.se/docs/copyright.html) | Used in uSCXML to fetch remote content |
+| [Xerces-C++](https://xerces.apache.org/xerces-c/) | [Apache v2](http://www.apache.org/licenses/LICENSE-2.0.html) | XML parser and DOM implementation |
+| [libevent](http://libevent.org) | [3-clause BSD](http://libevent.org/LICENSE.txt) | Delayed event queues |
+| [uriparser](http://uriparser.sourceforge.net) | [New BSD](https://sourceforge.net/p/uriparser/git/ci/master/tree/COPYING) | Referring and resolving URIs |
+
+At configure time, the uSCXML build-process will attempt to find and link several other libraries (e.g. Lua, v8) and additional licensing terms may apply.
+
+## Getting Started [started]
+
+For more detailled information, refer to the [documentation](http://tklab-tud.github.io/uscxml).
 
- * Language Bindings
- * Respond element
- * Plugin-Architecture
- * ArrayBuffers for binary data in data-model
+### Embedded as a Library [library]
+    uscxml::Interpreter scxml = uscxml::Interpreter::fromURL("...");
+    while(scxml.step() != uscxml::USCXML_FINISHED) {
+      ...
+    }
 
-### Dropped
+### On the Command-line [cli]
+    # interpret state-chart from url
+    $ uscxml-browser https://raw.githubusercontent.com/tklab-tud/uscxml/master/test/w3c/null/test436.scxml
 
- * XPath data-model
- * DOM Events
- * Many of the old invokers that were no longer supported
\ No newline at end of file
+### For Transformations [transform]
+    # transform given SCXML document into ANSI-C fragment
+    $ uscxml-transform -tc -i https://raw.githubusercontent.com/tklab-tud/uscxml/master/test/w3c/null/test436.scxml
diff --git a/apps/uscxml-browser.cpp b/apps/uscxml-browser.cpp
index cbbb21f..722b0af 100644
--- a/apps/uscxml-browser.cpp
+++ b/apps/uscxml-browser.cpp
@@ -99,6 +99,7 @@ int main(int argc, char** argv) {
                     interpreterIter++;
                 }
             }
+            interpreterIter = interpreters.begin();
         }
 	} catch (Event e) {
 		std::cout << e << std::endl;
diff --git a/contrib/local/deploy-docs.sh b/contrib/local/deploy-docs.sh
new file mode 100755
index 0000000..5e84431
--- /dev/null
+++ b/contrib/local/deploy-docs.sh
@@ -0,0 +1,27 @@
+#!/bin/bash
+
+set -e
+
+ME=`basename $0`
+DIR="$( cd "$( dirname "$0" )" && pwd )"
+CWD=`pwd`
+
+if [ ! -f "docs/html/index.html" ]
+then
+	echo "No documentation found in docs/html - run from build dir after make docs"
+	exit
+fi
+
+DOCS="${CWD}/docs/html"
+
+tempfoo=`basename $0`
+TMPDIR=`mktemp -d /tmp/${tempfoo}.XXXXXX` || exit 1
+cd ${TMPDIR}
+
+git clone -b gh-pages git@github.com:tklab-tud/uscxml.git
+rm -rf uscxml/*
+cp -R /Users/sradomski/Documents/TK/Code/uscxml/build/cli/docs/html/ ./uscxml/
+cd uscxml
+git add -A
+git commit -m "Updated documentation"
+git push
diff --git a/src/uscxml/Interpreter.cpp b/src/uscxml/Interpreter.cpp
index 9f2bfbf..05fb1fc 100644
--- a/src/uscxml/Interpreter.cpp
+++ b/src/uscxml/Interpreter.cpp
@@ -230,6 +230,7 @@ std::list<InterpreterIssue> Interpreter::validate() {
 
 std::recursive_mutex StateTransitionMonitor::_mutex;
 
+#if 0
 static void printNodeSet(const std::list<XERCESC_NS::DOMElement*> nodes) {
 	std::string seperator;
 	for (auto nIter = nodes.begin(); nIter != nodes.end(); nIter++) {
@@ -237,7 +238,8 @@ static void printNodeSet(const std::list<XERCESC_NS::DOMElement*> nodes) {
 		seperator = ", ";
 	}
 }
-
+#endif
+    
 void StateTransitionMonitor::beforeTakingTransition(const XERCESC_NS::DOMElement* transition) {
 	std::lock_guard<std::recursive_mutex> lock(_mutex);
 	std::cerr << "Transition: " << uscxml::DOMUtils::xPathForNode(transition) << std::endl;
diff --git a/src/uscxml/Interpreter.h b/src/uscxml/Interpreter.h
index ae1268f..1596914 100644
--- a/src/uscxml/Interpreter.h
+++ b/src/uscxml/Interpreter.h
@@ -160,7 +160,7 @@ public:
 	 *
 	 * @todo Have Interpreter::step() take a duration to block
 	 */
-	InterpreterState step(bool blocking = false);
+	InterpreterState step(bool blocking = true);
 
 	/**
 	 * Unblock and mark for finalize.
diff --git a/src/uscxml/interpreter/FastMicroStep.cpp b/src/uscxml/interpreter/FastMicroStep.cpp
index 99c2d74..fd9f1a9 100644
--- a/src/uscxml/interpreter/FastMicroStep.cpp
+++ b/src/uscxml/interpreter/FastMicroStep.cpp
@@ -325,7 +325,7 @@ void FastMicroStep::init(XERCESC_NS::DOMElement* scxml) {
 
 		// establish the transitions' exit set
 		assert(_transitions[i]->element != NULL);
-		std::cout << "i: " << i << std::endl << std::flush;
+//		std::cout << "i: " << i << std::endl << std::flush;
 		std::list<DOMElement*> exitList = getExitSet(_transitions[i]->element, _scxml);
 		for (j = 0; j < _states.size(); j++) {
 			if (!exitList.empty() && _states[j]->element == exitList.front()) {
diff --git a/src/uscxml/plugins/DataModelImpl.h b/src/uscxml/plugins/DataModelImpl.h
index e2795c0..c3f5390 100644
--- a/src/uscxml/plugins/DataModelImpl.h
+++ b/src/uscxml/plugins/DataModelImpl.h
@@ -111,16 +111,24 @@ public:
 	 */
 	size_t replaceExpressions(std::string& content);
 
-	///@name Foreach Support
-	///@{ 
-
-	// foreach
+	/**
+	 * Evaluate the given expression as something iterable and return its length.
+	 * @param expr Anything that possibly evaluates to an enumerable object.
+	 * @return The number of items in the enumerable object.
+	 */
 	virtual uint32_t getLength(const std::string& expr) = 0;
+	
+	/**
+	 * Set a given item to the object at a given index for one iteration.
+	 * @param item A variable or location to assign the current object to.
+	 * @param array An expression evalating to an enumerable object.
+	 * @param index A variable or location to set the current index at.
+	 * @param iteration The current iteration index.
+	 */
 	virtual void setForeach(const std::string& item,
 	                        const std::string& array,
 	                        const std::string& index,
 	                        uint32_t iteration) = 0;
-	///@} 
 
 	/**
 	 * Return a string as an *unevaluated* Data object.
@@ -181,8 +189,17 @@ test277:
 	 */
 	virtual void init(const std::string& location, const Data& data) = 0;
 
-
+	/**
+	 * Register an extension to get data into and out of the data-model.
+	 * @todo This is currently unsupported
+	 */
 	virtual void addExtension(DataModelExtension* ext);
+	
+	/**
+	 * Concat the given terms into a conjunctive form.
+	 * @todo This is required to automatically transform a state-chart into a 
+	 * state-machine. Actual transformation is still only available in legacy though.
+	 */
 	virtual std::string andExpressions(std::list<std::string>) {
 		return "";
 	}