sleep.runtime
Class ScriptEnvironment

java.lang.Object
  sleep.runtime.ScriptEnvironment

All Implemented Interfaces:

java.io.Serializable

public class ScriptEnvironment
extends java.lang.Object
implements java.io.Serializable

This class contains methods for accessing the data stack, return value of a function, and the environment hashtable for a script. In sleep each ScriptInstance has a ScriptEnvironment object associated with it. Most of the functions in this class are used internally by sleep.

For the developers purposes, this class is your gateway into the runtime environment of a script.

If you use the evaluate methods to evaluate a snippet of code, they will be evaluated as if they were part of the script file that this ScriptEnvironment represents.

The Hashtable environment contains references for all of the loaded bridges this script has access to. Every function, predicate, and operator is specified in the environment hashtable. To force scripts to share this information use setEnvironment(Hashtable) and pass the same instance of Hashtable that other scripts are using.

This class is instantiated by sleep.runtime.ScriptInstance.

See Also:

ScriptLoader, ScriptInstance, Serialized Form

Nested Class Summary

protected static class	ScriptEnvironment.Context
protected static class	ScriptEnvironment.ExceptionContext

Field Summary

protected java.util.Stack	context
protected java.util.Stack	contextStack
protected ScriptEnvironment.ExceptionContext	currentHandler
protected java.lang.String	debugString
protected java.util.Hashtable	environment the environment hashtable that contains all of the functions, predicates, operators, and "environment keywords" this script has access to.
protected java.util.Stack	environmentStack the runtime data stack for this environment
protected java.lang.Object	errorMessage stored error message...
protected java.util.Stack	exhandlers
protected int	findex
static int	FLOW_CONTROL_BREAK request a break out of the current loop
static int	FLOW_CONTROL_CALLCC adding a callcc keyword
static int	FLOW_CONTROL_CONTINUE adding a continue keyword as people keep demanding it
static int	FLOW_CONTROL_DEBUG a special case for debugs and such
static int	FLOW_CONTROL_NONE currently no flow control change has been requested
static int	FLOW_CONTROL_PASS a special case, pass control flow to the return value (it better be a function!)
static int	FLOW_CONTROL_RETURN request a return from the current function
static int	FLOW_CONTROL_THROW adding a throw keyword -- sleep is now useable :)
static int	FLOW_CONTROL_YIELD adding a yield keyword
protected java.util.ArrayList	frames
protected java.util.HashMap	metadata
protected java.util.Stack	metaStack
protected boolean	moreHandlers
protected int	request
protected Scalar	rv
protected ScriptInstance	self the script instance that this is the environment for
protected java.util.Stack	sources how many stacks does this damned class include?

Constructor Summary

ScriptEnvironment()
Not recommended that you instantiate a script environment in this way

ScriptEnvironment(java.util.Hashtable env, ScriptInstance myscript)
Instantiate a new script environment with the specified environment (can be shared), and the specified ScriptInstance

Method Summary

void	addToContext(Block b, Step s)
Scalar	checkError() once an error is checked using this function, it is cleared, the orignal error message is returned as well
void	cleanFrame(int mark) markFrame and cleanFrame are used to keep the sleep stack in good order after certain error conditions
void	clearReturn() Clears the return value from the last executed function.
void	CreateFrame()
void	CreateFrame(java.util.Stack frame)
Scalar	evaluateExpression(java.lang.String code) evaluates an expression
Scalar	evaluateOldContext()
Scalar	evaluateParsedLiteral(java.lang.String code) evaluates the passed in code as if it was a sleep parsed literal
boolean	evaluatePredicate(java.lang.String code) evaluates a predicate condition
Scalar	evaluateStatement(java.lang.String code) evaluate a full blown statement...
void	flagError(java.lang.Object message) A utility for bridge writers to flag an error.
void	flagReturn(Scalar value, int type_of_flow) flags a return value for this script environment
void	FrameResult(Scalar value) kills the current frame and if there is a parent frame pushes the specified value on to it
Block	getBlock(java.lang.String name)
java.lang.Object	getContextMetadata(java.lang.Object key) Returns the data associated with the particular key for this context.
java.lang.Object	getContextMetadata(java.lang.Object key, java.lang.Object default_value) Returns the data associated with the particular key for this context.
java.util.Stack	getCurrentFrame()
java.lang.String	getCurrentSource() obtain the filename of the current source of execution
java.lang.String	getDebugString()
java.util.Hashtable	getEnvironment() Returns the environment for this script.
java.util.Stack	getEnvironmentStack() returns the environment stack used for temporary calculations and such.
Block	getExceptionHandler() preps and returns the current exception handler...
Scalar	getExceptionMessage() if there is no handler, we'll just get the message which will clear the thrown message as well
FilterEnvironment	getFilterEnvironment(java.lang.String env)
int	getFlowControlRequest()
Function	getFunction(java.lang.String func)
Environment	getFunctionEnvironment(java.lang.String env)
Operator	getOperator(java.lang.String oper)
Predicate	getPredicate(java.lang.String name)
PredicateEnvironment	getPredicateEnvironment(java.lang.String env)
Scalar	getReturnValue()
Scalar	getScalar(java.lang.String key) returns a scalar from this scripts environment
ScriptInstance	getScriptInstance() returns a reference to the script associated with this environment
ScriptVariables	getScriptVariables() returns the variable manager for this script
boolean	hasFrame()
void	installExceptionHandler(Block owner, Block handler, java.lang.String varname)
void	installExceptionHandler(ScriptEnvironment.ExceptionContext exc)
boolean	isCallCC()
boolean	isDebugInterrupt()
boolean	isExceptionHandlerInstalled()
boolean	isPassControl()
boolean	isResponsible(Block block)
boolean	isReturn()
boolean	isThrownValue()
boolean	isYield()
void	KillFrame()
void	loadContext(java.util.Stack _context, java.util.HashMap _metadata)
int	markFrame() markFrame and cleanFrame are used to keep the sleep stack in good order after certain error conditions
ScriptEnvironment.ExceptionContext	popExceptionContext()
void	popSource() remove the latest source information from the source stack
void	pushSource(java.lang.String s) push source information onto the source stack
void	putScalar(java.lang.String key, Scalar value) puts a scalar into this scripts environment (global scope)
void	resetEnvironment() Resets the script environment to include clearing the return of all flags (including thrown exceptions)
java.util.Stack	saveContext()
void	setContextMetadata(java.lang.Object key, java.lang.Object value) Use this function to save some meta data for this particular closure context, passing null for value will remove the key from the metadata for this context.
void	setEnvironment(java.util.Hashtable h) Sets the environment Hashtable this script is to use.
void	showDebugMessage(java.lang.String message) fires this debug message via a runtime warning complete with line number of current step
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

self

protected ScriptInstance self

the script instance that this is the environment for

environmentStack

protected java.util.Stack environmentStack

the runtime data stack for this environment

environment

protected java.util.Hashtable environment

the environment hashtable that contains all of the functions, predicates, operators, and "environment keywords" this script has access to.

errorMessage

protected java.lang.Object errorMessage

stored error message...

context

protected java.util.Stack context

contextStack

protected java.util.Stack contextStack

metadata

protected java.util.HashMap metadata

metaStack

protected java.util.Stack metaStack

currentHandler

protected ScriptEnvironment.ExceptionContext currentHandler

exhandlers

protected java.util.Stack exhandlers

moreHandlers

protected boolean moreHandlers

FLOW_CONTROL_NONE

public static final int FLOW_CONTROL_NONE

currently no flow control change has been requested

See Also:

Constant Field Values

FLOW_CONTROL_RETURN

public static final int FLOW_CONTROL_RETURN

request a return from the current function

See Also:

Constant Field Values

FLOW_CONTROL_BREAK

public static final int FLOW_CONTROL_BREAK

request a break out of the current loop

See Also:

Constant Field Values

FLOW_CONTROL_CONTINUE

public static final int FLOW_CONTROL_CONTINUE

adding a continue keyword as people keep demanding it

See Also:

Constant Field Values

FLOW_CONTROL_YIELD

public static final int FLOW_CONTROL_YIELD

adding a yield keyword

See Also:

Constant Field Values

FLOW_CONTROL_THROW

public static final int FLOW_CONTROL_THROW

adding a throw keyword -- sleep is now useable :)

See Also:

Constant Field Values

FLOW_CONTROL_DEBUG

public static final int FLOW_CONTROL_DEBUG

a special case for debugs and such

See Also:

Constant Field Values

FLOW_CONTROL_CALLCC

public static final int FLOW_CONTROL_CALLCC

adding a callcc keyword

See Also:

Constant Field Values

FLOW_CONTROL_PASS

public static final int FLOW_CONTROL_PASS

a special case, pass control flow to the return value (it better be a function!)

See Also:

Constant Field Values

debugString

protected java.lang.String debugString

rv

protected Scalar rv

request

protected int request

sources

protected java.util.Stack sources

how many stacks does this damned class include?

frames

protected java.util.ArrayList frames

findex

protected int findex

Constructor Detail

ScriptEnvironment

public ScriptEnvironment()

Not recommended that you instantiate a script environment in this way

ScriptEnvironment

public ScriptEnvironment(java.util.Hashtable env,
                         ScriptInstance myscript)

Instantiate a new script environment with the specified environment (can be shared), and the specified ScriptInstance

Method Detail

getScriptInstance

public ScriptInstance getScriptInstance()

returns a reference to the script associated with this environment

flagError

public void flagError(java.lang.Object message)

A utility for bridge writers to flag an error. flags an error that script writers can then check for with checkError(). Currently used by the IO bridge openf, exec, and connect functions. Major errors should bubble up as exceptions. Small stuff like being unable to open a certain file should be flagged this way.

checkError

public Scalar checkError()

once an error is checked using this function, it is cleared, the orignal error message is returned as well

getScriptVariables

public ScriptVariables getScriptVariables()

returns the variable manager for this script

getScalar

public Scalar getScalar(java.lang.String key)

returns a scalar from this scripts environment

putScalar

public void putScalar(java.lang.String key,
                      Scalar value)

puts a scalar into this scripts environment (global scope)

getBlock

public Block getBlock(java.lang.String name)

getFunction

public Function getFunction(java.lang.String func)

getFunctionEnvironment

public Environment getFunctionEnvironment(java.lang.String env)

getPredicateEnvironment

public PredicateEnvironment getPredicateEnvironment(java.lang.String env)

getFilterEnvironment

public FilterEnvironment getFilterEnvironment(java.lang.String env)

getPredicate

public Predicate getPredicate(java.lang.String name)

getOperator

public Operator getOperator(java.lang.String oper)

getEnvironment

public java.util.Hashtable getEnvironment()

Returns the environment for this script. The environment has the following formats for keys: &[keyname] - a sleep function -[keyname] - assumed to be a unary predicate [keyname] - assumed to be an environment binding, predicate, or operator

setEnvironment

public void setEnvironment(java.util.Hashtable h)

Sets the environment Hashtable this script is to use. Sharing an instance of this Hashtable allows scripts to share common environment data like functions, subroutines, etc. Also useful for bridge writers as their information can be stored in this hashtable as well

getEnvironmentStack

public java.util.Stack getEnvironmentStack()

returns the environment stack used for temporary calculations and such.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

loadContext

public void loadContext(java.util.Stack _context,
                        java.util.HashMap _metadata)

setContextMetadata

public void setContextMetadata(java.lang.Object key,
                               java.lang.Object value)

Use this function to save some meta data for this particular closure context, passing null for value will remove the key from the metadata for this context. Note: context metadata is *not* serialized when the closure is serialized.

getContextMetadata

public java.lang.Object getContextMetadata(java.lang.Object key)

Returns the data associated with the particular key for this context.

getContextMetadata

public java.lang.Object getContextMetadata(java.lang.Object key,
                                           java.lang.Object default_value)

Returns the data associated with the particular key for this context. If the key value is null then the specified default_value is returned

addToContext

public void addToContext(Block b,
                         Step s)

evaluateOldContext

public Scalar evaluateOldContext()

saveContext

public java.util.Stack saveContext()

isExceptionHandlerInstalled

public boolean isExceptionHandlerInstalled()

isResponsible

public boolean isResponsible(Block block)

installExceptionHandler

public void installExceptionHandler(ScriptEnvironment.ExceptionContext exc)

installExceptionHandler

public void installExceptionHandler(Block owner,
                                    Block handler,
                                    java.lang.String varname)

getExceptionMessage

public Scalar getExceptionMessage()

if there is no handler, we'll just get the message which will clear the thrown message as well

getExceptionHandler

public Block getExceptionHandler()

preps and returns the current exception handler...

popExceptionContext

public ScriptEnvironment.ExceptionContext popExceptionContext()

isThrownValue

public boolean isThrownValue()

isDebugInterrupt

public boolean isDebugInterrupt()

isYield

public boolean isYield()

isCallCC

public boolean isCallCC()

isPassControl

public boolean isPassControl()

getReturnValue

public Scalar getReturnValue()

isReturn

public boolean isReturn()

getFlowControlRequest

public int getFlowControlRequest()

getDebugString

public java.lang.String getDebugString()

showDebugMessage

public void showDebugMessage(java.lang.String message)

fires this debug message via a runtime warning complete with line number of current step

flagReturn

public void flagReturn(Scalar value,
                       int type_of_flow)

flags a return value for this script environment

resetEnvironment

public void resetEnvironment()

Resets the script environment to include clearing the return of all flags (including thrown exceptions)

clearReturn

public void clearReturn()

Clears the return value from the last executed function.

pushSource

public void pushSource(java.lang.String s)

push source information onto the source stack

getCurrentSource

public java.lang.String getCurrentSource()

obtain the filename of the current source of execution

popSource

public void popSource()

remove the latest source information from the source stack

markFrame

public int markFrame()

markFrame and cleanFrame are used to keep the sleep stack in good order after certain error conditions

cleanFrame

public void cleanFrame(int mark)

markFrame and cleanFrame are used to keep the sleep stack in good order after certain error conditions

getCurrentFrame

public java.util.Stack getCurrentFrame()

FrameResult

public void FrameResult(Scalar value)

kills the current frame and if there is a parent frame pushes the specified value on to it

hasFrame

public boolean hasFrame()

KillFrame

public void KillFrame()

CreateFrame

public void CreateFrame(java.util.Stack frame)

CreateFrame

public void CreateFrame()

evaluateStatement

public Scalar evaluateStatement(java.lang.String code)
                         throws YourCodeSucksException

evaluate a full blown statement... probably best to just load a script at this point

Throws:

YourCodeSucksException

evaluatePredicate

public boolean evaluatePredicate(java.lang.String code)
                          throws YourCodeSucksException

evaluates a predicate condition

Throws:

YourCodeSucksException

evaluateExpression

public Scalar evaluateExpression(java.lang.String code)
                          throws YourCodeSucksException

evaluates an expression

Throws:

YourCodeSucksException

evaluateParsedLiteral

public Scalar evaluateParsedLiteral(java.lang.String code)
                             throws YourCodeSucksException

evaluates the passed in code as if it was a sleep parsed literal

Throws:

YourCodeSucksException