edu.mit.ai.psg.jevaES
Class JevaES

java.lang.Object
  |
  +--edu.mit.ai.psg.jevaES.JevaES

public class JevaES

extends Object

JevaES (Java Evaluator: Expressions & Statements) is the entry point class of the core of a source code evaluator for Java expressions and statements; see edu.mit.ai.psg.jevaESUI for user interfaces.

To just evaluate a single expression or statement from a command line, see main(String[]).

To parse and evaluate individual expressions:

• Consider method parseEvalStringExpression(String).

  .        JevaES.parseEvalStringExpression("25 * 9 / 5 + 32") ==> 77
  

• Alternatively, parseStringExpression(String), then
  EvalMethods.evaluate(IExpressionNode), and use
  IJevaNode.getEndToken() to see how far the parse proceeded.

  .        IExpressionNode expr = JevaES.parseStringExpression("25*9/5+32 degF");
  .        expr.getEndToken().beginColumn ==> 10
  .        EvalMethods.evaluate(expr) ==> 77
  

There are similar methods for parsing statements, and for parsing expressions and statements from streams rather than strings.

Statements that define local variables, or that import classes or packages, return an extended environment. This environment may be passed as an argument to later calls to parseEval...(...) or EvalMethods.evaluate(...), making the variable names or imported class or package names available to them.

.      IEnv env = JevaES.parseEvalStringStatement("import java.awt.*;");
.      env = JevaES.parseEvalStringStatement("Frame f = new Frame();", env);
.      Frame frame = (Frame) JevaES.parseEvalStringExpression("f", env);

To define names directly, start with a makeDefaultEnv() and extend it with extendEnv(Class, String, Object, IEnv).

.      Frame frameA = new Frame();       
.      IEnv env = JevaES.makeDefaultEnv();
.      env = JevaES.extendEnv(Frame.class, "f", frameA, env);
.      Frame frame = (Frame) JevaES.parseEvalStringExpression("f", env);

See edu.mit.ai.psg.jevaESUI for user interfaces which accept typed expressions and statements.

JevaES was developed using a parser generated by Sun's free Java parser generator JavaCC/JJTree (now maintained by the spinoff Metamata), using a modified version of the example Java grammar.

See Also:

edu.mit.ai.psg.jevaESUI

Field Summary

static int	leftmostOptionBit
static int	suppressAccessChecksBit Option: suppress checking accessibility (protected, etc.); may be useful when JevaES is used for debugging, but requires java.lang.reflect.ReflectPermission for edu/mit/ai/psg/jevaES if there is a SecurityManager.
static int	suppressPackageNameChecksBit Option: suppress checking spelling of package names against directory names; used if security prevents access to classPath

Method Summary

static IEnv	extendEnv(boolean isFinal, Class type, String name, Object value, IEnv nextEnv) Extend an env with a new local named value (may specify if final).
static IEnv	extendEnv(Class type, String name, Object value, IEnv nextEnv) Extend an env with a new local named value (that is not final).
static String	getCopyright()
static String	getHomepage()
static String	getNoWarranty()
static String	getVersion()
static boolean	isSuppressingAccessChecks(IEnv env)
static boolean	isSuppressingPackageNameChecks(IEnv env)
static void	main(String[] parameters) Evaluate a single statment or expression from command line.
static IEnv	makeDefaultEnv() Return a new default environment, which imports java.lang.
static IEnv	makeDefaultEnv(int optionBits)
static Object	parseEvalStreamExpression(InputStream stream) Parse and evaluate a single top-level java expression from stream, using default environment.
static Object	parseEvalStreamExpression(InputStream stream, IEnv env) Parse and evaluate a single top-level java expression from stream in environment env.
static IEnv	parseEvalStreamStatement(InputStream stream) Parse and evaluate a single top-level java statement from stream, using default environment.
static IEnv	parseEvalStreamStatement(InputStream stream, IEnv env) Parse and evaluate a single top-level java statement from stream, using environment env.
static Object	parseEvalStringExpression(String s) Parse and evaluate a single top-level java expression from string s, using default environment.
static Object	parseEvalStringExpression(String s, IEnv env) Parse and evaluate a single top-level java expression from string s in environment env.
static IEnv	parseEvalStringStatement(String s) Parse and evaluate one top-level (no free local vars) Java statement from string s, using default environment.
static IEnv	parseEvalStringStatement(String s, IEnv env) Parse and evaluate one top-level (no free local vars) Java statement from string s, using environment env.
static IExpressionNode	parseStreamExpression(InputStream stream) Parse one Java expression from stream.
static IStatementNode	parseStreamStatement(InputStream stream) Parse one Java statement from stream.
static IExpressionNode	parseStringExpression(String s) Parse one Java expression in string s.
static IStatementNode	parseStringStatement(String s) Parse one Java statement in string s.

Methods inherited from class java.lang.Object

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

Field Detail

suppressPackageNameChecksBit

public static final int suppressPackageNameChecksBit

Option: suppress checking spelling of package names against directory names; used if security prevents access to classPath

suppressAccessChecksBit

public static final int suppressAccessChecksBit

Option: suppress checking accessibility (protected, etc.); may be useful when JevaES is used for debugging, but requires java.lang.reflect.ReflectPermission for edu/mit/ai/psg/jevaES if there is a SecurityManager.

leftmostOptionBit

public static final int leftmostOptionBit

Method Detail

getCopyright

public static String getCopyright()

getNoWarranty

public static String getNoWarranty()

getVersion

public static String getVersion()

getHomepage

public static String getHomepage()

isSuppressingPackageNameChecks

public static final boolean isSuppressingPackageNameChecks(IEnv env)

isSuppressingAccessChecks

public static final boolean isSuppressingAccessChecks(IEnv env)

makeDefaultEnv

public static IEnv makeDefaultEnv()

Return a new default environment, which imports java.lang.

makeDefaultEnv

public static IEnv makeDefaultEnv(int optionBits)

extendEnv

public static IEnv extendEnv(Class type,
                             String name,
                             Object value,
                             IEnv nextEnv)

Extend an env with a new local named value (that is not final). For example, might be used from compiled code to give access to values at a breakpoint that calls JevaES.

Throws:

IllegalArgumentException - if type, name, or nextEnv is null, or if value cannot be assigned to variable of given type.

extendEnv

public static IEnv extendEnv(boolean isFinal,
                             Class type,
                             String name,
                             Object value,
                             IEnv nextEnv)

Extend an env with a new local named value (may specify if final). (Final primitives and strings are treated as constants.)

parseEvalStringExpression

public static Object parseEvalStringExpression(String s)
                                        throws ParseException,
                                               VerifyingException,
                                               ThrowException

Parse and evaluate a single top-level java expression from string s, using default environment.

Returns:

the result of evaluating the expression

Throws:

ParseException - wasn't able to parse expression

VerifyingException - if expression is illegal

ThrowException - if expression completed abruptly with exception

parseEvalStreamExpression

public static Object parseEvalStreamExpression(InputStream stream)
                                        throws ParseException,
                                               VerifyingException,
                                               ThrowException

Parse and evaluate a single top-level java expression from stream, using default environment.

Returns:

the result of evaluating the expression

Throws:

ParseException - wasn't able to parse expression

VerifyingException - if expression is illegal

ThrowException - if expression completed abruptly with exception

parseEvalStringExpression

public static Object parseEvalStringExpression(String s,
                                               IEnv env)
                                        throws ParseException,
                                               VerifyingException,
                                               ThrowException

Parse and evaluate a single top-level java expression from string s in environment env.

Returns:

the result of evaluating the expression

Throws:

ParseException - wasn't able to parse expression

VerifyingException - if expression is illegal

ThrowException - if expression completed abruptly with exception

parseEvalStreamExpression

public static Object parseEvalStreamExpression(InputStream stream,
                                               IEnv env)
                                        throws ParseException,
                                               VerifyingException,
                                               ThrowException

Parse and evaluate a single top-level java expression from stream in environment env.

Returns:

the result of evaluating the expression

Throws:

ParseException - wasn't able to parse expression

VerifyingException - if expression is illegal

ThrowException - if expression completed abruptly with exception

parseEvalStringStatement

public static IEnv parseEvalStringStatement(String s)
                                     throws ParseException,
                                            VerifyingException,
                                            AbruptCompletionException

Parse and evaluate one top-level (no free local vars) Java statement from string s, using default environment.

Returns:

IEnv, environment with extensions by statement (e.g., local decl)

Throws:

ParseException - wasn't able to parse statement.

VerifyingException - if statement is illegal

AbruptCompletionException - if statement completed abruptly

parseEvalStreamStatement

public static IEnv parseEvalStreamStatement(InputStream stream)
                                     throws ParseException,
                                            VerifyingException,
                                            AbruptCompletionException

Parse and evaluate a single top-level java statement from stream, using default environment.

Returns:

IEnv, environment with extensions by statement (e.g., local decl)

Throws:

ParseException - wasn't able to parse expression

VerifyingException - if statement is illegal

AbruptCompletionException - if statement completed abruptly

parseEvalStringStatement

public static IEnv parseEvalStringStatement(String s,
                                            IEnv env)
                                     throws ParseException,
                                            VerifyingException,
                                            AbruptCompletionException

Parse and evaluate one top-level (no free local vars) Java statement from string s, using environment env.

Returns:

IEnv, environment with extensions by statement (e.g., local decl)

Throws:

ParseException - wasn't able to parse statement.

VerifyingException - if statement is illegal

AbruptCompletionException - if statement completed abruptly

parseEvalStreamStatement

public static IEnv parseEvalStreamStatement(InputStream stream,
                                            IEnv env)
                                     throws ParseException,
                                            VerifyingException,
                                            AbruptCompletionException

Parse and evaluate a single top-level java statement from stream, using environment env.

Returns:

IEnv, environment with extensions by statement (e.g., local decl)

Throws:

ParseException - wasn't able to parse expression

VerifyingException - if statement is illegal

AbruptCompletionException - if statement completed abruptly

parseStreamExpression

public static IExpressionNode parseStreamExpression(InputStream stream)
                                             throws ParseException

Parse one Java expression from stream.

Returns:

the root node of the expression's parse tree.

Throws:

ParseException - wasn't able to parse expression

parseStringExpression

public static IExpressionNode parseStringExpression(String s)
                                             throws ParseException

Parse one Java expression in string s.

Returns:

the root node of the expression's parse tree.

Throws:

ParseException - wasn't able to parse expression

parseStreamStatement

public static IStatementNode parseStreamStatement(InputStream stream)
                                           throws ParseException

Parse one Java statement from stream.

Returns:

the root node of the statement's parse tree.

Throws:

ParseException - wasn't able to parse statement.

parseStringStatement

public static IStatementNode parseStringStatement(String s)
                                           throws ParseException

Parse one Java statement in string s.

Returns:

the root node of the statement's parse tree.

Throws:

ParseException - wasn't able to parse statement.

main

public static void main(String[] parameters)

Evaluate a single statment or expression from command line. Usage:
java edu.mit.ai.psg.jevaES.JevaES -expression "java expression"
java edu.mit.ai.psg.jevaES.JevaES -statement "java statement"
java edu.mit.ai.psg.jevaES.JevaES -echo [arguments...]
Echos what JevaES receives as arguments (to diagnose quoting).

Note: uses .class file if available and no older than .java file, otherwise interprets .java file.