Package com.hk.lua

Class LuaInterpreter

java.lang.Object
com.hk.lua.LuaInterpreter
All Implemented Interfaces:
Tokens
public class LuaInterpreter
extends Object
implements Tokens
This utility class encapsulates an entire Lua environment within a single Java class/package. This class is instantiated using the Lua class, which allows you to construct a Lua interpreter using a Reader. The reader is fully read and interpreted as Lua code. Which can then be executed in a myriad of fashions. There can be various types of variables and objects that can be directly tied to Java methods, fields, or code.
Author:
theKayani
See Also:
Lua.interpreter(), Lua.reader(java.io.Reader, java.lang.String), LuaFactory.build(), https://www.lua.org/manual/5.3/

  • Method Details

    • hasExtra

      public boolean hasExtra​(String key)

      Check whether a certain key has a value under it, whether null or not.

      Extra data it data that is tied to this specific interpreter. Completely optional and has no effect on execution of Lua. Just for utility and data consistency sake.

      Parameters:
      key - a String to match to a key
      Returns:
      if this certain key has data under it

    • getExtra

      public Object getExtra​(String key)

      Get the extra data under a certain key.

      Extra data it data that is tied to this specific interpreter. Completely optional and has no effect on execution of Lua. Just for utility and data consistency sake.

      Parameters:
      key - a String to match to a key
      Returns:
      a Object or null if there is no match.

    • getExtra

      public <T> T getExtra​(String key, Class<T> cls)

      Get the extra data under a certain key. The data returned should be able to be cast to the cls specified. If so, it is boxed and returned.

      Extra data it data that is tied to this specific interpreter. Completely optional and has no effect on execution of Lua. Just for utility and data consistency sake.

      Type Parameters:
      T - a T class
      Parameters:
      key - a String to match to a key
      cls - a Class to cast the returned value to
      Returns:
      a T object, or null if none was found.

    • getExtra

      public <T> T getExtra​(String key, Class<T> cls, T def)

      Get the extra data under a certain key, or a default if there data found under the key was null or not found.

      Extra data it data that is tied to this specific interpreter. Completely optional and has no effect on execution of Lua. Just for utility and data consistency sake.

      Type Parameters:
      T - a T class
      Parameters:
      key - a String to match to a key
      cls - a Class to cast the returned value to
      def - a T object or the default if there was one provided
      Returns:
      a T object, or the def value if the data was null or there was no found data.

    • getExtraLua

      public LuaObject getExtraLua​(String key)

      Get the extra data under a certain key, cast as a LuaObject. This is useful because it will not return null, it will instead return Lua.NIL if there was no valid data found.

      Extra data it data that is tied to this specific interpreter. Completely optional and has no effect on execution of Lua. Just for utility and data consistency sake.

      Parameters:
      key - a String to match to a key
      Returns:
      a LuaObject object, or Lua.NIL if there was no valid data found under the specified key.

    • getExtraProp

      public String getExtraProp​(String key)

      Get the extra data under a certain key, cast as a String. This will return null if there was no valid data found.

      Extra data it data that is tied to this specific interpreter. Completely optional and has no effect on execution of Lua. Just for utility and data consistency sake.

      Parameters:
      key - a String to match to a key
      Returns:
      a String object, or null if there was no valid data found under the specified key.

    • setExtra

      public LuaInterpreter setExtra​(String key, Object value)

      Set the data under a certain key. This value can then later be retrieved using the getExtra(java.lang.String) methods. These have various overloaded helper functions to return the value cast as another type.

      Extra data it data that is tied to this specific interpreter. Completely optional and has no effect on execution of Lua. Just for utility and data consistency sake.

      Parameters:
      key - a String to match to a key
      value - a Object object, or null if desired
      Returns:
      this

    • removeExtra

      public LuaInterpreter removeExtra​(String key)

      Remove a certain key from the extra data. This will result in the default value being used (if passed) or a null value when using the getExtra(java.lang.String) methods.

      Extra data it data that is tied to this specific interpreter. Completely optional and has no effect on execution of Lua. Just for utility and data consistency sake.

      Parameters:
      key - a String to match to a key
      Returns:
      this

    • getGlobals

      public Environment getGlobals()

      Get the global Lua environment with global variables and functions. Conventionally, the developer would use this method to set the various global variables for this specific environment before calling the execute(java.lang.Object...) method, or calling a specific method by name.

      Calling this before execute will only contain the library imported methods and data. After calling the execute method, will the environment be populated by the variables from the Lua code interpreted.

      Returns:
      the global Lua Environment

    • require

      public LuaObject require​(CharSequence cs)
      Immediately execute a string of Lua code using this global environment under a new Lua chunk.
      Parameters:
      cs - the Lua code to interpret
      Returns:
      the result from this execution. If this code had a return statement.

    • require

      public LuaObject require​(Reader reader)
      Immediately execute a reader of Lua code using this global environment under a new Lua chunk.
      Parameters:
      reader - a Reader to provide the Lua code to interpret
      Returns:
      the result from this execution. If this code had a return statement.

    • require

      public LuaObject require​(String module, Reader reader)
      Immediately execute a reader of Lua code using this global environment under a new Lua chunk. This function executes the Lua code under a certain module, the result is then stored in the case that this function is called again with the same module. If so, the reader is ignored and the saved value is returned instead.
      Parameters:
      module - a key to match the result object to
      reader - a Reader to provide the Lua code to interpret
      Returns:
      the result from this execution. If this code had a return statement.

    • hasModule

      public boolean hasModule​(String module)

    • importLib

      public <T extends Enum<T> & BiConsumer<Environment,​ LuaObject>> void importLib​(LuaLibrary<T> lib)

      Import the individual elements of a Lua Library directly into the global environment. Whether the elements are placed in the global space, or under a certain table is defined by the constructor when instantiating the library object.

      To use any of the default libraries, you don't need to define any functions yourself. All you need to do is import the various standard libraries under LuaLibrary.

      Type Parameters:
      T - a T class
      Parameters:
      lib - a LuaLibrary object
      See Also:
      LuaLibrary(String, Class)

    • execute

      public Object execute​(Object... args) throws UncheckedIOException

      Execute the interpreter using the previously provided reader. If the compile() was not called first, the code is first interpreted and compiled before executed.

      The args parameter is for providing a variable amount of arguments to the Lua code. According to The Lua 5.3 Manual, the provided arguments are converted into their LuaObject equivalents and stored in the ... varargs variable in the Lua code.

      Parameters:
      args - any vararg parameters to pass to the Lua code.
      Returns:
      a result of the execution.
      Throws:
      LuaException - if any.
      UncheckedIOException - if any.

    • compile

      public void compile() throws UncheckedIOException

      Attempt to fully read the provided Reader and interpret it as Lua code. If there are any Lua syntax errors, this function will throw a LuaException.

      If not, the code is saved to be executed using the execute(java.lang.Object...) command. If this is not called beforehand, it is called by default by the execute function.

      Throws:
      LuaException - if any Lua syntax errors.
      UncheckedIOException - if any.