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
Example
Command-Line Invocation
Programmatic Invocation
Caveats

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:

VoidTyp is a class that extends another class.
Line range (-1,-1) means the entire file
it is public and has PrimitiveType as its superclass
Inside Voidtype is:
- public static int field ARG_LENGTH whose definition is on line range (10,10) with final value =1
- final public static int field TOK_LENGTH whose definition is on line range (11,11) with final value =1
- public boolean[] method printorder whose definition is on line range (13,16)
- public VoidTyp method setParms(AstToken) whose defintion is on line range (18,27)

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