Package ca.cgjennings.apps.arkham.plugins

Class ScriptMonkey

  • public final class ScriptMonkey
extends java.lang.Object
    A ScriptMonkey manages the execution of a script from Strange Eons.
    Author:
    Chris Jennings

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CLEAR_CONSOLE_ON_RUN_KEY
      A boolean setting key that stores whether the script output console should be cleared before running a script.
      static java.lang.String ON_INSTALL_EVENT_KEY
      If a component's private settings set this key, then the script it contains will be executed when the component is installed in an editor.
      static java.lang.String ON_PAINT_EVENT_KEY
      If a component's private settings set this key, then Sheets evaluate the script it contains and call the function onPaint( Graphics2D, GameComponent, Sheet ).
      static java.nio.charset.Charset SCRIPT_FILE_ENCODING
      The standard encoding for script code stored in a file (UTF-8).
      static java.lang.String VAR_APPLICATION
      The reserved variable name for the application instance (Eons)
      static java.lang.String VAR_COMPONENT
      The reserved variable name for the active (edited) game component (Component).
      static java.lang.String VAR_CONTEXT
      The reserved variable name for the script's PluginContext (PluginContext).
      static java.lang.String VAR_EDITOR
      The reserved variable name for the active (selected) editor (Editor).
      static java.lang.String VAR_FILE
      The reserved variable name for the source file name (sourcefile).

    • Constructor Summary

      Constructors 
      Constructor Description
      ScriptMonkey​(java.lang.String scriptFileName)
      Creates a new ScriptMonkey that can be used to execute script code.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object ambivalentCall​(java.lang.String method, java.lang.Object... args)
      Call a script function, returning null without displaying an error if the method does not exist.
      void bind​(PluginContext pluginContext)
      Binds the specified PluginContext to the global scope.
      void bind​(java.lang.String name, java.lang.Object object)
      Bind a value to a variable name in the global scope of the script.
      void bindToConsoleInput()
      Attaches this script monkey to the shared console.
      java.lang.Object call​(java.lang.String method, java.lang.Object... args)
      Call a script function.
      java.lang.Object eval​(java.io.Reader r)
      Evaluates a script from a reader.
      java.lang.Object eval​(java.lang.String s)
      Evaluates a script stored in a string.
      java.lang.Object eval​(java.net.URL url)
      Evaluates a script from a URL.
      static java.lang.String getCurrentScriptLocation()
      Returns a string describing the current file and line of the script running on the current thread.
      Language getGameLangProvider()
      Returns the Language object that is used to look up game strings with #string_key syntax.
      static java.lang.String getLibrary​(java.lang.String name)
      Returns a library as a string.
      Settings getSettingProvider()
      Returns the Settings object that is used to look up settings with $setting_name syntax.
      static ScriptConsole getSharedConsole()
      Returns the shared script console.
      Language getUiLangProvider()
      Returns the Language object that is used to look up interface strings with @string_key syntax.
      <T> T implement​(java.lang.Class<T> klass)
      Returns an object that implements a Java interface by calling script functions.
      static void includeLibrary​(javax.script.ScriptEngine engine, java.lang.String name)
      Evaluate a library file within the current script context.
      static boolean isLibraryNameAURL​(java.lang.String s)
      Returns true if a library identifier is actually a URL.
      static java.lang.Object runResourceCreationScript​(java.lang.String resource)
      Runs a resource creation script stored in a resource file.
      static boolean runResourceScript​(java.lang.String resource, boolean debug)
      Runs a script file stored in a resource file.
      static void scriptError​(java.lang.Throwable se)
      Handles an error as if it was an uncaught exception thrown from a script.
      void setBreakpoint​(boolean breakpoint)
      If the debugger is enabled, sets whether a breakpoint should be set at the start of the next script evaluation.
      void setGameLangProvider​(Language language)
      Sets the Language object that is used to look up game strings with #string_key syntax.
      void setInternalFileName​(java.lang.String name)
      The script engine tracks two identifiers for the source of the script.
      void setSettingProvider​(Settings settings)
      Sets the Settings object that is used to look up settings with $setting_name syntax.
      void setUiLangProvider​(Language language)
      Sets the Language object that is used to look up interface strings with @string_key syntax.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • ON_INSTALL_EVENT_KEY

        public static final java.lang.String ON_INSTALL_EVENT_KEY
        If a component's private settings set this key, then the script it contains will be executed when the component is installed in an editor.
        See Also:
        Constant Field Values

      • ON_PAINT_EVENT_KEY

        public static final java.lang.String ON_PAINT_EVENT_KEY
        If a component's private settings set this key, then Sheets evaluate the script it contains and call the function onPaint( Graphics2D, GameComponent, Sheet ).
        See Also:
        Constant Field Values

      • CLEAR_CONSOLE_ON_RUN_KEY

        public static final java.lang.String CLEAR_CONSOLE_ON_RUN_KEY
        A boolean setting key that stores whether the script output console should be cleared before running a script. This applies to user-initiated actions, like right-clicking on a script editor and choosing Run. It has no effect in other circumstances, such as when plug-ins are being loaded.
        See Also:
        Constant Field Values

      • VAR_CONTEXT

        public static final java.lang.String VAR_CONTEXT
        The reserved variable name for the script's PluginContext (PluginContext).
        See Also:
        Constant Field Values

      • VAR_COMPONENT

        public static final java.lang.String VAR_COMPONENT
        The reserved variable name for the active (edited) game component (Component).
        See Also:
        Constant Field Values

      • VAR_EDITOR

        public static final java.lang.String VAR_EDITOR
        The reserved variable name for the active (selected) editor (Editor).
        See Also:
        Constant Field Values

      • VAR_FILE

        public static final java.lang.String VAR_FILE
        The reserved variable name for the source file name (sourcefile).
        See Also:
        Constant Field Values

      • SCRIPT_FILE_ENCODING

        public static final java.nio.charset.Charset SCRIPT_FILE_ENCODING
        The standard encoding for script code stored in a file (UTF-8).

    • Constructor Detail

      • ScriptMonkey

        public ScriptMonkey​(java.lang.String scriptFileName)
        Creates a new ScriptMonkey that can be used to execute script code.
        Parameters:
        scriptFileName - the identifier to associate with the code that will be executed; this will be reported as the script's file name in error messages
        See Also:
        setInternalFileName(java.lang.String)

    • Method Detail

      • setInternalFileName

        public void setInternalFileName​(java.lang.String name)
        The script engine tracks two identifiers for the source of the script. One is the "sourcefile" variable available to the script. When a plug-in is running, this will normally be the same name as the other, true, identifier. But when running a script "on demand", as from the project Run command or the Quickscript window, then the ScriptMonkey will typically be constructed using the file name "Quickscript", because many scripts check for this and change their behaviour accordingly. (For example, the source code for a plug-in might run a test of the plug-in functionality.) However, in this case the script will also report the identifier "Quickscript" in error messages, which may not be ideal. This method can be used to set the internal name to a different value than the one available to the script, so that error messages display a more appropriate name.
        Parameters:
        name - the internal identifier to use when the script is evaluated

      • getSharedConsole

        public static ScriptConsole getSharedConsole()
        Returns the shared script console.
        Returns:
        the script output window

      • bindToConsoleInput

        public void bindToConsoleInput()
        Attaches this script monkey to the shared console. Input from the console will be executed in the context of this monkey until the binding is changed.

      • implement

        public <T> T implement​(java.lang.Class<T> klass)
        Returns an object that implements a Java interface by calling script functions. Functions that are not defined in the evaluated script code will do nothing. If such missing functions return a value in the specified interface, they will return zero if the return type is a primitive numeric type, or null otherwise.
        Type Parameters:
        T - the type of the implemented interface
        Parameters:
        klass - the class value of the interface to implement
        Returns:
        an instance of the requested class that is implemented by script code

      • eval

        public java.lang.Object eval​(java.net.URL url)
        Evaluates a script from a URL. Any errors will be displayed on the script console.
        Parameters:
        url - the URL that contains script code to execute
        Returns:
        the return value of the script code, if any

      • eval

        public java.lang.Object eval​(java.io.Reader r)
        Evaluates a script from a reader. Any errors will be displayed on the script console.
        Parameters:
        r - the reader that contains script code to execute
        Returns:
        the return value of the script code, if any

      • eval

        public java.lang.Object eval​(java.lang.String s)
        Evaluates a script stored in a string. Any errors will be displayed on the script console.
        Parameters:
        s - the script code to execute
        Returns:
        the return value of the script code, if any

      • ambivalentCall

        public java.lang.Object ambivalentCall​(java.lang.String method,
                                       java.lang.Object... args)
        Call a script function, returning null without displaying an error if the method does not exist. If a script error occurs, an error message is displayed and null is returned.
        Parameters:
        method - the name of a script function
        args - the arguments to pass to the function
        Returns:
        the return value of the function

      • call

        public java.lang.Object call​(java.lang.String method,
                             java.lang.Object... args)
        Call a script function. If the function does not exist, an error message is displayed and a NoSuchMethodException exception is returned. If a script error occurs, the error is printed on the console and returned. Otherwise, the return value of the function (or null) is returned.
        Parameters:
        method - the name of a script function
        args - the arguments to pass to the function
        Returns:
        the return value of the function

      • bind

        public void bind​(java.lang.String name,
                 java.lang.Object object)
        Bind a value to a variable name in the global scope of the script.
        Parameters:
        name - the variable name to bind
        object - the value to assign to the variable name
        Throws:
        java.lang.NullPointerException - if the variable name is null
        java.lang.IllegalArgumentException - if the variable name starts with a reserved character ($, @, #)

      • scriptError

        public static void scriptError​(java.lang.Throwable se)
        Handles an error as if it was an uncaught exception thrown from a script.
        Parameters:
        se - the script exception (or pseudo-script exception) to handle

      • runResourceScript

        public static boolean runResourceScript​(java.lang.String resource,
                                        boolean debug)
        Runs a script file stored in a resource file. The script is simply evaluated; no specific function is called or result captured. Returns true if the script was loaded and run without error, false otherwise.
        Parameters:
        resource - the resource file containing the script
        Returns:
        true if a breakpoint should be set at the start of the script

      • runResourceCreationScript

        public static java.lang.Object runResourceCreationScript​(java.lang.String resource)
        Runs a resource creation script stored in a resource file. The script is evaluated and then its createResource() method is invoked. The result of that function is then returned. If there is an error loading or running the script, a null value is returned. If the script is missing, an error message is shown. If there is an error in the script, it is displayed in the output console.
        Parameters:
        resource - the resource file containing the script
        Returns:
        the object returned from createResource(), or null

      • setBreakpoint

        public void setBreakpoint​(boolean breakpoint)
        If the debugger is enabled, sets whether a breakpoint should be set at the start of the next script evaluation. This setting reverts to false when the next script is evaluated. If the debugger is not enabled, this method has no effect.
        Parameters:
        breakpoint -

      • setSettingProvider

        public void setSettingProvider​(Settings settings)
        Sets the Settings object that is used to look up settings with $setting_name syntax.
        Parameters:
        settings - the settings that will be visible in the global scope

      • getSettingProvider

        public Settings getSettingProvider()
        Returns the Settings object that is used to look up settings with $setting_name syntax.
        Returns:
        the settings that are visible in the global scope

      • setUiLangProvider

        public void setUiLangProvider​(Language language)
        Sets the Language object that is used to look up interface strings with @string_key syntax. Passing null will reset the language to Language.getInterface().
        Parameters:
        language - the UI language whose strings will be visible in the global scope

      • getUiLangProvider

        public Language getUiLangProvider()
        Returns the Language object that is used to look up interface strings with @string_key syntax.
        Returns:
        the interface language that is visible in the global scope

      • setGameLangProvider

        public void setGameLangProvider​(Language language)
        Sets the Language object that is used to look up game strings with #string_key syntax. Passing null will reset the language to Language.getGame().
        Parameters:
        language - the game language whose strings will be visible in the global scope

      • getGameLangProvider

        public Language getGameLangProvider()
        Returns the Language object that is used to look up game strings with #string_key syntax.
        Returns:
        the game language that is visible in the global scope

      • includeLibrary

        public static void includeLibrary​(javax.script.ScriptEngine engine,
                                  java.lang.String name)
                           throws javax.script.ScriptException,
                                  java.io.IOException,
                                  java.net.MalformedURLException
        Evaluate a library file within the current script context. This method is not intended for external use, although nothing prevents it. It is invoked from within scripts in order to process useLibrary() calls.
        Parameters:
        engine - the engine to add the library to
        name - the library's identifier, or a URL that points to it
        Throws:
        javax.script.ScriptException - if the library evaluation results in an error
        java.io.IOException - if there is an error loading the library
        java.net.MalformedURLException - if the URL is invalid

      • getLibrary

        public static java.lang.String getLibrary​(java.lang.String name)
                                   throws java.io.IOException,
                                          java.net.MalformedURLException
        Returns a library as a string. If the string contains :, it is treated as a URL and the library is fetched from that location. Otherwise, it is assumed to be a standard library that lives in resources/libraries. In this case, the ".js" extension is added automatically.
        Parameters:
        name - the library name (or a URL)
        Returns:
        the requested library
        Throws:
        java.io.IOException
        java.net.MalformedURLException

      • isLibraryNameAURL

        public static boolean isLibraryNameAURL​(java.lang.String s)
        Returns true if a library identifier is actually a URL. For example, it would return false for "imageutils", but true for "res://my/library.js".
        Parameters:
        s - the identifier to check
        Returns:
        true if the identifier is not a simple library name

      • getCurrentScriptLocation

        public static java.lang.String getCurrentScriptLocation()
        Returns a string describing the current file and line of the script running on the current thread.
        Returns:
        the location of the currently running script, or null