The mmatrix Tool


The mmatrix  tool was created in response for tool support to classify .jak files in order to get a better overall view of an AHEAD design.  As a general rule, it is not called from the command line, but rather invoked by other AHEAD tools.

Overview

mmatrix classifies .jak files and their contents into the following groups:

"C"       a class
"I" an interface
"S" a state machine
     
"K" a constructor
"M" a method
"F" a field
"S"   a state
"T"   a transition
     
"D"   defines C/I/S
"E"   defines and extends C/I/S
"R" refines C/I/S

mmatrix outputs other information as well.  See the example below.

Example

Consider the following .jak file:

public class VoidTyp extends PrimitiveType {

   final public static int ARG_LENGTH = 1 /* Kludge! */ ;
   final public static int TOK_LENGTH = 1 ;

   public boolean[] printorder () {
      return new boolean[] {true} ;
   }

   public VoidTyp setParms (AstToken tok0) {
      arg = new AstNode [ARG_LENGTH] ;
      tok = new AstTokenInterface [TOK_LENGTH] ;
      tok [0] = tok0 ; /* "void" */
      InitChildren () ;
      return (VoidTyp) this ;
   }
}

The output of mmatrix after it translates this file into:

C E VoidTyp
Line range (-1, -1)
public endMods
 beginKeys
Classes :( PrimitiveType ):
super :( PrimitiveType ):
 endKeys
 beginNest
	F D ARG_LENGTH int
	Line range (10, 10)
	final public static endMods
	 beginKeys
	finalValue :( = 1 ):
	 endKeys
	F D TOK_LENGTH int
	Line range (11, 11)
	final public static endMods
	 beginKeys
	finalValue :( = 1 ):
	 endKeys
	M D printorder() boolean[]
	Line range (13, 16)
	public endMods
	M D setParms(AstToken) VoidTyp
	Line range (18, 27)
	public endMods
endNest

The above says:

Command-Line Invocation

To call mmatrix from the command line, type:

> mmatrix
mmatrix <arguments>
-t (traverse directory ..)
-c (remove unnecessary attributes)
<file> (run mmatrix on input file)

So a typical invocation of mmatrix is:

> mmatrix

The -t and -c options have recently been added to extract a simple parsable output for mmatrix.  The -t option means consider the current directory a model directory, and recursively traverse this directory and its layers for all .jak files.  Invoke mmatrix on each .jak file found.  The -c option doesn't print finalValue and Classes output (which can be seen in the above example).  The bali grammar of the mmatrix output in -tc mode is given in this file.

Programmatic Invocation

To call mmatrix from within a program, use:

import mmatrix.*;
...
try {
   String out = mmatrix.Main.eval( "file.jak" );

   // out = any of the above constants, which can be referenced by mmatrix.Constants.X,
   // where X is Class, ExtendsClass, Interface, ExtendsInterface, StateMachine,
   //            ExtendsStateMachine, or Refines

   // do something with out...
}
catch (Exception e) {
   System.out.println("error in processing file.jak" );
   System.out.println(e.getMessage());
   System.exit(1);
}

In general, mmatrix was designed for programmatic, rather than command-line use.  It is the underlying tool used by ModelExplorer.

Caveats

It is possible that mmatrix doesn't harvest information correctly on state machines.  It has, however, been thoroughly tested with classes and interfaces.


ATS Home Page

Copyright Software Systems Generator Research Group. All rights reserved.
Revised: January 25, 2006.