XMG/XMGExtractor

Un article de Loria Wiki.

Sommaire 1 What is it? 2 Installation 2.1 Pre-requisites 2.1.1 Java 1.5 2.1.2 GraphViz/Dot 2.2 XMGExtractor 2.3 Update 2.4 Make it available everywhere 3 How to use it 3.1 Launching 3.2 Graph key 3.3 Nodes graph key 3.4 Get class information 3.5 Choose inheritance view 3.6 Highlighting 3.7 Save/Print 4 Problems you may encounter 5 Contact

What is it?

The purpose of the program is to extract information from an XMG metagrammar source file, and represent them graphically.

Installation

Pre-requisites

In order to use XMGExtractor, you need to install some programs first.

Java 1.5

XMGExtractor has been developed with Java 5.0, so you need to install the Java Runtime Environment (JRE) 5.0. You can find it on the Java website (http://java.sun.com, then go to Downloads -> Java SE -> Previous Releases -> J2SE 5.0 Downloads) or easier, follow this link: http://java.sun.com/javase/downloads/index_jdk5.jsp.

If you are under a Unix system, you can also go to your package manager (like Synaptic), search "sun-java5-jre" and install it.

You can also type in a terminal:

sudo apt-get install sun-java5-jre

Note: If you are using the non-compiled version of XMGExtractor, you will need the Java Development Kit (JDK) instead of the Java Runtime Environment (JRE).

GraphViz/Dot

GraphViz is an open source graph visualization project from AT&T Research. dot, a GraphViz program which can create diagrams and graphs, is used by XMGExtractor to create the classes tree. More information on GraphViz on the official website http://www.graphviz.org/.

To install it under a Unix system, it's very easy. Just select GraphViz in your package manager and install it, or type in a terminal:

sudo apt-get install graphviz

Under Windows, download and install GraphViz. Then, you have to put the dot program in your %PATH variable.

!!TODO !!

XMGExtractor

• If you are using the compiled version of XMGExtractor, it's ok.

• If you are using the non-compiled version, you must compile it before using it. Open a terminal and go to the XMGExtractor directory. Then type:

./Compile

If you have:

Compiling...
Done

, the compilation is successful. If you have error messages, check that you have Java 5.0 installed and set as your default Java compiler. To check your Java version, type in a console:

java -version

You should have this on the screen:

java version "1.5.0_11"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_11-b03)

Update

When updating from the repository, don't forget to launch the compile script:

./Compile

Make it available everywhere

How to make XMGExtractor able to launch from anywhere? Just add 3 lines at the end of your .bashrc file (in your home directory)

export xmgPath="PATH_OF_XMGEXTRACTOR"
export PATH="$PATH:$xmgPath"
export CLASSPATH="$CLASSPATH:$xmgPath"

where "PATH_OF_XMGEXTRACTOR" is the path in the repository where XMGExtractor is. For example, for me it's:

/users/led/ambrosib/local_repository/trunk/XMG-TOOLS/XMGExtractor

and so, my three lines are:

export xmgPath="/users/led/ambrosib/local_repository/trunk/XMG-TOOLS/XMGExtractor"
export PATH="$PATH:$xmgPath"
export CLASSPATH="$CLASSPATH:$xmgPath"

How to use it

Launching

In a terminal, type:

./XMGExtractor

You can also give the metagrammar in argument:

./XMGExtractor metagammar_file.mG

Graph key

This little example metagrammar:

class Parent1

class Parent2

class Parent3

class Child
import Parent1[]
{
	Parent2[]
}

class LittleChild1
import Child[]

class LittleChild2
{
	Child[] | Parent3[]
}

Gives this graph:

XMG classes are represented by a rectangle. Import clauses are represented with full lines. Instantiated classes from a conjunction are represented with dotted lines, and disjunctions are represented with dashed lines.

This is the graph when the class tree is highlighted. Parent classes become orange filled rectangles, with orange lines, and son classes become beige, with green lines. The class you requested highlight becomes blue. Classes which are not in the class tree don't change.

Nodes graph key

This little example class:

class VerbalArgument
import SentenceHead[]
export nArg
declare ?nArg ?fX ?fY
{
    <syn>{
        node nArg[cat= fX, funct= fY];
        nS -> nArg
        nS -> before
        before >> nArg
        nS ->+ farSon
        nS ->* farOrEqual
        before = plop;
    }     
}

Gives this nodes graph:

So you can see that:

• Strict dominance is represented by a single line
• Strict large dominance is represented by a dashed line
• Large dominance is represented by a dotted line
• When precedence is used, concerned nodes are colored
• When there is a node equation, the two nodes are linked with two arrows

Get class information

Select a class in the class list, on the right of the application, by left-clicking on the class name. Class information appears on the top of the program. To show information of another class, just click on another class name.

You can also show these information in a new window. To do so, right-click on the class name and select "Show class info". A new window will be opened. You can open as many windows as you want.

Note: You can hide the class list in the menu "View". You can also hide the class information panel.

The class' identifiers are represented in 4 separated lists:

• a declared/exported identifiers list
• an explicit inherited identifiers list
• an implicit inherited identifiers list
• an instantiated identifiers list

In the declared/exported list, the exported identifiers are highlighted: they have an orange background color in the list. You can see a screenshot of that:

Also, in the explicit and the implicit identifiers list, when you clic on an identifier, the label "Identifier's owner class" is updated and indicate where does the identifier come from.

Choose inheritance view

In the "View" menu, you can choose what you want on your graph:

• Inheritance classes: only import links will be represented on the graph
• Inheritance & instantiation: import links and conjunction instantiation links will be on the graph
• Disjunction: only disjunction instantiation links will be represented
• All: all kind of links will be represented

Highlighting

You can highlight a class tree, or a part of the tree, in the main graph view or in a new window.

• If you want to highlight in the main graph view, the class tree you decided to highlight will be coloured and all other classes won't change. To do this, right-click on the class name in the class list, and go to the "Highlight" sub menu. Then, choose what you want to highlight.

• If you want to highlight in a new window, the class tree you decided be coloured and there will be only this class tree on the graph. To do this, right-click on the class name in the class list, and go to the "Highlight (new window)" sub menu. Then, choose what you want to highlight.

Save/Print

You can save the main graph in the "File" menu. The file will be save in the PNG format, with the .png extension. You can't print this graph (it's obviously too big).

You can also save the highlighted class graph that you opened in a new window: the new window also have a file menu, where you can save (also in the PNG format) or print the graph.

Problems you may encounter

Exception in thread "main" java.lang.ClassFormatError: xmg.XMGExtractor
(unrecognized class file version)
   at java.lang.VMClassLoader.defineClass(libgcj.so.70)
   at java.lang.ClassLoader.defineClass(libgcj.so.70)
   at java.security.SecureClassLoader.defineClass(libgcj.so.70)
   at java.net.URLClassLoader.findClass(libgcj.so.70)
   at gnu.gcj.runtime.SystemClassLoader.findClass(libgcj.so.70)
   at java.lang.ClassLoader.loadClass(libgcj.so.70)
   at java.lang.ClassLoader.loadClass(libgcj.so.70)
   at gnu.java.lang.MainThread.run(libgcj.so.70)

This is because you don't have the right version of the Java Runtime Environment. Remember that you need Java JRE 5.0. If it is installed, check that it is your default Java application launcher.

Contact

Any bug or question?

Contact: brice dot ambrosiak at loria dot fr or yannick dot parmentier at loria dot fr