Interpreter (jEdit API Documentation)
Date: 2018-04-10

org.gjt.sp.jedit.bsh

## Class Interpreter

- java.lang.Object
- - org.gjt.sp.jedit.bsh.Interpreter

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Runnable, ConsoleInterface

      public class Interpreter
      extends java.lang.Object
      implements java.lang.Runnable, ConsoleInterface, java.io.Serializable

  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.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG`
    `protected boolean` | `evalOnly`
    `protected boolean` | `interactive`
    `static boolean` | `LOCALSCOPING`
    `static boolean` | `TRACE`
    `static java.lang.String` | `VERSION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Interpreter()` Create an interpreter for evaluation only.
    `Interpreter(ConsoleInterface console)` Construct a new interactive interpreter attached to the specified console.
    `Interpreter(ConsoleInterface console, NameSpace globalNameSpace)` Construct a new interactive interpreter attached to the specified console using the specified parent namespace.
    `Interpreter(java.io.Reader in, java.io.PrintStream out, java.io.PrintStream err, boolean interactive)`
    `Interpreter(java.io.Reader in, java.io.PrintStream out, java.io.PrintStream err, boolean interactive, NameSpace namespace)`
    `Interpreter(java.io.Reader in, java.io.PrintStream out, java.io.PrintStream err, boolean interactive, NameSpace namespace, Interpreter parent, java.lang.String sourceFileInfo)` The main constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `debug(java.lang.String s)` Print a debug message on debug stream associated with this interpreter only if debugging is turned on.
    `void` | `error(java.lang.Object o)` Print an error message in a standard format on the output stream associated with this interpreter.
    `java.lang.Object` | `eval(java.io.Reader in)` Evaluate the inputstream in this interpreter's global namespace.
    `java.lang.Object` | `eval(java.io.Reader in, NameSpace nameSpace, java.lang.String sourceFileInfo)` Spawn a non-interactive local interpreter to evaluate text in the specified namespace.
    `java.lang.Object` | `eval(java.lang.String statements)` Evaluate the string in this interpreter's global namespace.
    `java.lang.Object` | `eval(java.lang.String statements, NameSpace nameSpace)` Evaluate the string in the specified namespace.
    `java.lang.Object` | `get(java.lang.String name)` Get the value of the name.
    `BshClassManager` | `getClassManager()` Get the class manager associated with this interpreter (the BshClassManager of this interpreter's global namespace).
    `java.io.PrintStream` | `getErr()` Get the error output stream associated with this interpreter.
    `java.io.Reader` | `getIn()` Get the input stream associated with this interpreter.
    `java.lang.Object` | `getInterface(java.lang.Class interf)` Get a reference to the interpreter (global namespace), cast to the specified interface type.
    `NameSpace` | `getNameSpace()` Get the global namespace of this interpreter.
    `java.io.PrintStream` | `getOut()` Get the outptut stream associated with this interpreter.
    `Interpreter` | `getParent()` Get the parent Interpreter of this interpreter, if any.
    `boolean` | `getShowResults()` Show on/off verbose printing status for the show() command.
    `java.lang.String` | `getSourceFileInfo()` Specify the source of the text from which this interpreter is reading.
    `boolean` | `getStrictJava()`
    `static void` | `invokeMain(java.lang.Class clas, java.lang.String[] args)`
    `static void` | `main(java.lang.String[] args)` Run the text only interpreter on the command line or specify a file.
    `java.io.File` | `pathToFile(java.lang.String fileName)` Localize a path to the file name based on the bsh.cwd interpreter working directory.
    `void` | `print(java.lang.Object o)`
    `void` | `println(java.lang.Object o)`
    `static void` | `redirectOutputToFile(java.lang.String filename)`
    `void` | `run()` Run interactively.
    `void` | `set(java.lang.String name, boolean value)`
    `void` | `set(java.lang.String name, double value)`
    `void` | `set(java.lang.String name, float value)`
    `void` | `set(java.lang.String name, int value)`
    `void` | `set(java.lang.String name, long value)`
    `void` | `set(java.lang.String name, java.lang.Object value)` Assign the value to the name.
    `void` | `setClassLoader(java.lang.ClassLoader externalCL)` Set an external class loader to be used as the base classloader for BeanShell.
    `void` | `setConsole(ConsoleInterface console)` Attach a console Note: this method is incomplete.
    `void` | `setErr(java.io.PrintStream err)`
    `void` | `setExitOnEOF(boolean value)` Specify whether, in interactive mode, the interpreter exits Java upon end of input.
    `void` | `setNameSpace(NameSpace globalNameSpace)` Set the global namespace for this interpreter.
    `void` | `setOut(java.io.PrintStream out)`
    `void` | `setShowResults(boolean showResults)` Turn on/off the verbose printing of results as for the show() command.
    `void` | `setStrictJava(boolean b)` Set strict Java mode on or off.
    `java.lang.Object` | `source(java.lang.String filename)` Read text from fileName and eval it.
    `java.lang.Object` | `source(java.lang.String filename, NameSpace nameSpace)` Read text from fileName and eval it.
    `void` | `unset(java.lang.String name)` Unassign the variable name.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### VERSION

          public static final java.lang.String VERSION

      See Also:
        Constant Field Values

    - #### DEBUG

          public static boolean DEBUG

    - #### TRACE

          public static boolean TRACE

    - #### LOCALSCOPING

          public static boolean LOCALSCOPING

    - #### evalOnly

          protected boolean evalOnly

    - #### interactive

          protected boolean interactive

  - ### Constructor Detail

    - #### Interpreter

          public Interpreter(java.io.Reader in,
                             java.io.PrintStream out,
                             java.io.PrintStream err,
                             boolean interactive,
                             NameSpace namespace,
                             Interpreter parent,
                             java.lang.String sourceFileInfo)

      The main constructor. All constructors should now pass through here.
      Parameters:
        `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(java.io.Reader in,
                             java.io.PrintStream out,
                             java.io.PrintStream err,
                             boolean interactive,
                             NameSpace namespace)

    - #### Interpreter

          public Interpreter(java.io.Reader in,
                             java.io.PrintStream out,
                             java.io.PrintStream err,
                             boolean interactive)

    - #### Interpreter

          public Interpreter(ConsoleInterface console,
                             NameSpace globalNameSpace)

      Construct a new interactive interpreter attached to the specified console using the specified parent namespace.

    - #### Interpreter

          public Interpreter(ConsoleInterface console)

      Construct a new interactive interpreter attached to the specified console.

    - #### Interpreter

          public Interpreter()

      Create an interpreter for evaluation only.

  - ### Method Detail

    - #### setConsole

          public void setConsole(ConsoleInterface console)

      Attach a console Note: this method is incomplete.

    - #### 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).

    - #### 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).

    - #### main

          public static void main(java.lang.String[] args)

      Run the text only interpreter on the command line or specify a file.

    - #### invokeMain

          public static void invokeMain(java.lang.Class clas,
                                        java.lang.String[] args)
                                 throws java.lang.Exception

      Throws:
        `java.lang.Exception`

    - #### run

          public void run()

      Run interactively. (printing prompts, etc.)
      Specified by:
        `run` in interface `java.lang.Runnable`

    - #### source

          public java.lang.Object source(java.lang.String filename,
                                         NameSpace nameSpace)
                                  throws java.io.FileNotFoundException,
                                         java.io.IOException,
                                         EvalError

      Read text from fileName and eval it.
      Throws:
        `java.io.FileNotFoundException`
        `java.io.IOException`
        `EvalError`

    - #### source

          public java.lang.Object source(java.lang.String filename)
                                  throws java.io.FileNotFoundException,
                                         java.io.IOException,
                                         EvalError

      Read text from fileName and eval it. Convenience method. Use the global namespace.
      Throws:
        `java.io.FileNotFoundException`
        `java.io.IOException`
        `EvalError`

    - #### eval

          public java.lang.Object eval(java.io.Reader in,
                                       NameSpace nameSpace,
                                       java.lang.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).
      Parameters:
        `sourceFileInfo` - is for information purposes only. It is used to display error messages (and in the future may be made available to the script).
      Throws:
        `EvalError` - on script problems
        `TargetError` - on unhandled exceptions from the script

    - #### eval

          public java.lang.Object eval(java.io.Reader in)
                                throws EvalError

      Evaluate the inputstream in this interpreter's global namespace.
      Throws:
        `EvalError`

    - #### eval

          public java.lang.Object eval(java.lang.String statements)
                                throws EvalError

      Evaluate the string in this interpreter's global namespace.
      Throws:
        `EvalError`

    - #### eval

          public java.lang.Object eval(java.lang.String statements,
                                       NameSpace nameSpace)
                                throws EvalError

      Evaluate the string in the specified namespace.
      Throws:
        `EvalError`

    - #### error

          public final void error(java.lang.Object o)

      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.
      Specified by:
        `error` in interface `ConsoleInterface`

    - #### getIn

          public java.io.Reader getIn()

      Get the input stream associated with this interpreter. This may be be stdin or the GUI console.
      Specified by:
        `getIn` in interface `ConsoleInterface`

    - #### getOut

          public java.io.PrintStream getOut()

      Get the outptut stream associated with this interpreter. This may be be stdout or the GUI console.
      Specified by:
        `getOut` in interface `ConsoleInterface`

    - #### getErr

          public java.io.PrintStream getErr()

      Get the error output stream associated with this interpreter. This may be be stderr or the GUI console.
      Specified by:
        `getErr` in interface `ConsoleInterface`

    - #### println

          public final void println(java.lang.Object o)

      Specified by:
        `println` in interface `ConsoleInterface`

    - #### print

          public final void print(java.lang.Object o)

      Specified by:
        `print` in interface `ConsoleInterface`

    - #### debug

          public static final void debug(java.lang.String s)

      Print a debug message on debug stream associated with this interpreter only if debugging is turned on.

    - #### get

          public java.lang.Object get(java.lang.String name)
                               throws EvalError

      Get the value of the name. name may be any value. e.g. a variable or field
      Throws:
        `EvalError`

    - #### set

          public void set(java.lang.String name,
                          java.lang.Object value)
                   throws EvalError

      Assign the value to the name. name may evaluate to anything assignable. e.g. a variable or field.
      Throws:
        `EvalError`

    - #### set

          public void set(java.lang.String name,
                          long value)
                   throws EvalError

      Throws:
        `EvalError`

    - #### set

          public void set(java.lang.String name,
                          int value)
                   throws EvalError

      Throws:
        `EvalError`

    - #### set

          public void set(java.lang.String name,
                          double value)
                   throws EvalError

      Throws:
        `EvalError`

    - #### set

          public void set(java.lang.String name,
                          float value)
                   throws EvalError

      Throws:
        `EvalError`

    - #### set

          public void set(java.lang.String name,
                          boolean value)
                   throws EvalError

      Throws:
        `EvalError`

    - #### unset

          public void unset(java.lang.String name)
                     throws EvalError

      Unassign the variable name. Name should evaluate to a variable.
      Throws:
        `EvalError`

    - #### getInterface

          public java.lang.Object getInterface(java.lang.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.

      Throws:
        `EvalError` - if the interface cannot be generated because the version of Java does not support the proxy mechanism.

    - #### pathToFile

          public java.io.File pathToFile(java.lang.String fileName)
                                  throws java.io.IOException

      Localize a path to the file name based on the bsh.cwd interpreter working directory.
      Throws:
        `java.io.IOException`

    - #### redirectOutputToFile

          public static void redirectOutputToFile(java.lang.String filename)

    - #### setClassLoader

          public void setClassLoader(java.lang.ClassLoader externalCL)

      Set an external class loader to be used as the base classloader for BeanShell. The base classloader is used for all classloading unless/until the addClasspath()/setClasspath()/reloadClasses() commands are called to modify the interpreter's classpath. At that time the new paths /updated paths are added on top of the base classloader.

      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.

      See Also:
        `BshClassManager.setClassLoader( ClassLoader )`

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

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

    - #### getStrictJava

          public boolean getStrictJava()

      See Also:
        `setStrictJava( boolean )`

    - #### getSourceFileInfo

          public java.lang.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.
      See Also:
        `SimpleNode.getSourceFile()`

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

    - #### setOut

          public void setOut(java.io.PrintStream out)

    - #### setErr

          public void setErr(java.io.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).

    - #### setShowResults

          public void setShowResults(boolean showResults)

      Turn on/off the verbose printing of results as for the show() command. If this interpreter has a parent the call is delegated. See the BeanShell show() command.

    - #### getShowResults

          public boolean getShowResults()

      Show on/off verbose printing status for the show() command. See the BeanShell show() command. If this interpreter has a parent the call is delegated.