org.silence.smushcode
Class Expression

java.lang.Object
  |
  +--org.silence.smushcode.Expression

Direct Known Subclasses:

CompoundExpression, EmptyLiteral, NumericLiteral, SMUSHFunction, StringLiteral

public class Expression

extends java.lang.Object

Expression is the heart of the SMUSHcode75 system. Every SMUSHcode75 statement is parsed and executed by a subclass of Expression. NOTE: Expression should never be instantiated directly. When a SMUSHcode75 statement is to be stored in memory, it should be passed through Expression.classify(). The resulting Expression-derived object is of the proper class to hold the statement.

Version:

org.silence.smushcode v1.0

Author:

Sam Clippinger (samc (at) silence (dot) org)

See Also:

classify(org.silence.smushcode.ExpressionCache, java.lang.String)

Field Summary

protected boolean	constantExpr Stores if this object returns a constant value regardless of context.
protected java.lang.String	constantValue Stores the value returned by this object during evaluation if this object always returns a constant value regardless of the context it was called from.
protected ExpressionCache	exprStoreLink Stores a link back to the cache for this instantiation of the SMUSHcode75 system.

Constructor Summary

Expression()
Creates an empty SMUSHcode75 statement.

Expression(ExpressionCache newCache, java.lang.String newExpr)
This constructor creates a base Expression with the contents newExpr.

Method Summary

static Expression	classify(ExpressionCache newLink, java.lang.String newString) Most of the magic in Expression takes place here.
java.lang.String[]	evaluate(ExpressionCaller callerLink) Calls Expression.evaluate(ExpressionCaller, Vector) with a request only for the output of the evaluated functions, not the original SMUSHcode75 statements as well.
protected java.util.Vector[]	evaluate(ExpressionCaller callerLink, java.util.Vector[] evalProgress) Drives the evaluation of the SMUSHcode75 statements and should be overridden in each class to provide unique functionality.
protected void	findConstancy() Determines if this object will always return the same value regardless of its context.
protected boolean	getConstancy() Returns the value of constantExpr.
boolean	logic(ExpressionCaller callerLink) Determines if the value stored in the Expression is "true" or "false" in SMUSHcode75 terms.
static boolean	logic(java.lang.String input) Determines if the value passed is "true" or "false" in SMUSHcode75 terms.
java.lang.String	noExec() In Expression's subclasses, noExec() returns the SMUSHcode75 statement stored in the object.
static java.util.Vector	separate(ExpressionCache newLink, java.lang.String newExpr, char separator) Primarily for use by the constructors of Expression-derived classes, separate() will pick out the parameters to the SMUSHcode75 statement and pull them apart.
protected void	setLink(ExpressionCache newLink) Provides a way to set this object's pointer to an ExpressionCache object after it has been instantiated.
java.lang.String	toString(ExpressionCaller callerLink) The SMUSHcode75 statement stored in the object is evaluated and its result is returned.
java.lang.String[][]	traceExec(ExpressionCaller callerLink) Calls Expression.evaluate(ExpressionCaller, Vector) with a request for both the output of the stored statement and the SMUSHcode75 expression that produced it.

Methods inherited from class java.lang.Object

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

Field Detail

constantValue

protected java.lang.String constantValue

Stores the value returned by this object during evaluation if this object always returns a constant value regardless of the context it was called from. If this variable is null, the it is assumed that either (1) the object does not return a constant value regardless of context or (2) the object returns a constant value regardless of context but has not yet been evaluated.

exprStoreLink

protected ExpressionCache exprStoreLink

Stores a link back to the cache for this instantiation of the SMUSHcode75 system. It would be cleaner to have this passed in at instantiation-time similar to the way that ExpressionCaller is passed in during evaluation-time, but several SMUSHcode75 functions need this value at evaluation-time and passing it in twice is even less elegant than storing it.

constantExpr

protected boolean constantExpr

Stores if this object returns a constant value regardless of context. This variable should always be updated at instantiation-time. It is true by default (for no particular reason).

Constructor Detail

Expression

public Expression()

Creates an empty SMUSHcode75 statement. This constructor should never be called. The Expression resulting from this constructor will not take advantage of the cache system or become an Expression-derived object that properly stores/evaluates its data. classify() should be used instead.

See Also:

classify(org.silence.smushcode.ExpressionCache, java.lang.String)

Expression

public Expression(ExpressionCache newCache,
                  java.lang.String newExpr)
           throws SMUSHInvalidExpressionException

This constructor creates a base Expression with the contents newExpr. It removes all comments, uppercase and whitespace from the SMUSHcode75 statement (except within the string literals). This constructor is typically called by classify() before it does its own processing of the statement.

Parameters:

newCache - a link back to the cache for this instantiation of the SMUSHcode75 system.

newExpr - the SMUSHcode75 statement to be stored in the new Expression

Throws:

SMUSHInvalidExpressionException - Generated if the SMUSHcode75 statement is invalid for some reason.

Method Detail

evaluate

public final java.lang.String[] evaluate(ExpressionCaller callerLink)

Calls Expression.evaluate(ExpressionCaller, Vector) with a request only for the output of the evaluated functions, not the original SMUSHcode75 statements as well.

Parameters:

callerLink - a link back to the ExpressionCaller that holds this instance's evaluation stack.

Returns:

an array containing the output of every SMUSHcode75 expression that was evaluated, in order from first to last. The final output is stored as the last element in the array.

See Also:

ExpressionCaller, org.silence.smushcode.Expression#evaluate(org.silence.smushcode.ExpressionCaller, java.lang.util.Vector)

traceExec

public final java.lang.String[][] traceExec(ExpressionCaller callerLink)

Calls Expression.evaluate(ExpressionCaller, Vector) with a request for both the output of the stored statement and the SMUSHcode75 expression that produced it.

Parameters:

callerLink - a link back to the ExpressionCaller that holds this instance's evaluation stack.

Returns:

a two-dimensional array containing the output of all the evaluated SMUSHcode75 statements in order from first to last, and the expressions that produced that output. traceExec(ExpressionCaller)[SmushcodeDefines.indexNoExec][] contains the original unevaluated expressions while traceExec(ExpressionCaller)[SmushcodeDefines.indexExec][] contains their output.

See Also:

ExpressionCaller, org.silence.smushcode.Expression#evaluate(org.silence.smushcode.ExpressionCaller, java.lang.util.Vector), SmushcodeDefines.indexNoExec, SmushcodeDefines.indexExec

evaluate

protected java.util.Vector[] evaluate(ExpressionCaller callerLink,
                                      java.util.Vector[] evalProgress)

Drives the evaluation of the SMUSHcode75 statements and should be overridden in each class to provide unique functionality. Since Expression provides no special functionality, this function only returns the string stored within the object.

Parameters:

callerLink - a link back to the ExpressionCaller that holds this instance's evaluation stack.

evalProgress - an array of Vectors that contain the output and (possibly) the original expressions. If evalProgress[SmushcodeDefines.indexNoExec] is null, the original expressions are not generated.

Returns:

the same array of Vectors with the output and (possibly) original statement from this object added to the end.

See Also:

ExpressionCaller

toString

public final java.lang.String toString(ExpressionCaller callerLink)

The SMUSHcode75 statement stored in the object is evaluated and its result is returned.

Parameters:

callerLink - a link back to the ExpressionCaller that holds this instance's evaluation stack.

Returns:

the output of the SMUSHcode75 statement stored in the object.

See Also:

ExpressionCaller, evaluate(org.silence.smushcode.ExpressionCaller), org.silence.smushcode.Expression#evaluate(org.silence.smushcode.ExpressionCaller, java.lang.util.Vector), traceExec(org.silence.smushcode.ExpressionCaller)

noExec

public java.lang.String noExec()

In Expression's subclasses, noExec() returns the SMUSHcode75 statement stored in the object. Since the base Expression class has no special properties, the output of noExec() is the same as toString().

Returns:

the string stored in this object, unmodified and unexecuted.

logic

public boolean logic(ExpressionCaller callerLink)

Determines if the value stored in the Expression is "true" or "false" in SMUSHcode75 terms. In SMUSHcode75, an Expression is "false" if it evaluates to the string "0". Everything else is "true". This function simply returns logic(toString(callerLink)).

Returns:

true or false, according to whether the SMUSHcode75 statement in the object is true or false, respectively.

logic

public static boolean logic(java.lang.String input)

Determines if the value passed is "true" or "false" in SMUSHcode75 terms. In SMUSHcode75, a value is "false" if it evaluates to the string "0". Everything else is "true".

Parameters:

input - the value to be examined for "trueness".

Returns:

true or false, according to whether the input is true or false, respectively.

classify

public static Expression classify(ExpressionCache newLink,
                                  java.lang.String newString)
                           throws SMUSHInvalidExpressionException

Most of the magic in Expression takes place here. This function is the only way that new Expression-derived objects should be created. The unparsed SMUSHcode75 statement is passed to classify() and an Expression-derived object that contains the SMUSHcode75 is returned. The magic of this function is that it identifies the type of SMUSHcode75 statement it has been passed, finds the appropriate Java class to hold it and instantiates an object of that class. The type of SMUSHcode75 statement is determined according to the SMUSHcode75 EBNF specifications. Note that SMUSHcode75 functions each have their own classes, which classify() finds dynamically. The EBNF specs for SMUSHcode75 and the delimiters for each type of statement are contained in the comments for SmushcodeDefines.

Parameters:

newLink - a link back to the cache for this instantiation of the SMUSHcode75 system.

newString - the unparsed SMUSHcode75 statement to be stored in a new Expression-derived object

Returns:

an Expression-derived object holding the parsed SMUSHcode75 statement.

Throws:

SMUSHInvalidExpressionException - Generated if the SMUSHcode75 statement is invalid for some reason.

See Also:

SmushcodeDefines

separate

public static java.util.Vector separate(ExpressionCache newLink,
                                        java.lang.String newExpr,
                                        char separator)
                                 throws SMUSHInvalidExpressionException

Primarily for use by the constructors of Expression-derived classes, separate() will pick out the parameters to the SMUSHcode75 statement and pull them apart. The parameters are returned as individual Expression-derived objects stored in an Vector. separate() calls classify() for each parameter located.

Parameters:

newLink - a link back to the cache for this instantiation of the SMUSHcode75 system.

newExpr - the String containing the SMUSHcode75 statement's parameters.

separator - the character that separates the parameters within newExpr.

Returns:

a Vector that contains the parsed parameters.

Throws:

SMUSHInvalidExpressionException - Generated if the SMUSHcode75 statement is invalid for some reason.

setLink

protected void setLink(ExpressionCache newLink)

Provides a way to set this object's pointer to an ExpressionCache object after it has been instantiated.

Parameters:

newLink - a link back to the cache for this instantiation of the SMUSHcode75 system.

findConstancy

protected void findConstancy()

Determines if this object will always return the same value regardless of its context. This function should be overridden in every descendant class of Expression. Because Expression provides no special functionality, this function simply sets constantExpr to true.

See Also:

constantExpr

getConstancy

protected boolean getConstancy()

Returns the value of constantExpr.

Returns:

the value of constantExpr.

See Also:

constantExpr