mapss.dif.language
Class Reader

java.lang.Object
  mapss.dif.language.Reader

public class Reader
extends java.lang.Object

DIF Reader class. Top level class for reading DIF files and converting them to graphs. Input of this structure is a DIF (Dataflow Interchange Format) text. Output is a list of hierarchies or DIF graphs.

To read a DIF file, first a Reader object should be initialized for that file. Then compile() function should be called. The compiler will compare the types of graphs read with the ones defined in file "analysers.txt" which is in the same package as this class. If it finds a type match it will construct the appropriate graph whose runtime type is as defined in the DIF file otherwise it will skip the graph. Although Reader class can find default analysis classes from "analysers.txt", it is not necessary to use the default analysers. compile(mapss.dif.language.LanguageAnalysis[]) method can be used to pass custom LanguageAnalysis classes to the Reader. This overrides the analysis classes defined in "analysis.txt".

Information about the DIF file is not cached therefore compile method can be called after modifying the original file to apply the changes.

GNU C preprocessor commands are available for this reader. In order to use multiple files for related graphs #include command can be used. CPP documentation is available at http://gcc.gnu.org/onlinedocs/cpp/. GNU CPP version 2.95.3-5 (cygwin special) was used during the development of this class. cpp(java.lang.String) method requires the format generated by this version. For using a different preprocessor version check its documentation.

Hierarchical relationships between different kinds of graphs are regulated according to the rules in LanguageAnalysis._acceptableSubHierarchy(mapss.dif.DIFHierarchy).

For more information on this package see the package documentation and LanguageAnalysis. The following codes illustrate the usage of Reader:

Reader reader = new Reader(fileName);
reader.compile();
DIFHierarchy topHierarchy = reader.getTopHierarchy();

Version:

$Id: Reader.java 362 2007-02-25 21:08:57Z plishker $

Author:

Fuat Keceli, Chia-Jui Hsu

See Also:

LanguageAnalysis, Writer, DIFHierarchy, DIFGraph

Field Summary

protected LanguageAnalysis[]	_analysers Set to an array of default analysers defined in "analysers.txt" if compile() is used.
protected java.lang.String	_fileName

Constructor Summary

Reader(java.lang.String fileName)
Constructs a Reader for this file.

Method Summary

void	addAnalyser(LanguageAnalysis analyser) Add new LanguageAnalysis subclass object to the analysers.
void	addOptions(java.lang.String[] options) Adds options to the preprocessor.
void	compile() Default compiler using default keywords defined in "analysers.txt" under mapss.dif.language.
void	compile(LanguageAnalysis[] analysers) Compiler with custom analysers.
java.util.LinkedHashMap	cpp(java.lang.String fileName) Seperates all files that the given file depends on by processing the output from "cpp fileName " command.
java.util.Collection	getGraphs() Returns the graphs read during compilation as a collection of DIFGraph objects.
java.util.Collection	getHierarchies() Returns the graphs read during compilation as a collection of DIFHierarchy objects.
DIFHierarchy	getTopHierarchy() Returns the top level hierarchy of a dif specification.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

_fileName

protected java.lang.String _fileName

_analysers

protected LanguageAnalysis[] _analysers

Set to an array of default analysers defined in "analysers.txt" if compile() is used. Not set if custom LanguageAnalysis objects are used.

Constructor Detail

Reader

public Reader(java.lang.String fileName)
       throws java.io.IOException

Constructs a Reader for this file. File content is not cached so file can be changed and compiled multiple times. The constructor also reads the "analysers.txt" file to find the default graph types for this reader.

Throws:

java.io.IOException - If "analysers.txt" could not be read.

Method Detail

addAnalyser

public void addAnalyser(LanguageAnalysis analyser)

Add new LanguageAnalysis subclass object to the analysers. In case a particular LanguageAnalysis subclass is not specified in analysers.txt, this method can be used.

Parameters:

analyser - The LanguageAnalysis subclass object.

addOptions

public void addOptions(java.lang.String[] options)

Adds options to the preprocessor. Options will be added to the end of the command.

Parameters:

options - Options to add to the preprocessor. Each word should be provided as an element in the array. Words are seperated by whitespaces.

compile

public void compile()
             throws java.io.IOException,
                    DIFLanguageException

Default compiler using default keywords defined in "analysers.txt" under mapss.dif.language.

This function first pre-processes file by first running cpp(java.lang.String).

Throws:

java.io.IOException - If there is a problem reading the input file.

DIFLanguageException - If there is a parse problem in the dif file.

compile

public void compile(LanguageAnalysis[] analysers)
             throws java.io.IOException,
                    DIFLanguageException

Compiler with custom analysers. An array of analysers are provided so reader will choose which analysis to use with which type of graph.

This function first pre-processes file by first running cpp(java.lang.String).

Parameters:

analysers - An array of different analysers to use with the compiler. Behaviour is not defined if same type of analysis is defined more than once in this array.

Throws:

java.io.IOException - If there is a problem reading the input files.

DIFLanguageException - If there is a parse problem.

cpp

public java.util.LinkedHashMap cpp(java.lang.String fileName)
                            throws java.io.IOException,
                                   DIFLanguageException

Seperates all files that the given file depends on by processing the output from "cpp fileName " command. Returned value has file names as keys and text inside the files as values. An iterator on the keys will return the given file first. Order of rest of the files follows the depedency tree that starts from the given file (hence files with no dependencies will be returned last).

This method assumes that cpp uses the # lineNumber fileName flag format for the output (with whitespace between # and lineNumber). Also it uses "cpp -M fileName " command to check for errors. It is assumed that if there are no errors, returned text has at least one semicolon character in it.

For details and compliance of the cpp version in your system see gnu cpp web site.

Parameters:

fileName - File to compile

Returns:

A map of file names to preprocessed text.

Throws:

java.io.IOException - If any of the files cannot be read.

DIFLanguageException

getGraphs

public java.util.Collection getGraphs()

Returns the graphs read during compilation as a collection of DIFGraph objects. Runtime types of the graphs are as read from the DIF file. (e.g. If "sdf" keyword is found for a graph graph type will be SDFGraph)

Note that this form doesn't contain any information about hierarchical relations between the graphs read.

Returns:

A collection of DIFGraphs.

See Also:

DIFGraph

getHierarchies

public java.util.Collection getHierarchies()

Returns the graphs read during compilation as a collection of DIFHierarchy objects. Runtime types of the graphs contained in those objects are read from the DIF file.

Returns:

A collection of DIFHierarchy objects.

See Also:

DIFHierarchy

getTopHierarchy

public DIFHierarchy getTopHierarchy()

Returns the top level hierarchy of a dif specification. If a dif specification consists of multiple separate hierarchies (graphs), this method returns the last one.

Returns:

The top level hierarchy.