Package com.blackrook.rookscript

Class ScriptInstance

java.lang.Object
com.blackrook.rookscript.ScriptInstance
public class ScriptInstance extends Object
A single script instance.
Since:
1.8.0, Script Scope attachment is done on the script, not the instance.
Author:
Matthew Tropiano

  • Field Details

  • Constructor Details

    • ScriptInstance

      public ScriptInstance(Script script, ScriptInstanceStack scriptInstanceStack, ScriptEnvironment environment)
      Creates a new script instance, no wait handler, default runaway limit.
      Parameters:
      script - the script that holds the code.
      scriptInstanceStack - the instance stack.
      environment - the script environment to use.

    • ScriptInstance

      public ScriptInstance(Script script, ScriptInstanceStack scriptInstanceStack, ScriptEnvironment environment, int runawayLimit)
      Creates a new script instance, no wait handler.
      Parameters:
      script - the script that holds the code.
      scriptInstanceStack - the instance stack.
      environment - the script environment to use.
      runawayLimit - the runaway script command limit. 0 or less is no limit.

    • ScriptInstance

      public ScriptInstance(Script script, ScriptInstanceStack scriptInstanceStack, ScriptWaitHandler waitHandler, ScriptEnvironment environment, int runawayLimit)
      Creates a new script instance.
      Parameters:
      script - the script that holds the code.
      scriptInstanceStack - the instance stack.
      waitHandler - the handler for handling a script in a waiting state (can be null).
      environment - the script environment to use.
      runawayLimit - the runaway script command limit. 0 or less is no limit.
      Throws:
      IllegalArgumentException - if script or scriptInstanceStack

  • Method Details

    • createBuilder

      public static ScriptInstanceBuilder createBuilder()
      Returns a new builder for creating a new script instance piece by piece.
      Returns:
      a new ScriptInstanceBuilder object.

    • reset

      public void reset()
      Resets the instance.

    • getScript

      public Script getScript()
      Gets this instance's script reference.
      Returns:
      the script.

    • getState

      public ScriptInstance.State getState()
      Returns:
      the current script execution state.

    • getEntryName

      public String getEntryName()
      Gets the entry name that was used to start this script. Can be null if not started from an entry.
      Returns:
      the entry name that was used to start this script or null.

    • getEnvironment

      public ScriptEnvironment getEnvironment()
      Returns this script's script environment.
      Returns:
      the scope resolver.

    • getHostFunctionResolver

      public ScriptHostFunctionResolver getHostFunctionResolver()
      Returns this script's host function resolver.
      Returns:
      the function resolver.

    • getScopeResolver

      public ScriptScopeResolver getScopeResolver()
      Returns this script's scope resolver.
      Returns:
      the scope resolver.

    • setCommandRunawayLimit

      public void setCommandRunawayLimit(int commandRunawayLimit)
      Sets the amount of commands that can be executed in one update before the runaway detection is triggered. By default, this is 0, which means no detection.
      Parameters:
      commandRunawayLimit - the amount of commands.

    • getCommandRunawayLimit

      public int getCommandRunawayLimit()
      Gets the amount of commands that can be executed in one update before the runaway detection is triggered. By default, this is 0, which means no detection.
      Returns:
      the amount of commands.

    • call

      public void call(String entryName, Object... parameters)
      Initializes the script with an entry point and parameters and calls update() to execute it. The return value for the entry point should still be on the stack.
      Parameters:
      entryName - the entry point name.
      parameters - the starting parameters to push onto the stack.
      Throws:
      ScriptExecutionException - if the provided amount of parameters do not match the amount of parameters that the script requires, or the provided entry point does not exist.
      See Also:

    • callAndReturnAs

      public <T> T callAndReturnAs(Class<T> returnType, String entryName, Object... parameters)
      Initializes the script with an entry point and parameters and calls update() to execute it, then gets the return value off the stack converted to a provided type. If the amount of required parameters are less than the expected amount, nulls are pushed until the amount is met.
      Type Parameters:
      T - the return type.
      Parameters:
      returnType - the return type to get from the script.
      entryName - the entry point name.
      parameters - the starting parameters to push onto the stack.
      Returns:
      the returned value at the end of the script, converted to a specific class type.
      Throws:
      ClassCastException - if the conversion could not be done.
      ScriptExecutionException - if the provided amount of parameters do not match the amount of parameters that the script requires, or the provided entry point does not exist.
      See Also:

    • initialize

      public void initialize(String entryName, Object... parameters)
      Initializes the script with parameters. If the amount of parameters are less than the expected amount, nulls are pushed until the amount is met. The method update() can be called afterward.
      Parameters:
      entryName - the entry point name.
      parameters - the starting parameters to push onto the stack.
      Throws:
      ScriptExecutionException - if the provided amount of parameters do not match the amount of parameters that the script requires, or the provided entry point does not exist.

    • initializeLabel

      public void initializeLabel(String labelName)
      Initializes the script at an arbitrary label. Use with caution - this is assuming manual setup of a script instance. The method update() can be called afterward.
      Parameters:
      labelName - the script label name.
      Throws:
      ScriptExecutionException - if the provided label does not exist.

    • initializeIndex

      public void initializeIndex(int index)
      Initializes the script at an arbitrary index. Use with caution - this is assuming manual setup of a script instance. The method update() can be called afterward.
      Parameters:
      index - the command index.
      Throws:
      ScriptExecutionException - if the provided index is out of script command bounds.

    • step

      public boolean step()
      Makes a single command step in the script.
      Returns:
      false if the script should halt, true to continue.

    • update

      public void update()
      Executes the script. Note that the script may stop, but not terminate.
      Throws:
      ScriptExecutionException - if this instance is in ScriptInstance.State.CREATED state (init methods not called).

    • resume

      public void resume()
      Sets the RUNNING state. This clears a wait state, if currently waiting. Does not actually run anything - this just sets the script's state as "enabled" for a future call to update().
      See Also:

    • wait

      public void wait(Object waitType, Object waitParameter)
      Sets the WAITING state and waiting parameters. A future call to update() afterward will attempt to re-check and update the waiting state.
      Parameters:
      waitType - the type for the wait (seen by the waiting handler).
      waitParameter - the parameter for the wait (seen by the waiting handler).

    • suspend

      public void suspend()
      Sets the SUSPENDED state. This clears a wait state, if currently waiting. A call to update() afterward will do nothing.

    • terminate

      public void terminate()
      Sets the ENDED state. Also closes all registered closeables. This clears a wait state, if currently waiting. A future call to update() afterward will do nothing.
      See Also:

    • getCommandIndex

      public int getCommandIndex(String labelName)
      Gets a command index by label.
      Parameters:
      labelName - the label name.
      Returns:
      the corresponding index, or -1 for no index.

    • getCurrentCommand

      public ScriptCommand getCurrentCommand()
      Gets the current command.
      Returns:
      the current command or null if current index is outside script bounds.

    • getValue

      public boolean getValue(String name, ScriptValue out)
      Gets a corresponding script value by name. Only looks at the topmost stack scope. Changing the returned value does not change the value, unless it is a reference type like a map or list.
      Parameters:
      name - the variable name.
      out - the destination variable for the value.
      Returns:
      true if a corresponding value was fetched into out, false if not. If false, out is set to the null value.

    • setValue

      public void setValue(String name, ScriptValue value)
      Sets a corresponding script value by name. If the value does not exist, it is set on the topmost stack scope in the stack.
      Parameters:
      name - the name of the variable.
      value - the value to set.

    • getCurrentCommandIndex

      public int getCurrentCommandIndex()
      Returns:
      the current command index.

    • setCurrentCommandIndex

      public void setCurrentCommandIndex(int index)
      Sets the current command index (jump).
      Parameters:
      index - the new index.

    • incrementCurrentCommandIndex

      public int incrementCurrentCommandIndex()
      Increments the current command index and returns it.
      Returns:
      the new current index.
      Throws:
      ScriptStackException - if this call would breach the stack capacity.

    • pushFrame

      public void pushFrame(int nextCommandIndex)
      Pushes a new activation frame (local scope and command index).
      Parameters:
      nextCommandIndex - the next command index.
      Throws:
      ScriptStackException - if this call would breach the stack capacity.

    • popFrame

      public void popFrame()
      Pops an activation frame (local scope and command index).
      Throws:
      ScriptStackException - if there's nothing on the stack when this is called.

    • getCurrentActivationStackDepth

      public int getCurrentActivationStackDepth()
      Gets the activation (frame) depth. If 0, then this is 0 functions deep - the starting entry point.
      Returns:
      the depth of the activation stack.

    • pushStackValue

      public <T> void pushStackValue(T value)
      Pushes a value onto the stack.
      Type Parameters:
      T - the value type.
      Parameters:
      value - the value to push.
      Throws:
      ScriptStackException - if this call would breach the stack capacity.

    • popStackValue

      public void popStackValue(ScriptValue out)
      Pops a value off the stack.
      Parameters:
      out - the output value.
      Throws:
      ScriptStackException - if there's nothing on the stack when this is called.

    • popStackValue

      public void popStackValue()
      Pops a value off the stack, ignoring output.
      Throws:
      ScriptStackException - if there's nothing on the stack when this is called.

    • getStackValue

      public void getStackValue(int depth, ScriptValue out)
      Gets a value on the stack (reference).
      Parameters:
      depth - the depth from the top (0 is top, 1 ... N is N places down).
      out - the output value.
      Throws:
      ScriptStackException - if the top minus the depth escapes the active stack bounds.

    • clearStackValues

      public void clearStackValues()
      Clears the value stack.

    • registerCloseable

      public void registerCloseable(AutoCloseable closeable)
      Registers a resource that will be automatically closed when this instance terminates. Function calls that open resources should call this.
      Parameters:
      closeable - the closeable to add to the instance registry.

    • closeableIsRegistered

      public boolean closeableIsRegistered(AutoCloseable closeable)
      Checks if a closeable resource is registered on this instance.
      Parameters:
      closeable - the closeable to look for.
      Returns:
      true if it is, false if it isn't.

    • unregisterCloseable

      public void unregisterCloseable(AutoCloseable closeable)
      Unregisters a resource that should be closed when this instance terminates. Function calls that close resources should call this.
      Parameters:
      closeable - the closeable to remove from the instance registry.

    • closeAllCloseables

      public void closeAllCloseables()
      Unregisters and closes all closeable resources that are registered on this instance. This is called when the instance enters the "terminated" state.
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object