View source for VIATRA2/UseCases/DebuggingAndVisualisation

= Transformation Debugging in VIATRA2 =
The VIATRA2 framework does not contain a dedicated debugger, but there are other features that can be used to support debugging. These are:
* Output rules
* The VIATRA Console
** Undoable Transformations
** Executing Single Rules
* Model Space Visualisation

== Output rules ==
The <code>print</code> and <code>println</code> rules can be used to output the value of any selected transformation program variable to the output. A typical use would be to output the matches of the precondition in the action part of a graph transformation rule:

 gtrule rule(in Token) = {
   precondition find token(Token)
   action {
      println(Token);
   }
 }

== The VIATRA Console ==
The VIATRA framework provides a ''VIATRA2 Console'' view that is capable of displaying the messages of the framework, and allowing the execution of commands. By default the ''debug'' messages are disabled because of their possible large number - it is only recommended to turn it on while it is explicitely needed. Furthermore, the display of "debug", "info", "warning" and "error" messages can be turned on-off using the toggle buttons on the top right part of the toolbar of the VIATRA Console view. The red X button is used to clear the contents of the console buffer.

The commands of the console can be listed used the <code>listcommands</code> code together with a short description. Console commands can take an arbitrary number of parameters, which need to be separated by commas for invocation.  

The Console supports command name auto-completion (in the text input field on the bottom may be used to enter commands), by using the tab key. Additionally, the console features a command history (press the UP and DOWN arrow keys in the command entry field) for convenience.
  
[[Image:VIATRA2_UseCases_Console.png]]

=== Executing transformations and single rules ===
Transformations may be invoked using the <code>runmachine</code>. As the first parameter, you need to supply the fully qualified ID of the machine (namespace and name, separated with dots; as it is displayed in the VIATRA2 Model Spaces view), and a semicolon-separated list of parameter name=value pairs (if the machine's main rule takes parameters). An example:

  runmachine(notions.transformer,Model=notions.model.01_preliminaries;Target=latex.model)
  > runmachine([notions.transformer, Model=notions.model.01_preliminaries;Target=latex.model])

The console will echo a parsed version of your command as the first feedback line of execution.

During debugging, a transformation developer may need to run only a single ASM rule of the transformation program, instead of the entire machine. The <code>runrule</code> allows executing a single rule of the transformation on the current model space, the parametrization is the same as for <code>runmachine</code>

=== Undoable Transformations ===
When [[VIATRA2/GettingStarted/Using_Transformations|you execute a transformation program]] from the user interface of VIATRA2, it may change the model space (although these changes are not automatically saved). However, during transformation development, it is a common need to execute the same transformation program on the same model, so it is useful to be able to revert the changes after a transformation has been executed.

To achieve this, the <code>runmachineundoable</code> and <code>runruleundoable</code> commands can execute ASM machines or a single ASM rule in a way that the <code>undotransaction</code> command can undo all of their changes. This technique speeds up the debugging process by eliminating the need to close and re-open model spaces.

An example interaction sequence may look like this:

  runmachineundoable(notions.transformer,Model=notions.model.01_preliminaries)
  > runmachineundoable([notions.transformer, Model=notions.model.01_preliminaries])
  [info] Entity successfully interpreted.
  [info] Trigger engine: A transactional operation ended in the system.
  [info] Transformation engine ran for 61 milliseconds.
  [info] Transformation transaction ID: TRANS_4
  
  undotransaction(TRANS_4)
  > undotransaction([TRANS_4])
  [info] Trigger engine: A transactional operation ended in the system.

In this sequence, we first execute the "notions.transformer" transformation (using an input parameter mapping where the "Model" parameter takes the value of "notions.model.01_preliminaries") in an undoable transaction, and then undo this transaction to ensure that the state of the model space is restored to its original (before the transformation was executed).

=== Command scripts ===
The VIATRA Console has the ability to save a history of executed commands into line-delimited textual files ("command scripts"), by calling the ''savecommandscript'' built-in command. These scripts can be later loaded and automatically executed, by the ''executecommandscript'' built-in command. You can use this facility as a light-weight batch execution environment for e.g. importing models (''nativeimport''), executing rules or transformations (''runmachine'') etc. 

=== Extending the VIATRA Console with new commands ===

The VIATRA Console can be extended with new commands easily using the <code>org.eclipse.viatra2.gui.consoleCommandProvider</code> extension point. You need to provide two components:
 * a command implementation class, implementing the <code>IVIATRAConsoleCommandProvider</code> interface
 * a command factory that adds your command classes to the system

See a few simple, self-explanatory examples below:

==== MANIFEST.MF ====

  Require-Bundle:
   org.eclipse.viatra2.gui;bundle-version="3.1.0",

==== Command implementation ====

  import org.eclipse.viatra2.frameworkgui.views.console.commands.IVIATRAConsoleCommandProvider;
  public class YourCommand implements IVIATRAConsoleCommandProvider {
   public void executeCommand(IFramework fw, List<String> parameters) {
    /* implementation */ 
   }
   /* displayed in the list of commands generated by the >>listcommands<< built-in command */
   public String getCommandSignature() {
    return "functionName(someParameter)";
   }
   public String getDescription() {
    return "...";
   }
   public String getHelpText() {
    return "...";
   }
  }

==== Command Factory ====

  import org.eclipse.viatra2.frameworkgui.views.console.commands.IVIATRAConsoleCommandProviderFactory;
  public class YourCommandFactory implements IVIATRAConsoleCommandProviderFactory {
   public List<IVIATRAConsoleCommandProvider> getProviders(IFramework fw) {
    ArrayList<IVIATRAConsoleCommandProvider> ps = new ArrayList<IVIATRAConsoleCommandProvider>();
    ps.add(new YourCommand());
    return ps;
   }

==== plugin.xml ====

  <extension point="org.eclipse.viatra2.gui.consoleCommandProvider">
   <commandProviderFactory
     class="sample.YourCommandFactory">
   </commandProviderFactory>
  </extension>

== Model Space Visualisation and Debugging ==
The [[VIATRA2/ExtraFeatures/ModelVisualisation|model space visualisation component]] can be used to view a part of the model space as a graph, and it also reacts to changes of the model space: when a displayed model element changes (e.g. after the execution of a rule it is deleted), the changes are immediately reflected on the visualisation (e.g. the related node is deleted).

It is important to note that the model space visualisation component only helps to understand the actual state of the model space, but it does not contain any option to alter it.