| # 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

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