2 Developing an ECharts Machine

The ECharts SDK (System Development Kit) is split into two major components: (1) a translator and (2) a runtime system. The translator translates an ECharts machine into a host language program module, for example, Java. The runtime system is a host language library comprising the ECharts machine interpreter, that is, the code that actually executes the machine. The runtime system library is linked with the compiled ECharts machine modules and other compiled host language modules to form an executable program. For information on building the ECharts SDK see Appendix A.

2.1 Hello World!

Here’s an example of how to program, compile, and run the canonical “Hello World!” program as an ECharts machine. In this example and all subsequent examples, we employ Java as the ECharts host language.

First, create the ECharts machine itself in a file examples/Example0001.ech. If you feel like cheating a bit, you’ll find this file and all other example files mentioned in this document in the runtime/java/src/examples directory of the ECharts SDK.

package examples;

public machine Example0001 {
    initial state S1;
    state S2;
    transition S1 - / System.out.println("Hello World!") -> S2;
}

For all examples in this document we depict a program using the ECharts textual syntax and its graphical syntax. For a discussion of the many ways that exist to generate machine diagrams like the one above see Section 6.

The Example0001 machine does nothing more than transition from state S1, declared as the machine’s initial state, to state S2 executing the action to print “Hello World!” in the process. The graphical syntax depicts the initial state with a bold outline. In ECharts, transition actions are defined following the / (forward slash) character. Here the action is a simple expression, System.out.println("Hello World!"), specified using Java syntax. In general, Java expression syntax can be used to specify machine actions regardless of the host language. These are translated to the appropriate host language expressions (in this case, Java expressions) appropriately. ECharts also permits otherwise unacceptable expressions to be wrapped in host code delimiters <* *>. Further discussion concerning the ECharts/host language interface can be found in Section 3.16.

To translate the machine to the host language, invoke the ECharts translator (provided with the ECharts SDK) from the examples directory. In this example and subsequent examples, we show a command line prompt as a percent character %.

% ech2java --echartspath .. Example0001.ech

For information on configuring your platform to run ECharts commands like ech2java see Appendix A. This command will create a file examples/Example0001.java. Note the use of the --echartspath command line option. This option informs the translator where to locate the examples package declared in our machine. It is analogous to Java’s javac -classpath command line option. See Section 8 for more ech2java command line options.

To compile and link the translated machine, invoke the host language’s compiler from the examples directory:

% javac -classpath ..:../../echarts.jar Example0001.java

This command creates the file examples/Example0001.class. Note that the -classpath option references the echarts.jar file containing the ECharts Java runtime system (part of the ECharts SDK build).

The next step is to write a host language program whose mainline procedure calls the machine. To do this create a file examples/HelloWorld.java:

package examples;

public class HelloWorld {
    public static final void main(String argv[]) {
        try {
            new Example0001().run();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

All this program does is create a new instance of an Example0001 machine and then invoke its run() method. The run() method returns after the ECharts machine runtime has determined that it can execute no further machine transitions.

% javac -classpath ..:../echarts.jar HelloWorld.java

This will produce the file examples/HelloWorld.class. As the final step, run the program:

% java -classpath ..:../echarts.jar examples.HelloWorld
Hello World!

There you have it. Naturally, the steps described above for building an executable program can be automated using your favorite build tool such as ant or make. A GNU Makefile and and Apache Ant build.xml file are included in ECharts SDK for building the example machines in this document. For more information about ECharts runtimes and translators see Sections 5 and 8, respectively.

Chapter 2Developing an ECharts Machine

2.1 Hello World!

Chapter 2
Developing an ECharts Machine