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/

Field Summary

Fields inherited from interface com.hk.lua.Tokens

F_DO, F_ELSE, F_ELSEIF, F_FOR, F_FUNCTION, F_IF, F_LOOP, F_REPEAT, F_WHILE, T_AND, T_BAND, T_BOOLEAN, T_BOR, T_BREAK, T_BXOR, T_CLSE_BKT, T_CLSE_BRC, T_CLSE_PTS, T_COLON, T_COMMA, T_CONCAT, T_DIVIDE, T_DO, T_DOUBLECOLON, T_EEQUALS, T_ELSE, T_ELSEIF, T_END, T_EQUALS, T_FLR_DIVIDE, T_FOR, T_FUNCTION, T_GENERIC_FOR, T_GOTO, T_GREQ_THAN, T_GRTR_THAN, T_IDENTIFIER, T_IF, T_IN, T_INC_NUMBER, T_INC_STRING, T_LESS_THAN, T_LOCAL, T_LSEQ_THAN, T_MINUS, T_MODULO, T_NEGATE, T_NEQUALS, T_NIL, T_NOT, T_NULL, T_NUMBER, T_NUMERIC_FOR, T_OPEN_BKT, T_OPEN_BRC, T_OPEN_PTS, T_OR, T_PERIOD, T_PLUS, T_POUND, T_POW, T_REPEAT, T_RETURN, T_SEMIC, T_SHL, T_SHR, T_STRING, T_TABLE, T_THEN, T_THREAD, T_TIMES, T_UBNOT, T_UNTIL, T_USERDATA, T_VARARGS, T_WHILE

Method Summary

Modifier and Type	Method	Description
void	compile()	Attempt to fully read the provided Reader and interpret it as Lua code.
@Nullable LuaObject	execute(Object... args)	Execute the interpreter using the previously provided reader.
@Nullable Object	getExtra(@NotNull String key)	Get the extra data under a certain key.
<T> T	getExtra(@NotNull String key, @NotNull Class<T> cls)	Get the extra data under a certain key.
<T> T	getExtra(@NotNull String key, @NotNull 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.
@NotNull LuaObject	getExtraLua(@NotNull String key)	Get the extra data under a certain key, cast as a LuaObject.
@Nullable String	getExtraProp(@NotNull String key)	Get the extra data under a certain key, cast as a String.
@NotNull Environment	getGlobals()	Get the global Lua environment with global variables and functions.
boolean	hasExtra(@NotNull String key)	Check whether a certain key has a value under it, whether null or not.
boolean	hasModule(@NotNull String module)
<T extends Enum<T> & BiConsumer<Environment,LuaObject>> void	importLib(@NotNull LuaLibrary<T> lib)	Import the individual elements of a Lua Library directly into the global environment.
@NotNull LuaInterpreter	removeExtra(@NotNull String key)	Remove a certain key from the extra data.
@NotNull LuaObject	require(@NotNull Reader reader)	Immediately execute a reader of Lua code using this global environment under a new Lua chunk.
@NotNull LuaObject	require(@NotNull CharSequence cs)	Immediately execute a string of Lua code using this global environment under a new Lua chunk.
@NotNull LuaObject	require(@Nullable String module, @NotNull Reader reader)	Immediately execute a reader of Lua code using this global environment under a new Lua chunk.
@NotNull LuaInterpreter	setExtra(@NotNull String key, @Nullable Object value)	Set the data under a certain key.

Methods inherited from class java.lang.Object

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

Method Detail

hasExtra

public boolean hasExtra(@NotNull
                        @NotNull 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

@Nullable
public @Nullable Object getExtra(@NotNull
                                 @NotNull 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

@Nullable
public <T> T getExtra(@NotNull
                      @NotNull String key,
                      @NotNull
                      @NotNull 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

@Nullable
@Contract("_,_,!null -> !null")
public <T> T getExtra(@NotNull
                      @NotNull String key,
                      @NotNull
                      @NotNull Class<T> cls,
                      @Nullable
                      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

@NotNull
public @NotNull LuaObject getExtraLua(@NotNull
                                      @NotNull 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

@Nullable
public @Nullable String getExtraProp(@NotNull
                                     @NotNull 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

@NotNull
public @NotNull LuaInterpreter setExtra(@NotNull
                                        @NotNull String key,
                                        @Nullable
                                        @Nullable 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

@NotNull
public @NotNull LuaInterpreter removeExtra(@NotNull
                                           @NotNull 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

@NotNull
public @NotNull 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

@NotNull
public @NotNull LuaObject require(@NotNull
                                  @NotNull 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

@NotNull
public @NotNull LuaObject require(@NotNull
                                  @NotNull 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

@NotNull
public @NotNull LuaObject require(@Nullable
                                  @Nullable String module,
                                  @NotNull
                                  @NotNull 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(@NotNull
                         @NotNull String module)

importLib

public <T extends Enum<T> & BiConsumer<Environment,LuaObject>> void importLib(@NotNull
                                                                                    @NotNull 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

@Nullable
public @Nullable LuaObject 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.