au.edu.monash.csse.tonyj.cider.interpreter
Class Interpreter

java.lang.Object
  |
  +--Interpreter

All Implemented Interfaces:

ConstraintVariableListener, java.util.EventListener

public abstract class Interpreter

extends java.lang.Object

implements ConstraintVariableListener

The Interpreter is the main control class in the CIDER toolkit that maintains a parse forest representation of a diagram, is responsible for applying productions, and also controls the application of transformations. It as an abstract base class that is extended by a grammar-specific class that is responsible for implementing functionality that is grammar dependent. This grammar-specific class is produced by the CIDER compiler. Note that when an instance of this class is created, auto forest checking and auto constraint solving are initially turned on.

Important change from version 0.2.0: The load() and save() methods have been removed. Loading and saving functionality must now be implemented by the application developer. For example, to save, all terminal symbols (and their attribute values) can be written to a file (in a format that the application developer is free to choose). Then, to load again, each terminal symbol (and their attribute values) can be read in and added to an instance of the Interpreter class, and the associated parse forest will be automatically generated.

Field Summary

static java.lang.String

VERSION

Method Summary

void	addGrammarSymbolListener(GrammarSymbolListener gsl) Adds an listener to listen for grammar symbol events.
boolean	addTerminalSymbol(GrammarSymbol symbol) Adds a terminal symbol to the parse forest.
void	applyForceDirectedLayout(int timeStep) Invokes the force directed layout algorithm to be performed on the diagram.
abstract boolean	applyTransformation(int transformation) Applies a specified transformation to the parse forest at the first valid location it finds.
abstract boolean	applyTransformationInParallel(int transformation) Applies a specified transformation to the parse forest in parallel.
abstract boolean	applyTransformationWithMapping(int transformation, boolean parallel, java.util.Map candidatesMap) Applies a specified transformation to the parse forest with a specified symbol mapping.
void	checkForest() Checks all productions and updates all attributes in the parse forest that require it.
void	disableUndo() Turns off the ability to undo actions.
void	enableUndo() Turns on the ability to undo actions.
abstract void	evaluateProductionRules() Explicitly calls the grammar-specific interpreter to evaluate the production rules.
java.util.Set	getAllSymbols() Returns a set containing all symbols in the parse forest.
javax.swing.JComponent	getJComponent() Returns the JComponent associated with the visual representation of the diagram being stored by this Interpreter instance (or null if there is none).
int	getUndoIndex() Returns the index to the most recent action recorded on the undo action list.
boolean	isAutoConstraintSolvingOn() Returns true if auto constraint solving is on, false otherwise.
boolean	isAutoForestCheckingOn() Returns true if auto forest checking is on, false otherwise.
boolean	isUndoEnabled() Returns true if the undo feature is currently enabled, false otherwise.
boolean	isUpToDate() Returns true if the parse forest is up to date, false otherwise.
void	printForest(java.io.PrintStream stream) Prints the parse forest.
void	reevaluateForest() Reevaluates all productions in the parse forest.
void	removeGrammarSymbolListener(GrammarSymbolListener gsl) Removes a listener that listens for grammar symbol events.
boolean	removeSubTree(GrammarSymbol symbol) Removes from the parse forest the sub tree of this symbol.
boolean	removeTerminalSymbol(GrammarSymbol symbol) Removes a terminal symbol from the parse forest.
void	resolve() Calls the constraint solver resolve method.
void	setAutoConstraintSolving(boolean on) Allows auto constraint solving to be turned on or off.
void	setAutoForestChecking(boolean on) Allows auto forest checking to be turned on or off.
void	setForceDirectedLayoutParameters(double springEquilibriumDistance, double particleRepulsionConstant, double springConstant) This methods sets the parameters for force directed layout.
void	setJComponent(javax.swing.JComponent jc) This method is invoked by the constructor of an InterpretedTokenCanvas.
static void	setLoggingLevel(java.util.logging.Level level) Allows the logging level for the CIDER logger to be set.
void	solve() Calls the solver to solve all constraints.
boolean	undoActions(int index) Will undo actions that occurred after a specific time, as indicated by the index value.
void	variableModified(ConstraintVariableEvent event) Implemented for an internally used interface.

Methods inherited from class java.lang.Object

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

Field Detail

VERSION

public static final java.lang.String VERSION

See Also:

Constant Field Values

Method Detail

applyForceDirectedLayout

public void applyForceDirectedLayout(int timeStep)

Invokes the force directed layout algorithm to be performed on the diagram.

Parameters:

timeStep - The time (in milliseconds) between animation steps. Note that this is the minimum time - calculation of the next layout iteration may take longer than the value specified.

setJComponent

public void setJComponent(javax.swing.JComponent jc)

This method is invoked by the constructor of an InterpretedTokenCanvas. It should not be invoked at any other time.

getJComponent

public javax.swing.JComponent getJComponent()

Returns the JComponent associated with the visual representation of the diagram being stored by this Interpreter instance (or null if there is none). Typically, this should be an instance of an InterpretedTokenCanvas.

setForceDirectedLayoutParameters

public void setForceDirectedLayoutParameters(double springEquilibriumDistance,
                                             double particleRepulsionConstant,
                                             double springConstant)

This methods sets the parameters for force directed layout.

Parameters:

springEquilibriumDistance - The equilibrium distance that the spring force tries to achieve between graph nodes that are connected by a graph edge. Default value is 25.0

particleRepulsionConstant - Used to calculate the repulsive force between each pair of graph nodes (both connected and unconnected), which drops of quadratically as the distance between nodes increases. Default value is 400.0
Force = ParticleRepulsionConstant / (Distance * Distance)

springConstant - Used to calculate spring force between connected graph nodes. Default value is 0.5
Force = SpringConstant * | Distance - SpringEquilibriumDistance |

setLoggingLevel

public static void setLoggingLevel(java.util.logging.Level level)

Allows the logging level for the CIDER logger to be set. By default, the logging level is set to Level.INFO. Logging can be turned off by using Level.OFF, and all messages will be logged if Level.ALL is used.

Parameters:

level - The logging level to be set.

evaluateProductionRules

public abstract void evaluateProductionRules()

Explicitly calls the grammar-specific interpreter to evaluate the production rules.

applyTransformation

public abstract boolean applyTransformation(int transformation)
                                     throws java.lang.IllegalArgumentException

Applies a specified transformation to the parse forest at the first valid location it finds.

Parameters:

transformation - The transformation to be applied.

Returns:

true if the transformation was successful, false otherwise.

Throws:

java.lang.IllegalArgumentException - If an unknown transformation is specified.

applyTransformationInParallel

public abstract boolean applyTransformationInParallel(int transformation)
                                               throws java.lang.IllegalArgumentException

Applies a specified transformation to the parse forest in parallel. That is, it will find all the locations in the parse forest where the transformation can be applied, and then in a single step apply the transformation at all of these locations.

Parameters:

transformation - The transformation to be applied.

Returns:

true if the transformation was successful, false otherwise.

Throws:

java.lang.IllegalArgumentException - If an unknown transformation is specified, or a a transformation is specified that cannot be applied in parallel (such as a compound transformation).

applyTransformationWithMapping

public abstract boolean applyTransformationWithMapping(int transformation,
                                                       boolean parallel,
                                                       java.util.Map candidatesMap)
                                                throws java.lang.IllegalArgumentException

Applies a specified transformation to the parse forest with a specified symbol mapping.

Parameters:

transformation - The transformation to be applied. Must be a basic transformation (not a disjunction or compound transformation).

parallel - true applies the transformation in parallel, false does not.

candidatesMap - Contains a mapping of String objects to Set objects. Each String object should be the name of an input or referable existential symbol in the transformation specified (as it appears in the input specification). The corresponding Set object should contain a collection of candidate symbols, each of which must be of the correct type. That is, if the name corresponds to a symbol of type Circle, the Set should only contain Circle objects.
Any input or referable existential symbols not accounted for in the mapping will be chosen from the available symbols in the parse forest.

Returns:

true if the transformation was successful, false otherwise.

Throws:

java.lang.IllegalArgumentException - If an unknown transformation is specified, or the candidates mapping contains objects of the wrong type.

getAllSymbols

public java.util.Set getAllSymbols()

Returns a set containing all symbols in the parse forest.

addTerminalSymbol

public boolean addTerminalSymbol(GrammarSymbol symbol)

Adds a terminal symbol to the parse forest. If auto forest checking is turned on, the forest will be updated as necessary with the symbols from invalid productions removed, and the symbols from any new valid productions added. If successful, an event detailing this action will be launched.

Parameters:

symbol - The symbol to be added.

Returns:

true if successful, false if the symbol is not a terminal symbol, or is already present in the parse forest of this or another Interpreter.

removeTerminalSymbol

public boolean removeTerminalSymbol(GrammarSymbol symbol)

Removes a terminal symbol from the parse forest. If auto forest checking is turned on, the forest will be updated as necessary with the symbols from invalid productions removed, and the symbols from any new valid productions added. If successful, an event detailing this action will be launched.

Parameters:

symbol - The symbol to be removed.

Returns:

true if successful, false if the symbol is not a terminal symbol, or is not present in the parse forest of this Interpreter.

removeSubTree

public boolean removeSubTree(GrammarSymbol symbol)

Removes from the parse forest the sub tree of this symbol. The method will find all terminal symbols in the parse forest that compose the symbol given, and removes them. Then, automatic parse forest checking will see all dependent non-terminal symbols removed as well. The event notification system will inform of all parse forest modifications. The method assumes that the symbol provided is in the parse forest.

Parameters:

symbol - The symbol to be removed.

Returns:

true if successful, false if the symbol is not present in the parse forest of this Interpreter.

resolve

public void resolve()

Calls the constraint solver resolve method. Waits for all symbol updates before checking forest. Note that it will only work if auto constraint checking is turned on.
It is unlikely that this method will need to be called explicitly.

solve

public void solve()

Calls the solver to solve all constraints. This method should be called if constraints have been added or removed. Note that it will only work if auto constraint checking is turned on.
It is unlikely that this method will need to be called explicitly.

printForest

public void printForest(java.io.PrintStream stream)

Prints the parse forest. Primarily for debugging purposes.

Parameters:

stream - The output stream where the text is sent to.

isUpToDate

public boolean isUpToDate()

Returns true if the parse forest is up to date, false otherwise.

addGrammarSymbolListener

public void addGrammarSymbolListener(GrammarSymbolListener gsl)

Adds an listener to listen for grammar symbol events. Events are launched when symbols are added to or removed from the parse forest, and when their attributes are modified.

Parameters:

gsl - The listener to be added.

removeGrammarSymbolListener

public void removeGrammarSymbolListener(GrammarSymbolListener gsl)

Removes a listener that listens for grammar symbol events. Events are launched when symbols are added to or removed from the parse forest, and when their attributes are modified.

Parameters:

gsl - The listener to be removed.

isAutoForestCheckingOn

public boolean isAutoForestCheckingOn()

Returns true if auto forest checking is on, false otherwise. Auto forest checking means that each change that is made to the forest (via a symbol being added, removed or modified), will result in checks to ensure that the forest is in a valid state and up to date.

setAutoForestChecking

public void setAutoForestChecking(boolean on)

Allows auto forest checking to be turned on or off. Auto forest checking means that each change that is made to the forest (via a symbol being added, removed or modified), will result in checks to ensure that the forest is in a valid state and up to date. It should normally be turned on.

Parameters:

on - true to turn on, false to turn off.

isAutoConstraintSolvingOn

public boolean isAutoConstraintSolvingOn()

Returns true if auto constraint solving is on, false otherwise. Auto constraint solving means that the multi-way constraint solver will automatically enforce any constraints that it is responsible for, ensuring that the parse forest remains in a valid state.

setAutoConstraintSolving

public void setAutoConstraintSolving(boolean on)

Allows auto constraint solving to be turned on or off. Auto constraint solving means that the multi-way constraint solver will automatically enforce any constraints that it is responsible for, ensuring that the parse forest remains in a valid state. It should normally be turned on.

Parameters:

on - true to turn on, false to turn off.

checkForest

public void checkForest()

Checks all productions and updates all attributes in the parse forest that require it. If auto forest checking is turned on, this method will be called automatically when needed.

reevaluateForest

public void reevaluateForest()

Reevaluates all productions in the parse forest.

variableModified

public void variableModified(ConstraintVariableEvent event)

Implemented for an internally used interface. Listens for when a constraint variable has been modified by the multi-way constraint solver. This method should not be called directly.

Specified by:

variableModified in interface ConstraintVariableListener

isUndoEnabled

public boolean isUndoEnabled()

Returns true if the undo feature is currently enabled, false otherwise.

enableUndo

public void enableUndo()

Turns on the ability to undo actions. Since storing user actions takes up memory, the undo feature should only be enabled when necessary.

disableUndo

public void disableUndo()

Turns off the ability to undo actions.

getUndoIndex

public int getUndoIndex()

Returns the index to the most recent action recorded on the undo action list. Then, if further actions are carried out, it will possible to later undo all actions that occurred after the one whose index has been obtained, without going any further back (using the undoActions(int) method).

undoActions

public boolean undoActions(int index)

Will undo actions that occurred after a specific time, as indicated by the index value. Note that the undo feature allows for the fact that constraint variables may have been changed by the multi-way constraint solver.

Parameters:

index - The index in the undo action list (obtained from getUndoIndex()).

Returns:

true if successful, false if undo is not enabled, or an invalid index value is given.