The BeanShell script interpreter.
An instance of Interpreter can be used to source scripts and evaluate
statements or expressions.
Here are some examples:
Interpeter bsh = new Interpreter();
// Evaluate statements and expressions
bsh.eval("foo=Math.sin(0.5)");
bsh.eval("bar=foo*5; bar=Math.cos(bar);");
bsh.eval("for(i=0; i<10; i++) { print(\"hello\"); }");
// same as above using java syntax and apis only
bsh.eval("for(int i=0; i<10; i++) { System.out.println(\"hello\"); }");
// Source from files or streams
bsh.source("myscript.bsh"); // or bsh.eval("source(\"myscript.bsh\")");
// Use set() and get() to pass objects in and out of variables
bsh.set( "date", new Date() );
Date date = (Date)bsh.get( "date" );
// This would also work:
Date date = (Date)bsh.eval( "date" );
bsh.eval("year = date.getYear()");
Integer year = (Integer)bsh.get("year"); // primitives use wrappers
// With Java1.3+ scripts can implement arbitrary interfaces...
// Script an awt event handler (or source it from a file, more likely)
bsh.eval( "actionPerformed( e ) { print( e ); }");
// Get a reference to the script object (implementing the interface)
ActionListener scriptedHandler =
(ActionListener)bsh.eval("return (ActionListener)this");
// Use the scripted event handler normally...
new JButton.addActionListener( script );
In the above examples we showed a single interpreter instance, however
you may wish to use many instances, depending on the application and how
you structure your scripts. Interpreter instances are very light weight
to create, however if you are going to execute the same script repeatedly
and require maximum performance you should consider scripting the code as
a method and invoking the scripted method each time on the same interpreter
instance (using eval()).
See the BeanShell User's Manual for more information.
DEBUG
public static boolean DEBUG
LOCALSCOPING
public static boolean LOCALSCOPING
TRACE
public static boolean TRACE
VERSION
public static final String VERSION
evalOnly
protected boolean evalOnly
interactive
protected boolean interactive
Interpreter
public Interpreter()
Create an interpreter for evaluation only.
Interpreter
public Interpreter(Reader in,
PrintStream out,
PrintStream err,
boolean interactive)
Interpreter
public Interpreter(Reader in,
PrintStream out,
PrintStream err,
boolean interactive,
NameSpace namespace)
Interpreter
public Interpreter(Reader in,
PrintStream out,
PrintStream err,
boolean interactive,
NameSpace namespace,
Interpreter parent,
String sourceFileInfo)
The main constructor.
All constructors should now pass through here.
namespace
- If namespace is non-null then this interpreter's
root namespace will be set to the one provided. If it is null a new
one will be created for it.parent
- The parent interpreter if this interpreter is a child
of another. May be null. Children share a BshClassManager with
their parent instance.sourceFileInfo
- An informative string holding the filename
or other description of the source from which this interpreter is
reading... used for debugging. May be null.
Interpreter
public Interpreter(ConsoleInterface console)
Construct a new interactive interpreter attached to the specified
console.
Interpreter
public Interpreter(ConsoleInterface console,
NameSpace globalNameSpace)
Construct a new interactive interpreter attached to the specified
console using the specified parent namespace.
debug
public static final void debug(String s)
Print a debug message on debug stream associated with this interpreter
only if debugging is turned on.
error
public final void error(String s)
Print an error message in a standard format on the output stream
associated with this interpreter. On the GUI console this will appear
in red, etc.
- error in interface ConsoleInterface
eval
public Object eval(Reader in)
throws EvalError
Evaluate the inputstream in this interpreter's global namespace.
eval
public Object eval(Reader in,
NameSpace nameSpace,
String sourceFileInfo)
throws EvalError
Spawn a non-interactive local interpreter to evaluate text in the
specified namespace.
Return value is the evaluated object (or corresponding primitive
wrapper).
sourceFileInfo
- is for information purposes only. It is used to
display error messages (and in the future may be made available to
the script).
eval
public Object eval(String statements)
throws EvalError
Evaluate the string in this interpreter's global namespace.
eval
public Object eval(String statements,
NameSpace nameSpace)
throws EvalError
Evaluate the string in the specified namespace.
get
public Object get(String name)
throws EvalError
Get the value of the name.
name may be any value. e.g. a variable or field
getClassManager
public BshClassManager getClassManager()
Get the class manager associated with this interpreter
(the BshClassManager of this interpreter's global namespace).
This is primarily a convenience method.
getErr
public PrintStream getErr()
Get the error output stream associated with this interpreter.
This may be be stderr or the GUI console.
- getErr in interface ConsoleInterface
getIn
public Reader getIn()
Get the input stream associated with this interpreter.
This may be be stdin or the GUI console.
- getIn in interface ConsoleInterface
getInterface
public Object getInterface(Class interf)
throws EvalError
Get a reference to the interpreter (global namespace), cast
to the specified interface type. Assuming the appropriate
methods of the interface are defined in the interpreter, then you may
use this interface from Java, just like any other Java object.
For example:
Interpreter interpreter = new Interpreter();
// define a method called run()
interpreter.eval("run() { ... }");
// Fetch a reference to the interpreter as a Runnable
Runnable runnable =
(Runnable)interpreter.getInterface( Runnable.class );
Note that the interpreter does *not* require that any or all of the
methods of the interface be defined at the time the interface is
generated. However if you attempt to invoke one that is not defined
you will get a runtime exception.
Note also that this convenience method has exactly the same effect as
evaluating the script:
(Type)this;
For example, the following is identical to the previous example:
// Fetch a reference to the interpreter as a Runnable
Runnable runnable =
(Runnable)interpreter.eval( "(Runnable)this" );
Version requirement Although standard Java interface types
are always available, to be used with arbitrary interfaces this
feature requires that you are using Java 1.3 or greater.
EvalError
- if the interface cannot be generated because the
version of Java does not support the proxy mechanism.
getNameSpace
public NameSpace getNameSpace()
Get the global namespace of this interpreter.
Note: This is here for completeness. If you're using this a lot
it may be an indication that you are doing more work than you have
to. For example, caching the interpreter instance rather than the
namespace should not add a significant overhead. No state other than
the debug status is stored in the interpreter.
All features of the namespace can also be accessed using the
interpreter via eval() and the script variable 'this.namespace'
(or global.namespace as necessary).
getOut
public PrintStream getOut()
Get the outptut stream associated with this interpreter.
This may be be stdout or the GUI console.
- getOut in interface ConsoleInterface
getParent
public Interpreter getParent()
Get the parent Interpreter of this interpreter, if any.
Currently this relationship implies the following:
1) Parent and child share a BshClassManager
2) Children indicate the parent's source file information in error
reporting.
When created as part of a source() / eval() the child also shares
the parent's namespace. But that is not necessary in general.
getSourceFileInfo
public String getSourceFileInfo()
Specify the source of the text from which this interpreter is reading.
Note: there is a difference between what file the interrpeter is
sourcing and from what file a method was originally parsed. One
file may call a method sourced from another file. See SimpleNode
for origination file info.
bsh.SimpleNode.getSourceFile()
getStrictJava
public boolean getStrictJava()
main
public static void main(String[] args)
Run the text only interpreter on the command line or specify a file.
pathToFile
public File pathToFile(String fileName)
throws IOException
Localize a path to the file name based on the bsh.cwd interpreter
working directory.
redirectOutputToFile
public static void redirectOutputToFile(String filename)
run
public void run()
Run interactively. (printing prompts, etc.)
set
public void set(String name,
Object value)
throws EvalError
Assign the value to the name.
name may evaluate to anything assignable. e.g. a variable or field.
set
public void set(String name,
boolean value)
throws EvalError
set
public void set(String name,
double value)
throws EvalError
set
public void set(String name,
float value)
throws EvalError
set
public void set(String name,
int value)
throws EvalError
set
public void set(String name,
long value)
throws EvalError
setClassLoader
public void setClassLoader(ClassLoader externalCL)
Set an external class loader to be used for all basic class loading
in BeanShell.
BeanShell will use this at the same point it would otherwise use the
plain Class.forName().
i.e. if no explicit classpath management is done from the script
(addClassPath(), setClassPath(), reloadClasses()) then BeanShell will
only use the supplied classloader. If additional classpath management
is done then BeanShell will perform that in addition to the supplied
external classloader.
However BeanShell is not currently able to reload
classes supplied through the external classloader.
setConsole
public void setConsole(ConsoleInterface console)
Attach a console
Note: this method is incomplete.
setErr
public void setErr(PrintStream err)
setExitOnEOF
public void setExitOnEOF(boolean value)
Specify whether, in interactive mode, the interpreter exits Java upon
end of input. If true, when in interactive mode the interpreter will
issue a System.exit(0) upon eof. If false the interpreter no
System.exit() will be done.
Note: if you wish to cause an EOF externally you can try closing the
input stream. This is not guaranteed to work in older versions of Java
due to Java limitations, but should work in newer JDK/JREs. (That was
the motivation for the Java NIO package).
setNameSpace
public void setNameSpace(NameSpace globalNameSpace)
Set the global namespace for this interpreter.
Note: This is here for completeness. If you're using this a lot
it may be an indication that you are doing more work than you have
to. For example, caching the interpreter instance rather than the
namespace should not add a significant overhead. No state other
than the debug status is stored in the interpreter.
All features of the namespace can also be accessed using the
interpreter via eval() and the script variable 'this.namespace'
(or global.namespace as necessary).
setOut
public void setOut(PrintStream out)
setStrictJava
public void setStrictJava(boolean b)
Set strict Java mode on or off.
This mode attempts to make BeanShell syntax behave as Java
syntax, eliminating conveniences like loose variables, etc.
When enabled, variables are required to be declared or initialized
before use and method arguments are reqired to have types.
This mode will become more strict in a future release when
classes are interpreted and there is an alternative to scripting
objects as method closures.
source
public Object source(String filename)
throws FileNotFoundException,
IOException,
EvalError
Read text from fileName and eval it.
Convenience method. Use the global namespace.
source
public Object source(String filename,
NameSpace nameSpace)
throws FileNotFoundException,
IOException,
EvalError
Read text from fileName and eval it.
unset
public void unset(String name)
throws EvalError
Unassign the variable name.
Name should evaluate to a variable.