Porting to a New Host Language
Here are some notes for people interested in porting ECharts to a new host language. These notes are incomplete but they're a start. At the moment, they only cover the translator, not the runtime interpreter. These notes don't constitute documentation but they're a start...

The important directories in the ECharts distribution are the 'translator' and the 'runtime' directories.

  • the 'translator' directory contains host language translators for ECharts machine e.g. the ech2java translator for translating an ECharts .ech file to a corresponding .java file
  • the 'runtime' directory contains host language interpreters for translated ECharts machines e.g. the javamachine runtime for executing a .java file generated by ech2java

Let's look at the two directories in more detail now.

  • the ECharts translator is based on the Python version of the ANTLR parser generator - for this reason ECharts translators are written in Python
  • the translator directory consists of two main subdirectories: (1) 'bin' which contains the various translator commands e.g. ech2java, and (2) 'lib' which contains the translator code libraries invoked by the translator commands and the ECharts parser itself
  • the commands in the 'bin' directory invoke a common backend program, ech2x.py - like the javac translator, ech2x.py determines dependencies between .ech files and relative modification dates in order to determine which .ech files require translation, and invokes the appropriate translator when translation is required - ech2x.py also supports a number of commonly used command-line options e.g. the --target-directory option can be used to specify the directory to write translated files to
  • the 'lib' directory consists of subdirectories containing host code translators e.g. the 'javamachine' subdirectory contains the code for translating a .ech file to a .java file
  • the 'lib' directory also contains the ECharts grammar files and the ECharts abstract machine program, AbstractMachine.py
  • the ECharts grammar files (echarts*.* antlr.*) can be ignored since the grammar is fixed
  • in contrast, the ECharts abstract machine class, AbstractMachine.py, cannot be ignored - this program encapsulates the abstract syntax tree for a parsed .ech file - it is the job of the machine translator (e.g. the javamachine translator) to traverse a machine's abstract syntax tree to generate a host code representation of the machine - the AbstractMachine.py file is divided into two parts - the bottom of the file comprises the AbstractMachine class definition - this class and its methods can be ignored - however, it is important to understand how this class is used by ech2x.py - ech2x.py creates an instance of the AbstractMachine class for an .ech file when it determines the file requires parsing - when an instance of this class is created the side effect is to parse its associated .ech file and create its abstract syntax tree - after an .ech file is parsed its abstract syntax tree is passed to the machine translator by ech2x.py - an ECharts abstract syntax tree is represented by a nested list structure - the top of the AbstractMachine.py file comprises a comprehensive set of methods for accessing abstract syntax tree components - a machine translator is expected to use these methods as it traverses the abstract syntax tree - for example, the getStates() method returns a list of states defined for the machine list provided as the method's argument - a machine translator should never have to access the abstract syntax tree structure directly, it should only access it using the accessor methods
  • as mentioned earlier a machine's abstract syntax tree is represented as a nested list structure - as a result, many of the abstract machine accessor methods return sub-lists of this structure - occasionally, the curious programmer may want to print a list returned by one the accessors - the recommended way to do this is to use the AbstractMachine.py indent() method - this method portrays an abstract syntax tree (sub-)list in a human-readable format
  • once a machine's .ech file is parsed and its abstract syntax tree is created, the ech2x.py file calls the machine translator's translate() method, passing it the abstract syntax tree as a parameter (along with other useful parameters) - the machine translator traverses the abstract syntax tree to create a string constituting the host code representation of the abstract machine and returns the string to ech2x.py - ech2x.py then writes the string to a file e.g. SomeMachine.java - the string created by the machine translator includes any ECharts state, transition, and constructor declarations, and any host code declarations e.g. methods and fields - these declarations are expressed in terms of data structures defined in the host language runtime library e.g. each state declared in the abstract machine is translated to Java code that creates an org.echarts.State class instance (defined in the javamachine runtime library)

What follows needs work.

  • the runtime - package hierarchy overview - big picture of the class hierarchy - strategy used for Java runtime: static declarations of states and transitions for each machine class - familiarization with translation and execution of runtime/java/src/examples/Example0001.java (Hello World!)
  • suggested implementation strategy for machines: first or-machines, then and-machines, then inner machines, then machine arrays (dynamic machines) - for transitions: messageless transitions, then message transitions, then timed transitions - leave reflective machine invocation for later - use javamachine test suite as basis for host language tests - should be simple to translate to another host language

Discuss this article on the forums. (0 posts)
Last Updated ( Wednesday, 17 October 2007 )