org.hecl
Class Interp

java.lang.Object
  extended by java.lang.Thread
      extended by org.hecl.Interp
All Implemented Interfaces:
java.lang.Runnable

public class Interp
extends java.lang.Thread

Interp is the Hecl interpreter, the class responsible for knowing what variables and commands are available.

Version:
1.0
Author:
David N. Welton

Nested Class Summary
protected static class Interp.WaitToken
           
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
static int ALL_EVENTS
           
static java.lang.String ASYNCPREFIX
          Some string constants used to generate names for internal events.
protected  java.util.Vector asyncs
           
protected  java.util.Hashtable auxdata
          The auxdata Hashtable is a place to store extra information about the state of the program.
 long cacheversion
           
protected  java.util.Vector ci
           
protected  java.util.Hashtable classcmdcache
           
protected  java.util.Hashtable commands
          The commands Hashtable provides the mapping from the strings containing command names to the code implementing the commands.
 Thing currentFile
           
static int DONT_WAIT
          Flags for the event loop.
static char[] eol
          eol is the end-of-line character or characters.
protected  java.util.Stack error
           
static java.lang.String fileseparator
          fileseparator is the file separator, such as "/".
protected  java.util.Vector idle
           
static int IDLE_EVENTS
           
protected  long idlegeneration
           
static java.lang.String IDLEPREFIX
           
protected  long maxblocktime
           
static java.lang.String MODULE_CLASS_PACKAGE
          Package name prefix of the module classes.
 java.lang.String PROMPT
          The prompt for the readEvalPrint loop.
 java.lang.String PROMPT2
          The prompt for continued lines in the readEvalPrint loop.
protected  boolean running
           
protected  java.util.Stack stack
           
static int TIMER_EVENTS
           
static java.lang.String TIMERPREFIX
           
protected  java.util.Vector timers
           
protected  java.util.Hashtable waittokens
           
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
Interp()
          Creates a new Interp instance, initializing command and variable hashtables, a stack, and an error stack.
 
Method Summary
 void addClassCmd(java.lang.Class clazz, ClassCommand cmd)
          Add a new class command to an Interp.
 java.lang.String addCommand(java.lang.String name, Command c)
          Add a new command to an Interp.
 void addError(Thing err)
          addError adds a Thing as an error message.
 HeclTask addTimer(Thing timerThing, int millisecs)
           
 void backgroundError(java.lang.String errorMessage)
          The backgroundError method can be called to dispatch a bgerror command.
 void cancelAsync(java.lang.String name)
           
 void cancelIdle(HeclTask idletask)
           
 void cancelIdle(java.lang.String name)
           
 void cancelTimer(java.lang.String name)
           
static void checkArgCount(Thing[] argv, int minargs, int maxargs)
          checkArgCount checks to see whether the command actually has the required number of arguments.
 void clearError()
          clearError clears the error stack.
 void cmdAlias(java.lang.String oldname, java.lang.String newname)
           
 void cmdRename(java.lang.String oldname, java.lang.String newname)
          The cmdRename method renames a command, or throws an error if the original command didn't exist.
 boolean commandExists(java.lang.String name)
          The commandExists method returns true if a command exists, otherwise false.
 boolean doOneEvent(int flags)
           
 Thing eval(Thing in)
          The eval method evaluates some Hecl code passed to it.
 Thing eval(Thing in, int level)
          This version of eval takes a 'level' argument that tells Hecl what level to run the code at.
 HeclTask evalAsync(Thing asyncThing)
           
 Thing evalAsyncAndWait(Thing in)
           
 HeclTask evalIdle(Thing idleThing)
           
 boolean existsVar(java.lang.String varname)
          existsVar returns true if the given variable exists in the current variable stack frame, false if it does not.
 boolean existsVar(java.lang.String varname, int level)
          existsVar returns true if the given variable exists in the variable stack frame given by level, false if it does not.
 boolean existsVar(Thing varname)
          existsVar returns true if the given variable exists in the current variable stack frame, false if it does not.
 java.util.Vector getAllEvents()
           
 java.lang.Object getAuxData(java.lang.String key)
          Retrieve auxiliary data from an Interp.
 HeclTask getEvent(java.lang.String name)
           
 Thing getVar(java.lang.String varname)
          getVar returns the value of a variable given its name.
 Thing getVar(java.lang.String varname, int level)
          getVar returns the value of a variable given its name and level.
 Thing getVar(Thing varname)
          getVar returns the value of a variable given its name.
protected  java.lang.String[] hashKeysToArray(java.util.Hashtable h)
           
protected  java.lang.String[] hashKeysToArray(java.util.Hashtable h, java.lang.String prefix)
           
 boolean hasIdleTasks()
           
protected  HeclTask nextTask(java.util.Vector v, long until)
          nextTask extracts first element from given vector.
 void notifyToken(java.lang.String tokenname)
           
 void readEvalPrint(java.io.InputStream in, java.io.PrintStream out, java.io.PrintStream err)
          The commandLine method implements a Read/Eval/Print Loop.
 void removeAuxData(java.lang.String key)
          Remove auxiliary data from an Interp.
 void removeClassCmd(java.lang.Class clazz)
          Remove a command for a specific class from an Interp.
 void removeCommand(java.lang.String name)
          Remove a command from an Interp.
 void run()
           
protected  boolean serviceIdleTask()
          Service at most one idle task of the idle task queue.
 void setAuxData(java.lang.String key, java.lang.Object value)
          Attach auxiliary data to an Interp.
 void setVar(java.lang.String varname, Thing value)
          setVar sets a variable in the innermost variable stack frame to a value.
 void setVar(java.lang.String varname, Thing value, int level)
          setVar sets a variable to a value in the variable stack frame specified by level.
 void setVar(Thing varname, Thing value)
          setVar sets a variable in the innermost variable stack frame to a value.
 java.util.Hashtable stackDecr()
          stackDecr pops the stack frame, returning it so that commands like upeval can save it.
 void stackIncr()
          The stackIncr method creates a new stack frame.
 void stackPush(java.util.Hashtable vars)
          stackDecr pushes a new variable hashtable (probably saved via upeval) onto the stack frame.
 void terminate()
          The terminate method terminates the Hecl interpreter thread in a graceful manner.
 void unSetVar(java.lang.String varname)
           
 void unSetVar(java.lang.String varname, int level)
           
 void unSetVar(Thing varname)
          unSetVar unsets a variable in the current stack frame.
 void waitForToken(java.lang.String tokenname)
           
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MODULE_CLASS_PACKAGE

public static final java.lang.String MODULE_CLASS_PACKAGE
Package name prefix of the module classes.

See Also:
Constant Field Values

DONT_WAIT

public static final int DONT_WAIT
Flags for the event loop.

See Also:
Constant Field Values

IDLE_EVENTS

public static final int IDLE_EVENTS
See Also:
Constant Field Values

TIMER_EVENTS

public static final int TIMER_EVENTS
See Also:
Constant Field Values

ALL_EVENTS

public static final int ALL_EVENTS
See Also:
Constant Field Values

ASYNCPREFIX

public static final java.lang.String ASYNCPREFIX
Some string constants used to generate names for internal events.

See Also:
Constant Field Values

IDLEPREFIX

public static final java.lang.String IDLEPREFIX
See Also:
Constant Field Values

TIMERPREFIX

public static final java.lang.String TIMERPREFIX
See Also:
Constant Field Values

PROMPT

public final java.lang.String PROMPT
The prompt for the readEvalPrint loop.

See Also:
Constant Field Values

PROMPT2

public final java.lang.String PROMPT2
The prompt for continued lines in the readEvalPrint loop.

See Also:
Constant Field Values

cacheversion

public long cacheversion

commands

protected java.util.Hashtable commands
The commands Hashtable provides the mapping from the strings containing command names to the code implementing the commands.


auxdata

protected java.util.Hashtable auxdata
The auxdata Hashtable is a place to store extra information about the state of the program.


stack

protected java.util.Stack stack

error

protected java.util.Stack error

timers

protected java.util.Vector timers

asyncs

protected java.util.Vector asyncs

idle

protected java.util.Vector idle

waittokens

protected java.util.Hashtable waittokens

idlegeneration

protected long idlegeneration

running

protected boolean running

maxblocktime

protected long maxblocktime

ci

protected java.util.Vector ci

classcmdcache

protected java.util.Hashtable classcmdcache

eol

public static final char[] eol
eol is the end-of-line character or characters.


fileseparator

public static final java.lang.String fileseparator
fileseparator is the file separator, such as "/".


currentFile

public Thing currentFile
Constructor Detail

Interp

public Interp()
       throws HeclException
Creates a new Interp instance, initializing command and variable hashtables, a stack, and an error stack.

Throws:
HeclException - if an error occurs
Method Detail

hashKeysToArray

protected java.lang.String[] hashKeysToArray(java.util.Hashtable h)

hashKeysToArray

protected java.lang.String[] hashKeysToArray(java.util.Hashtable h,
                                             java.lang.String prefix)

readEvalPrint

public void readEvalPrint(java.io.InputStream in,
                          java.io.PrintStream out,
                          java.io.PrintStream err)
The commandLine method implements a Read/Eval/Print Loop.

Parameters:
in - Input stream to read input from.
out - Output stream to print results to.
err - Output stream for error messages. This function never returns.

addClassCmd

public void addClassCmd(java.lang.Class clazz,
                        ClassCommand cmd)
Add a new class command to an Interp.

Parameters:
clazz - The Java class the command should operate on.
cmd - The command to add. When this paramter is null, an existing command is removed.

removeClassCmd

public void removeClassCmd(java.lang.Class clazz)
Remove a command for a specific class from an Interp.

Parameters:
clazz - The class to remove the command for.

addCommand

public java.lang.String addCommand(java.lang.String name,
                                   Command c)
Add a new command to an Interp.

Parameters:
name - the name of the command to add.
c - the command to add.

removeCommand

public void removeCommand(java.lang.String name)
Remove a command from an Interp.

Parameters:
name - the name of the command to add.

commandExists

public boolean commandExists(java.lang.String name)
The commandExists method returns true if a command exists, otherwise false.

Parameters:
name - a String value
Returns:
a boolean value

setAuxData

public void setAuxData(java.lang.String key,
                       java.lang.Object value)
Attach auxiliary data to an Interp.


getAuxData

public java.lang.Object getAuxData(java.lang.String key)
Retrieve auxiliary data from an Interp.

Returns:
a Object value or null when no auxiliary data under the given key is attached to the interpreter.

removeAuxData

public void removeAuxData(java.lang.String key)
Remove auxiliary data from an Interp.


eval

public Thing eval(Thing in)
           throws HeclException
The eval method evaluates some Hecl code passed to it.

Returns:
a Thing value - the result of the evaluation.
Throws:
HeclException - if an error occurs.

evalIdle

public HeclTask evalIdle(Thing idleThing)

evalAsync

public HeclTask evalAsync(Thing asyncThing)

evalAsyncAndWait

public Thing evalAsyncAndWait(Thing in)
                       throws HeclException
Throws:
HeclException

eval

public Thing eval(Thing in,
                  int level)
           throws HeclException
This version of eval takes a 'level' argument that tells Hecl what level to run the code at. Level 0 means global, negative numbers indicate relative levels down from the current stackframe, and positive numbers mean absolute stack frames counting up from 0.

Parameters:
in - a Thing value
level - an int value
Returns:
a Thing value
Throws:
HeclException - if an error occurs

hasIdleTasks

public boolean hasIdleTasks()

getEvent

public HeclTask getEvent(java.lang.String name)

getAllEvents

public java.util.Vector getAllEvents()

addTimer

public HeclTask addTimer(Thing timerThing,
                         int millisecs)

cancelTimer

public void cancelTimer(java.lang.String name)

cancelIdle

public void cancelIdle(java.lang.String name)

cancelAsync

public void cancelAsync(java.lang.String name)

cancelIdle

public void cancelIdle(HeclTask idletask)

doOneEvent

public boolean doOneEvent(int flags)

waitForToken

public void waitForToken(java.lang.String tokenname)
                  throws HeclException
Throws:
HeclException

notifyToken

public void notifyToken(java.lang.String tokenname)
                 throws HeclException
Throws:
HeclException

terminate

public void terminate()
The terminate method terminates the Hecl interpreter thread in a graceful manner. The thread will eventually finish its run-method.


run

public void run()
Specified by:
run in interface java.lang.Runnable
Overrides:
run in class java.lang.Thread

cmdRename

public void cmdRename(java.lang.String oldname,
                      java.lang.String newname)
               throws HeclException
The cmdRename method renames a command, or throws an error if the original command didn't exist.

Parameters:
oldname - a String value
newname - a String value
Throws:
HeclException - if an error occurs

cmdAlias

public void cmdAlias(java.lang.String oldname,
                     java.lang.String newname)
              throws HeclException
Throws:
HeclException

stackIncr

public void stackIncr()
The stackIncr method creates a new stack frame. Used in the Proc class.


stackDecr

public java.util.Hashtable stackDecr()
stackDecr pops the stack frame, returning it so that commands like upeval can save it. If it's not saved, it's gone.


stackPush

public void stackPush(java.util.Hashtable vars)
stackDecr pushes a new variable hashtable (probably saved via upeval) onto the stack frame.


getVar

public Thing getVar(Thing varname)
             throws HeclException
getVar returns the value of a variable given its name.

Parameters:
varname - a Thing value
Returns:
a Thing value
Throws:
HeclException - if an error occurs

getVar

public Thing getVar(java.lang.String varname)
             throws HeclException
getVar returns the value of a variable given its name.

Parameters:
varname - a String value
Returns:
a Thing value
Throws:
HeclException - if an error occurs

getVar

public Thing getVar(java.lang.String varname,
                    int level)
             throws HeclException
getVar returns the value of a variable given its name and level.

Parameters:
varname - a String value
level - an int value
Returns:
a Thing value
Throws:
HeclException - if an error occurs

setVar

public void setVar(Thing varname,
                   Thing value)
            throws HeclException
setVar sets a variable in the innermost variable stack frame to a value.

Parameters:
varname - a Thing value
value - a Thing value
Throws:
HeclException

setVar

public void setVar(java.lang.String varname,
                   Thing value)
setVar sets a variable in the innermost variable stack frame to a value.

Parameters:
varname - a String value
value - a Thing value

setVar

public void setVar(java.lang.String varname,
                   Thing value,
                   int level)
setVar sets a variable to a value in the variable stack frame specified by level.

Parameters:
varname - a String value
value - a Thing value
level - an int value

unSetVar

public void unSetVar(Thing varname)
              throws HeclException
unSetVar unsets a variable in the current stack frame.

Parameters:
varname - a Thing value
Throws:
HeclException

unSetVar

public void unSetVar(java.lang.String varname)
              throws HeclException
Throws:
HeclException

unSetVar

public void unSetVar(java.lang.String varname,
                     int level)
              throws HeclException
Throws:
HeclException

existsVar

public boolean existsVar(Thing varname)
                  throws HeclException
existsVar returns true if the given variable exists in the current variable stack frame, false if it does not.

Parameters:
varname - a Thing value
Returns:
a boolean value
Throws:
HeclException

existsVar

public boolean existsVar(java.lang.String varname)
existsVar returns true if the given variable exists in the current variable stack frame, false if it does not.

Parameters:
varname - a String value
Returns:
a boolean value

existsVar

public boolean existsVar(java.lang.String varname,
                         int level)
existsVar returns true if the given variable exists in the variable stack frame given by level, false if it does not.

Parameters:
varname - a String value
level - an int value
Returns:
a boolean value

addError

public void addError(Thing err)
addError adds a Thing as an error message.

Parameters:
err - a Thing value

clearError

public void clearError()
clearError clears the error stack.


checkArgCount

public static void checkArgCount(Thing[] argv,
                                 int minargs,
                                 int maxargs)
                          throws HeclException
checkArgCount checks to see whether the command actually has the required number of arguments. The first element of the parameter array argv is not counted as argument!

Parameters:
argv - A Thing[] parameter array.
minargs - The minimal number of arguments or -1 if no check is required.
maxargs - The maximal number of arguments or -1 if no check is required.
Throws:
HeclException - if an error occurs

nextTask

protected HeclTask nextTask(java.util.Vector v,
                            long until)
nextTask extracts first element from given vector. This function operates in a synchronized manner on the argument v.

Parameters:
v - A Vector of tasks.
until - A value to compare the result of getGeneration of the HeclTask. If until is less than 0 or getGeneration is less than until for the first element of v, the first task in the vector is returned, null otherwise.

serviceIdleTask

protected boolean serviceIdleTask()
Service at most one idle task of the idle task queue.

Returns:
a boolean indicatign that an idle task has been serviced (=true) or not (=false).

backgroundError

public void backgroundError(java.lang.String errorMessage)
The backgroundError method can be called to dispatch a bgerror command.

Parameters:
errorMessage - a String value