dk.rode.thesis.interpreter
Interface Expression<E>

Type Parameters:

E - The type of value the evaluation of this expression produces.

All Superinterfaces:

Copyable<Expression<E>>, StrictCopyable<Expression<E>>

All Known Subinterfaces:

InitialisableExpression<E>, NonTerminalExpression<E>, TerminalExpression<E>, TypedExpression<E>

All Known Implementing Classes:

AbstractExpression, AndExpression, AssignmentExpression, BinaryExpression, BreakExpression, CompareExpression, ConditionalExpression, ConstantExpression, CurrentExpression, EqualExpression, FlowExpression, NextExpression, NotExpression, OrExpression, ResetExpression, ReverseExpression, SequenceExpression, SetExpression, TypedExpressionDecorator, TypedFlowExpression, VariableExpression

@Participant(value="AbstractExpression")
public interface Expression<E>
extends StrictCopyable<Expression<E>>

An expression represents grammar rules in form or non terminal expressions and actual functionality in form of terminal expressions that will be enforced when the expression is evaluated.

Expressions are considered immutable, but can be copied. Each unique expression type have a name and each instance symbolic representation. Expressions that cannot be constructed in a single step must be initialised before use; once initialised, they are considered immutable.

Expressions may use other expressions as operands. If a given expression uses or contains another expression can be tested using the contains(Expression) method, based on identity. An expression containing cyclic expression references can still be evaluated and generate a symbolic representation, but cannot be copied, queried for containment, or generate its toString() representation.

Expression is the common super type for all expressions that can be evaluated by an interpreter.

Implementation notes:
As expressions are considered immutable, all but a few internal attributes can be declared final. Simple immutable flags or values can therefore be exposed directly through a final public instance variable, such as the value of a constant or the comparison type used.

Author:

Gunni Rode / rode.dk

See Also:

TypedExpression, InitialisableExpression

Nested Class Summary

static class

Expression.SymbolIdiom The symbol idiom ensures that cyclic expression references will be represented correctly in symbolic representation starting from a given expression.

Method Summary

String	asSymbol(Context context) Returns a short symbolic representation of this expression that describes it in a concise form.
boolean	contains(Expression<?> expression) Returns true if this expression is or contains the expression supplied as expression, false if not.
Expression<E>	copy() Copies this expression.
E	evaluate(Context context) Evaluates this expression and returns the result.
String	name() The stand-alone symbol name for this expression.
List<Expression<?>>	operands() Returns the expression operands used by this expression, in order.
String	toString() Returns the string representation of this expression.

Method Detail

asSymbol

String asSymbol(Context context)
                throws ExpressionException

Returns a short symbolic representation of this expression that describes it in a concise form.

The caller of this method should always ensure that context is reset properly before use by calling Context.reset(). This ensures that cyclic expression references are handled properly!

General semantics:

• Expressions are separated by comma (,), and possibly grouped in parentheses.

• Standard Java operators are used: && and }||} for logical short-circuit AND and OR, respectively; & and }|} for logical non short-circuit AND and OR, respectively; <, <=, ==, !=, >=, and > for comparison; = for assignment; ! for negation; and x ? y : z for conditional expressions, where x, y, and z are expressions.

• Arguments to terminal expressions are enclosed in square brackets, not parentheses, like x[y], where x is the terminal expression taking expression y as an argument.

• typed expressions may expose the type like Type{x}, where Type is the simple class name of the type, and x the symbolic representation of the expression.

• The symbolic representation of a cyclic reference is {{from -> to}}, where from and to are the names of the expressions, respectively.

Parameters:

context - The context to use; never null.

Returns:

The symbolic representation; never null.

Throws:

NullPointerException - If context is null.

ExpressionException - If the symbol cannot be generated.

See Also:

contains(Expression)

contains

boolean contains(Expression<?> expression)

Returns true if this expression is or contains the expression supplied as expression, false if not.

The test is performed using identity (==).

Unlike asSymbol(Context), querying for containment cannot handle cyclic expression references!

Parameters:

expression - The expression to test; cannot be null.

Returns:

True if expression is this expression or contained within this expression, false if not.

Throws:

NullPointerException - If expression is null.

See Also:

asSymbol(Context), Context.touch(Expression)

copy

Expression<E> copy()

Copies this expression.

Unlike asSymbol(Context), copying cannot handle cyclic expression references!

Specified by:

copy in interface Copyable<Expression<E>>

Returns:

A copy of this expression; never null.

evaluate

E evaluate(Context context)
           throws ExpressionException

Evaluates this expression and returns the result.

There is no guarantee that the evaluation of this expression will terminate!

Parameters:

context - The context to use; cannot be null.

Returns:

The result of the evaluation; never null.

Throws:

NullPointerException - If context is null.

ExpressionException - If the evaluation fails.

name

String name()

The stand-alone symbol name for this expression.

Returns:

The symbol name; never null.

operands

List<Expression<?>> operands()

Returns the expression operands used by this expression, in order.

Modifying the returned list will not affect this expression.

Returns:

The operands; never null, but can be empty.

toString

String toString()

Returns the string representation of this expression.

Unlike asSymbol(Context), the string generation cannot handle cyclic expression references!

Overrides:

toString in class Object

Returns:

The string representation; never null.