Interface ScriptEngine


public interface ScriptEngine
Interface for managing script engine variables, statements, and script execution.

The ScriptEngine interface provides methods for interacting with a script engine, such as executing scripts and statements, managing variables, and serializing/deserializing objects. It serves as a bridge between JLine and various scripting languages like JavaScript, Groovy, etc.

The ScriptEngine is responsible for:

  • Executing scripts and statements in the underlying script engine
  • Managing variables in the script engine's context
  • Converting objects between Java and the script engine's native format
  • Serializing and deserializing objects to/from various formats
  • Providing completers for script-specific syntax
  • Method Details

    • getEngineName

      String getEngineName()
      Returns the name of the underlying script engine.

      This method retrieves the name of the script engine implementation being used, such as "JavaScript", "Groovy", etc.

      Returns:
      the name of the script engine
    • getExtensions

      Collection<String> getExtensions()
      Returns the file name extensions associated with this script engine.

      This method retrieves the file extensions that are recognized by this script engine, such as ".js" for JavaScript, ".groovy" for Groovy, etc.

      Returns:
      a collection of file name extensions associated with this script engine
    • getScriptCompleter

      Completer getScriptCompleter()
      Returns a completer for script-specific syntax.

      This method retrieves a completer that can provide completion for script-specific syntax, such as keywords, built-in functions, etc. The completer can be used for tab completion in the console.

      Returns:
      a completer for script-specific syntax
    • hasVariable

      boolean hasVariable(String name)
      Tests if a variable exists in the script engine's context.

      This method determines whether a variable with the specified name exists in the script engine's context.

      Parameters:
      name - the name of the variable to check
      Returns:
      true if a variable with the specified name exists, false otherwise
    • put

      void put(String name, Object value)
      Creates or updates a variable in the script engine's context.

      This method creates a new variable with the specified name and value in the script engine's context, or updates an existing variable if one with the specified name already exists.

      Parameters:
      name - the name of the variable to create or update
      value - the value to assign to the variable
    • get

      Object get(String name)
      Gets the value of a variable from the script engine's context.

      This method retrieves the value of the variable with the specified name from the script engine's context.

      Parameters:
      name - the name of the variable to get
      Returns:
      the value of the variable, or null if no variable with the specified name exists
    • find

      default Map<String,Object> find()
      Gets all variables with their values from the script engine's context.

      This method retrieves all variables and their values from the script engine's context. This is a convenience method that calls find(String) with a null pattern.

      Returns:
      a map of variable names to their values
    • find

      Map<String,Object> find(String name)
      Gets all variables that match the specified pattern.

      This method retrieves all variables whose names match the specified pattern from the script engine's context. The pattern can contain wildcard characters (*) to match multiple variable names.

      Parameters:
      name - the pattern to match variable names against, or null to match all variables
      Returns:
      a map of matching variable names to their values
    • del

      void del(String... vars)
      Deletes variables from the script engine's context.

      This method removes variables from the script engine's context. The variable names can contain wildcard characters (*) to match multiple variables.

      Parameters:
      vars - the names of the variables to delete, which can contain wildcard characters
    • toJson

      String toJson(Object object)
      Serializes an object to a JSON string.

      This method converts the specified object to a formatted JSON string representation. The exact format of the JSON string depends on the script engine implementation.

      Parameters:
      object - the object to serialize to JSON
      Returns:
      a formatted JSON string representation of the object
    • toString

      String toString(Object object)
      Converts an object to its string representation.

      This method converts the specified object to a string representation. The exact format of the string depends on the script engine implementation.

      Parameters:
      object - the object to convert to a string
      Returns:
      a string representation of the object
    • toMap

      Map<String,Object> toMap(Object object)
      Converts an object's fields to a map.

      This method extracts the fields of the specified object and returns them as a map of field names to field values. The exact set of fields included in the map depends on the script engine implementation.

      Parameters:
      object - the object whose fields to extract
      Returns:
      a map of field names to field values
    • deserialize

      default Object deserialize(String value)
      Deserializes a value from its string representation.

      This method converts the specified string representation back to an object. This is a convenience method that calls deserialize(String, String) with a null format.

      Parameters:
      value - the string representation to deserialize
      Returns:
      the deserialized object
    • deserialize

      Object deserialize(String value, String format)
      Deserializes a value from its string representation using the specified format.

      This method converts the specified string representation back to an object using the specified serialization format.

      Parameters:
      value - the string representation to deserialize
      format - the serialization format to use, or null to use the default format
      Returns:
      the deserialized object
    • getSerializationFormats

      List<String> getSerializationFormats()
      Returns the serialization formats supported by this script engine.

      This method retrieves the names of the serialization formats that can be used with the persist(Path, Object, String) method.

      Returns:
      a list of supported serialization format names
    • getDeserializationFormats

      List<String> getDeserializationFormats()
      Returns the deserialization formats supported by this script engine.

      This method retrieves the names of the deserialization formats that can be used with the deserialize(String, String) method.

      Returns:
      a list of supported deserialization format names
    • persist

      void persist(Path file, Object object)
      Persists an object to a file.

      This method serializes the specified object and writes it to the specified file. This is a convenience method that calls persist(Path, Object, String) with a null format.

      Parameters:
      file - the file to write the serialized object to
      object - the object to serialize and persist
    • persist

      void persist(Path file, Object object, String format)
      Persists an object to a file using the specified serialization format.

      This method serializes the specified object using the specified format and writes it to the specified file.

      Parameters:
      file - the file to write the serialized object to
      object - the object to serialize and persist
      format - the serialization format to use, or null to use the default format
    • execute

      Object execute(String statement) throws Exception
      Executes a script engine statement.

      This method evaluates the specified statement in the script engine and returns the result of the evaluation.

      Parameters:
      statement - the statement to execute
      Returns:
      the result of executing the statement
      Throws:
      Exception - if an error occurs during execution
    • execute

      default Object execute(Path script) throws Exception
      Executes a script from a file.

      This method executes the script contained in the specified file and returns the result of the execution. This is a convenience method that calls execute(File, Object[]) with null arguments.

      Parameters:
      script - the file containing the script to execute
      Returns:
      the result of executing the script
      Throws:
      Exception - if an error occurs during execution
    • execute

      default Object execute(File script) throws Exception
      Executes a script from a file.

      This method executes the script contained in the specified file and returns the result of the execution. This is a convenience method that calls execute(File, Object[]) with null arguments.

      Parameters:
      script - the file containing the script to execute
      Returns:
      the result of executing the script
      Throws:
      Exception - if an error occurs during execution
    • execute

      default Object execute(Path script, Object[] args) throws Exception
      Executes a script from a file with the specified arguments.

      This method executes the script contained in the specified file with the specified arguments and returns the result of the execution. This is a convenience method that calls execute(File, Object[]) with the file converted to a File object.

      Parameters:
      script - the file containing the script to execute
      args - the arguments to pass to the script, or null if no arguments
      Returns:
      the result of executing the script
      Throws:
      Exception - if an error occurs during execution
    • execute

      Object execute(File script, Object[] args) throws Exception
      Executes a script from a file with the specified arguments.

      This method executes the script contained in the specified file with the specified arguments and returns the result of the execution.

      Parameters:
      script - the file containing the script to execute
      args - the arguments to pass to the script, or null if no arguments
      Returns:
      the result of executing the script
      Throws:
      Exception - if an error occurs during execution
    • execute

      Object execute(Object closure, Object... args)
      Executes a script engine closure with the specified arguments.

      This method executes the specified closure (a callable object) with the specified arguments and returns the result of the execution.

      Parameters:
      closure - the closure to execute
      args - the arguments to pass to the closure
      Returns:
      the result of executing the closure