edu.mit.ai.psg.jeva
Class Jeva

java.lang.Object
  |
  +--edu.mit.ai.psg.jeva.Jeva

public class Jeva

extends Object

Jeva (Java Evaluator) is the entry point class of the core of a source code evaluator for Java programs; see edu.mit.ai.psg.jevaUI for user interfaces.

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

To parse and evaluate individual expressions:

• Consider method parseEvalStringExpression(String).

  .        Jeva.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 = Jeva.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 = Jeva.parseEvalStringStatement("import java.awt.*;");
.      env = Jeva.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 = Jeva.makeDefaultEnv();
.      env = Jeva.extendEnv(Frame.class, "f", frameA, env);
.      Frame frame = (Frame) Jeva.parseEvalStringExpression("f", env);

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

Jeva 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.jevaUI

Field Summary

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

Method Summary

static IEnv	extendEnv(boolean isFinal, Class type, String name, Object value, IEnv nextEnv)
static IEnv	extendEnv(boolean isFinal, IClass 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 IEnv	extendEnv(IClass type, String name, Object value, IEnv nextEnv)
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) Accept a class name on command line as compilation unit to locate in classpath, parse, evaluate, and run its public static void main(String[]) method, passing it any remaining arguments.
static IEnv	makeDefaultEnv() Return a new default environment.
static IEnv	makeDefaultEnv(int optionBits)
static void	parseEvalStreamCompilationUnit(InputStream stream, String[] arguments) Parse one top-level Java compilation unit (file) from stream With default environment, find its public class, and call the class's "public static void main(String[])" method with arguments.
static void	parseEvalStreamCompilationUnit(InputStream stream, String[] arguments, IEnv env) Parse one top-level Java compilation unit (file) from stream With environment env, find its public class, and call the class's "public static void main(String[])" method with arguments.
static IEnv	parseEvalStreamDeclaration(InputStream stream) Parse and evaluate a single top-level java declaration from stream.
static IEnv	parseEvalStreamDeclaration(InputStream stream, IEnv env) Parse and evaluate a single top-level java declaration from stream, using environment env.
static Object	parseEvalStreamExpression(InputStream stream) Parse and evaluate a single top-level java expression from stream.
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.
static IEnv	parseEvalStreamStatement(InputStream stream, IEnv env) Parse and evaluate a single top-level java statement from stream, using environment env.
static void	parseEvalStringCompilationUnit(String s, String[] arguments) Parse one top-level Java compilation unit (file) from string s With default environment, find its public class, and call the class's "public static void main(String[])" method with arguments.
static void	parseEvalStringCompilationUnit(String s, String[] arguments, IEnv env) Parse one top-level Java compilation unit (file) from stream With environment env, find its public class, and call the class's "public static void main(String[])" method with arguments.
static IEnv	parseEvalStringDeclaration(String s) Parse and evaluate one top-level (no free local vars) Java declaration from string s.
static IEnv	parseEvalStringDeclaration(String s, IEnv env) Parse and evaluate one top-level (no free local vars) Java declaration from string s, using environment env.
static Object	parseEvalStringExpression(String s) Parse and evaluate a single top-level java expression from string s.
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.
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 JNCompilationUnit	parseStreamCompilationUnit(InputStream strm) Parse one Java compilation unit (file) in stream.
static IDeclarationNode	parseStreamDeclaration(InputStream stream) Parse one top-level Java declaration from stream.
static IExpressionNode	parseStreamExpression(InputStream stream) Parse one top-level (no free local vars) Java expression from stream.
static IStatementNode	parseStreamStatement(InputStream stream) Parse one top-level (no free local vars) Java statement from stream.
static JNCompilationUnit	parseStringCompilationUnit(String strg) Parse one Java compilation unit (file) in string s.
static IDeclarationNode	parseStringDeclaration(String s) Parse one top-level Java declaration in string s.
static IExpressionNode	parseStringExpression(String s) Parse one top-level (no free local vars) Java expression in string s.
static IStatementNode	parseStringStatement(String s) Parse one top-level (no free local vars) Java statement in string s.
static void	runClass(String className, String[] arguments) run with a default environment.
static void	runClass(String className, String[] arguments, IEnv env) Given the name of a public class as compilation unit to locate in classpath: parse, evaluate, and run its public static void main(String[]) method, passing it the arguments.

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

supressAccessChecksBit

public static final int supressAccessChecksBit

Option: suppress checking accessibility (protected, package, private); 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. (Applets may need to first set checkPackageNames to false to prevent security exceptions.)

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(IClass type,
                             String name,
                             Object value,
                             IEnv nextEnv)

extendEnv

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

extendEnv

public static IEnv extendEnv(boolean isFinal,
                             IClass 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.

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.

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. With 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. With 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

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 statement

VerifyingException - if statement is illegal

AbruptCompletionException - if statement completed abruptly

parseEvalStringDeclaration

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

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

Returns:

IEnv, environment with extensions by declaration

Throws:

ParseException - wasn't able to parse declaration.

VerifyingException - if declaration is illegal

AbruptCompletionException - if declaration completed abruptly

parseEvalStreamDeclaration

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

Parse and evaluate a single top-level java declaration from stream. With default environment.

Returns:

IEnv, environment with extensions by declaration

Throws:

ParseException - wasn't able to parse declaration

VerifyingException - if declaration is illegal

AbruptCompletionException - if declaration completed abruptly

parseEvalStringDeclaration

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

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

Returns:

IEnv, environment with extensions by declaration

Throws:

ParseException - wasn't able to parse declaration.

VerifyingException - if declaration is illegal

AbruptCompletionException - if declaration completed abruptly

parseEvalStreamDeclaration

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

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

Returns:

IEnv, environment with extensions by declaration

Throws:

ParseException - wasn't able to parse declaration

VerifyingException - if declaration is illegal

AbruptCompletionException - if declaration completed abruptly

parseEvalStringCompilationUnit

public static void parseEvalStringCompilationUnit(String s,
                                                  String[] arguments)
                                           throws ParseException,
                                                  VerifyingException,
                                                  ClassNotFoundException,
                                                  ThrowException

Parse one top-level Java compilation unit (file) from string s With default environment, find its public class, and call the class's "public static void main(String[])" method with arguments.

Throws:

ParseException - wasn't able to parse compilation unit

VerifyingException - if compilation unit is illegal

ClassNotFoundException - if no class with "public static void main(String[])" method is found

ThrowException - if main method completed with thrown exception

parseEvalStreamCompilationUnit

public static void parseEvalStreamCompilationUnit(InputStream stream,
                                                  String[] arguments)
                                           throws ParseException,
                                                  VerifyingException,
                                                  ClassNotFoundException,
                                                  ThrowException

Parse one top-level Java compilation unit (file) from stream With default environment, find its public class, and call the class's "public static void main(String[])" method with arguments.

Throws:

ParseException - wasn't able to parse compilation unit

VerifyingException - if compilation unit is illegal

ClassNotFoundException - if no class with "public static void main(String[])" method is found

ThrowException - if main method completed with thrown exception

parseEvalStringCompilationUnit

public static void parseEvalStringCompilationUnit(String s,
                                                  String[] arguments,
                                                  IEnv env)
                                           throws ParseException,
                                                  VerifyingException,
                                                  ClassNotFoundException,
                                                  ThrowException

Parse one top-level Java compilation unit (file) from stream With environment env, find its public class, and call the class's "public static void main(String[])" method with arguments.

Throws:

ParseException - wasn't able to parse compilation unit

VerifyingException - if compilation unit is illegal

ClassNotFoundException - if no class with "public static void main(String[])" method is found

ThrowException - if main method completed with thrown exception

parseEvalStreamCompilationUnit

public static void parseEvalStreamCompilationUnit(InputStream stream,
                                                  String[] arguments,
                                                  IEnv env)
                                           throws ParseException,
                                                  VerifyingException,
                                                  ClassNotFoundException,
                                                  ThrowException

Parse one top-level Java compilation unit (file) from stream With environment env, find its public class, and call the class's "public static void main(String[])" method with arguments.

Throws:

ParseException - wasn't able to parse compilation unit

VerifyingException - if compilation unit is illegal

ClassNotFoundException - if no class with "public static void main(String[])" method is found

ThrowException - if main method completed with thrown exception

parseStreamExpression

public static IExpressionNode parseStreamExpression(InputStream stream)
                                             throws ParseException

Parse one top-level (no free local vars) 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 top-level (no free local vars) 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 top-level (no free local vars) 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 top-level (no free local vars) Java statement in string s.

Returns:

the root node of the statement's parse tree.

Throws:

ParseException - wasn't able to parse statement.

parseStreamDeclaration

public static IDeclarationNode parseStreamDeclaration(InputStream stream)
                                               throws ParseException

Parse one top-level Java declaration from stream.

Returns:

the root node of the declaration's parse tree.

Throws:

ParseException - wasn't able to parse declaration.

parseStringDeclaration

public static IDeclarationNode parseStringDeclaration(String s)
                                               throws ParseException

Parse one top-level Java declaration in string s.

Returns:

the root node of the declaration's parse tree.

Throws:

ParseException - wasn't able to parse statement.

parseStreamCompilationUnit

public static JNCompilationUnit parseStreamCompilationUnit(InputStream strm)
                                                    throws ParseException

Parse one Java compilation unit (file) in stream.

Returns:

the compilation unit parse tree.

Throws:

ParseException - wasn't able to parse the compilation unit.

parseStringCompilationUnit

public static JNCompilationUnit parseStringCompilationUnit(String strg)
                                                    throws ParseException

Parse one Java compilation unit (file) in string s.

Returns:

the compilation unit parse tree.

Throws:

ParseException - wasn't able to parse the compilation unit.

runClass

public static void runClass(String className,
                            String[] arguments)
                     throws ParseException,
                            ClassNotFoundException,
                            Error,
                            IllegalAccessException,
                            NoSuchMethodException,
                            ThrowException

run with a default environment.

See Also:

runClass(String, String[], IEnv), makeDefaultEnv()

runClass

public static void runClass(String className,
                            String[] arguments,
                            IEnv env)
                     throws ParseException,
                            ClassNotFoundException,
                            Error,
                            IllegalAccessException,
                            NoSuchMethodException,
                            ThrowException

Given the name of a public class as compilation unit to locate in classpath: parse, evaluate, and run its public static void main(String[]) method, passing it the arguments. (Jeva uses newer of .java or .class files.)

Throws:

ParseException - if className can't be parsed.

ClassNotFoundException - if className can't be found.

Error - if there are problems parsing files

IllegalAccessException - if class is not public

NoSuchMethodException - if class doesn't have a public static void main(String[]) method

ThrowException - if running main throws an exception

main

public static void main(String[] parameters)

Accept a class name on command line as compilation unit to locate in classpath, parse, evaluate, and run its public static void main(String[]) method, passing it any remaining arguments. Or evaluate a single statment or expression. Usage:
java edu.mit.ai.psg.jeva.Jeva fullClassName [arguments...]
java edu.mit.ai.psg.jeva.Jeva -expression "java expression"
java edu.mit.ai.psg.jeva.Jeva -statement "java statement"
java edu.mit.ai.psg.jeva.Jeva -echo [arguments...]
Echos what Jeva receives as arguments (to diagnose quoting).

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