diff options
author | Stefan Radomski <github@mintwerk.de> | 2016-05-19 08:03:50 (GMT) |
---|---|---|
committer | Stefan Radomski <github@mintwerk.de> | 2016-05-19 08:03:50 (GMT) |
commit | 5de792adc6796b0f03d62124765b4af0676dde46 (patch) | |
tree | e700d6b008b21c037aebcc1882fd9286920b2987 /src/uscxml/Interpreter.h | |
parent | f8e0c96fddfdd5f086e1bd973d6b0a19c39c93da (diff) | |
download | uscxml-5de792adc6796b0f03d62124765b4af0676dde46.zip uscxml-5de792adc6796b0f03d62124765b4af0676dde46.tar.gz uscxml-5de792adc6796b0f03d62124765b4af0676dde46.tar.bz2 |
Refactored for public headers and started documentation
Diffstat (limited to 'src/uscxml/Interpreter.h')
-rw-r--r-- | src/uscxml/Interpreter.h | 205 |
1 files changed, 137 insertions, 68 deletions
diff --git a/src/uscxml/Interpreter.h b/src/uscxml/Interpreter.h index fa5ab05..ae1268f 100644 --- a/src/uscxml/Interpreter.h +++ b/src/uscxml/Interpreter.h @@ -20,20 +20,28 @@ #ifndef INTERPRETER_H_6CD5A168 #define INTERPRETER_H_6CD5A168 + +#include "Common.h" + #include <map> -#include <mutex> #include <string> +#include <vector> -#include "Common.h" -#include "uscxml/interpreter/InterpreterImpl.h" -#include "uscxml/interpreter/InterpreterMonitor.h" // beware cyclic reference! -#include "uscxml/debug/InterpreterIssue.h" // beware cyclic reference! -#include <xercesc/dom/DOM.hpp> +#include "uscxml/interpreter/MicroStep.h" +#include "uscxml/plugins/DataModel.h" +#include "uscxml/interpreter/ContentExecutor.h" +#include "uscxml/interpreter/InterpreterState.h" namespace uscxml { -class InterpreterMonitor; // forward declare +class InterpreterMonitor; +class InterpreterImpl; +class InterpreterIssue; +/** + * @ingroup interpreter + * Options to pass into an interpreter. + */ class USCXML_API InterpreterOptions { public: InterpreterOptions() : @@ -75,60 +83,139 @@ public: }; +/** + * @ingroup interpreter + * Collection of instances for interpreter that constitute its action language. + */ +class USCXML_API ActionLanguage { +public: + MicroStep microStepper; ///< The microstepper instance to use + DataModel dataModel; ///< The datamodel to uses + ContentExecutor execContent; ///< To process executable content elements +}; + +/** + * @ingroup interpreter + * @ingroup facade + * Central class to interpret and process SCXML documents. + + Instances of this class are available from the static constructors. In order + to use an interpreter instance to actually *do* things, you will want to + provide an ActionLanguage and an InterpreterMonitor. + + We did avoid threading primitives within the core interpreter (there is + threading for nested interpeters in the USCXMLInvoker, though). As such, you + will have to call the <step> function continuously. + + */ + class USCXML_API Interpreter { public: - static Interpreter fromDocument(xercesc::DOMDocument* dom, + + /** + * Instantiate an Interpeter with a given XML document. + * @param dom A pointer to the XML document. + * @param baseURL An absolute URL to resolve relative URLs in the document. + * @param copy Whether to make a copy of the document, we deallocate it either way. + */ + static Interpreter fromDocument(XERCESC_NS::DOMDocument* dom, const std::string& baseURL, bool copy = true); - static Interpreter fromElement(xercesc::DOMElement* element, + /** + * Instantiate an Interpeter with a given XML element. + * This constructor will create a new document and copy/import the given element. + * @param element The element to be copies/imported as the new document element. + * @param baseURL An absolute URL to resolve relative URLs in the document. + */ + static Interpreter fromElement(XERCESC_NS::DOMElement* element, const std::string& baseURL); + /** + * Instantiate an Interpeter from a string containined proper XML markup. + * @param xml Textual representation of an SCXML document. + * @param baseURL An absolute URL to resolve relative URLs in the document. + */ static Interpreter fromXML(const std::string& xml, const std::string& baseURL); - static Interpreter fromURL(const std::string& URL); + /** + * Instantiate an Interpeter with a document located at an URL. + * @param url An absolute URL to locate the SCXML document. + */ + static Interpreter fromURL(const std::string& url); + + /** + * Instantiate an Interpeter as a copy of another. + * @param other The other interpreter. + */ static Interpreter fromClone(const Interpreter& other); + /** + * See PIMPL_OPERATORS macro in Common.h + */ PIMPL_OPERATORS(Interpreter); - void reset() { - return _impl->reset(); - } - - InterpreterState step(bool blocking = false) { - return _impl->step(blocking); - }; - - void cancel() { - return _impl->cancel(); - } - - virtual bool isInState(const std::string& stateId) { - return _impl->isInState(stateId); - } - - InterpreterState getState() { - return _impl->getState(); - } - - std::list<xercesc::DOMElement*> getConfiguration() { - return _impl->getConfiguration(); - } - - virtual void receive(const Event& event) { - _impl->enqueueExternal(event); - } - - void setActionLanguage(ActionLanguage actionLanguage) { - return _impl->setActionLanguage(actionLanguage); - } - - void setMonitor(InterpreterMonitor* monitor) { - return _impl->setMonitor(monitor); - } - - std::list<InterpreterIssue> validate() { - return InterpreterIssue::forInterpreter(_impl.get()); - } - + /** + * Perform a single microstep and return. + * @param blocking Whether or not to block the thread when waiting for events + * @return The new state of the interpreter object. + * + * @todo Have Interpreter::step() take a duration to block + */ + InterpreterState step(bool blocking = false); + + /** + * Unblock and mark for finalize. + */ + void cancel(); + + /** + * Finalize and reset interpeter. + */ + void reset(); + + /** + * Get all state elements that constitute the active configuration. + * @return A list of XML elements of the active states. + */ + std::list<XERCESC_NS::DOMElement*> getConfiguration(); + + /** + * Determine whether the state with the given `id` is in the active configuration. + * @param id An identifier for a state from the SCXML document. + * @return Whether the interpreter is in state `id`. + */ + bool isInState(const std::string& stateId); + + /** + * The current state of the interpreter, not to be confused with its configuration. + * @return The current state of the interpreter object. + */ + InterpreterState getState(); + + /** + * Return a list of possible syntactic and semantic issues with the interpreter's state-chart. + * @return A list of InterpreterIssue%s + */ + std::list<InterpreterIssue> validate(); + + /** + * Enqueue an event to the interpreter's external queue. + * @event An event to be enqueued + */ + void receive(const Event& event); + + /** + * Adapt the constituting components for a SCXML interpreter. + */ + void setActionLanguage(ActionLanguage actionLanguage); + + /** + * Attach a monitor to make more details of the interpreter observable. + */ + void setMonitor(InterpreterMonitor* monitor); + + /** + * Return the actual implementation of the Interperter. + */ std::shared_ptr<InterpreterImpl> getImpl() const { return _impl; } @@ -138,24 +225,6 @@ protected: }; -class USCXML_API StateTransitionMonitor : public uscxml::InterpreterMonitor { -public: - StateTransitionMonitor(Interpreter interpreter) : _interpreter(interpreter) {} - virtual ~StateTransitionMonitor() {} - - virtual void beforeTakingTransition(const xercesc::DOMElement* transition); - virtual void beforeExecutingContent(const xercesc::DOMElement* element); - virtual void onStableConfiguration(); - virtual void beforeProcessingEvent(const uscxml::Event& event); - virtual void beforeExitingState(const xercesc::DOMElement* state); - virtual void beforeEnteringState(const xercesc::DOMElement* state); - virtual void beforeMicroStep(); - -protected: - Interpreter _interpreter; - static std::recursive_mutex _mutex; -}; - } #endif /* end of include guard: INTERPRETER_H_6CD5A168 */ |