Bidirectional Model Transformation with eMoflon::IBeX
Learn how to specify bidirectional model transformations with eMoflon::IBeX-TGG

eMoflon::IBeX-TGG is a tool for specifying bidirectional model transformations of EMF models using Triple Graph Grammars (TGGs).  It is integrated into the eMoflon::IBeX toolsuite, which also supports unidirectional transformations via graph transformation.  In our first handbook +Meta-Modelling with eMoflon::IBeX we got to know the puzzle game Sokoban and spent some time learning how to metamodel it with the Eclipse Modelling Framework (EMF) and eMoflon::Core.  In the second part of our handbook +Unidirectional Model Transformation with eMoflon::IBeX we got introduced to graph constraints which we used to validate Sokoban boards, and graph transformations which we used to move Sokoban around and push boxes correctly (according to the rules of the game or its semantics).  In this third part of our handbook we’ll be supporting a standard textual import/export format for Sokoban puzzles.  This will require a pair of board-to-text and text-to-board model transformations, and we’ll see how a special dialect of graph transformations (TGGs) is particularly suitable for such tasks.

✈️ Some (starting) assumptions we make

  • You’ll start with a fresh workspace.  Yes, we know you’d like to perhaps continue where you left off, but if you do so you’re on your own so don’t complain later (you’ve been warned).
  • You avoid white spaces and umlauts in the path to your Eclipse workspace, especially on Windows.

Get your workspace compiling

Before starting you’ll need to install an extra plugin for this handbook.  We’ll be using Xtext for text-to-model transformations, and Xtend for model-to-text transformations.  Don’t worry if you’ve never used these technologies before, we won’t be focussing too much on them and will be using mainly read-to-go implementations.   Choose and install Xtext (it includes Xtend) from the categories listed on this Eclipse update site.  

Next, check out the prepared workspace I. Sokoban Example: 3 using the eMoflon cloud menu as usual.  You should have exactly four projects in your workspace — three from the previous handbooks (SokobanLanguage, SokobanGUI, SokobanRules) , and one new project (sokobanExchangeFormat).

To generate the parser for the textual Sokoban exchange format (let’s refer to this format in the following as “sok”) locate GenerateSokobanExchangeFormat.mwe2 in the sokobanExchangeFormat project under /src/org.emoflon.ibex.handbook/, right-click it and choose Run As/MWE 2 Workflow.  If all goes well you should get some messages logged on your console ending with a reassuring “Done”.

Finally, choose all projects and hit the black eMoflon hammer for a full rebuild.  You should now have a compiling workspace with no problems or warnings.  If you still have some problems in MANIFEST.MF files complaining about non existent packages, check that these packages have been generated.  If yes, then just choose the stale problem markers in the problem view, right-click and delete the pesky things.  

Inspect the supplied parser and serialiser

The sok format we want to support is described in this wiki.  It’s more or less a standard for describing Sokoban levels and you can google for and find numerous Sokoban puzzles to be downloaded in this format.  Let’s take a look at the example below (you can find it in your workspace as /SokobanGUI/boards/chaos.sok):
Author::"YASGen & Briant Damgaard"

###@ .#
# $ #.#
#  $$ #
#.  # #
#   $.#

To load (and save) such a file as (from) a Sokoban model according to our metamodel, we need to start by parsing the textual file into something we can work with.  Xtext is made for this kind of job and has the extra benefit of supporting EMF directly.  This means that Xtext produces an EMF model that we can directly operate on using EMF-compatible tooling.  If you’re interested in seeing the string grammar that we’ll be using to parse sok files, open SokobanExchangeFormat.xtext in sokobanExchangeFormat under /src/org.emoflon.ibex.handbook/ and take a look.  If you more or less know what string grammars are then it should be possible to get the gist of what the code specifies.  The important point is that the format is parsed recursively — so a board essentially references its first row, which unfolds to a first entry and the next row (and so on).  Every entry also unfolds recursively to either an empty field “ “ (an empty end field is “.”), or a symbol representing the figure on the (end) field, and then a next entry if there is one.  A list of symbols is used to represent all possible figures, e.g., @ for Sokoban (+ for Sokoban on an end field).

With that understanding in mind, we can now take a look at the metamodel Xtext automatically generates from this string grammar (below to the left), and a small model representing a board with four fields (below to the right).  Take your time to understand how this tree represents the Sokoban board and how what maps to what (“#” is the symbol for boulder).

As we want to load and save our Sokoban boards, we also need a serialiser that generates sok files from Sokoban boards.  The final step is a model-to-text transformation and Xtend provides a really nice template language for this kind of job.  Take a peek at Serialiser.xtend in sokobanExchangeFormat under /src/org.emoflon.ibex.handbook.serialiser/.  You don’t need to understand everything — the main idea is simply to visit the recursive structure and print out the corresponding symbol for every field.

Both Xtext and Xtend integrate relatively smoothly with Java.  Take a look at how the parser and serialiser are invoked in and , respectively (both in  sokobanExchangeFormat under /src/org.emoflon.ibex.handbook.api/).

If you’re an Xtext/Xtend whiz, you might be wondering why we don’t simply implement the complete text-to-board and board-to-text transformation in the Xtext parser and Xtend serialiser, respectively.  Although this should be possible (our example is not that complex), a divide-and-conquer strategy is still often a good idea as it breaks up the task into multiple, (hopefully) easier sub-tasks.  This does not only reduce complexity but also makes things more flexible.  In this case, the parser/serialiser is largely independent of our choice of metamodel for representing Sokoban boards as used by the GUI.  We are thus free to choose each of the metamodels to be as suitable as possible for the different concerns:  a recursive tree-like structure for parsing/serialising versus a flat, highly connected and richly typed graph for validating and implementing the rules of Sokoban (using graph constraints and graph transformations).

An overview of the required transformation chain

As depicted below, we now have two different representations of Sokoban puzzles and need to transform back and forth if we want to be able to import and export sok files in and from our GUI.
For the rest of the handbook, let’s agree to refer to sokobanExchangeFormat as our source metamodel, and SokobanLanguage as our target metamodel, so we can talk sensibly about forward and backward transformations. 
Although we could program both forward and backward directions in Java or as a graph transformation (as you have worked through +Unidirectional Model Transformation with eMoflon::IBeX ), we shall learn in this handbook that TGGs are a convenient way of implementing such multi-directional transformations involving two different metamodels.