Package party.iroiro.luajava

Interface Lua

All Superinterfaces:
AutoCloseable, LuaThread
All Known Implementing Classes:
AbstractLua, Lua51, Lua52, Lua53, Lua54, Lua55, LuaJ, LuaJit
public interface Lua extends AutoCloseable, LuaThread
A lua_State * wrapper, representing a Lua thread

Most methods in this interface are wrappers around the corresponding Lua C API functions, and requires a certain degree of familiarity with the Lua C API. If you are not that familiar with the Lua C API, you may want to read the Lua manual first or try out LuaValue-related API at the LuaThread interface.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    Lua.Conversion
    Controls the degree of conversion from Java to Lua
    static enum 
    Lua.LuaType
    Lua data types

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    GLOBAL_THROWABLE
    The global key used to store Java exceptions in Lua.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    checkStack(int extra)
    Ensures that there are at least extra free stack slots in the Lua stack
    void
    close()
    Closes the thread
    void
    concat(int n)
    Concatenates the n values at the top of the stack, pops them, and leaves the result at the top
    Object
    createProxy(Class<?>[] interfaces, Lua.Conversion degree)
    Creates a proxy object, implementing all the specified interfaces, with a Lua table / function on top of the stack
    void
    createTable(int nArr, int nRec)
    Creates a new empty table and pushes it onto the stack
    @Nullable ByteBuffer
    dump()
    Dumps a function as a binary chunk
    boolean
    equal(int i1, int i2)
    Returns true if the two values in acceptable indices i1 and i2 are equal
    int
    error(@Nullable Throwable e)
    Sets the Lua global GLOBAL_THROWABLE to the throwable
    void
    error(String message)
    Throws an error inside a Lua environment
    void
    gc()
    Performs a full garbage-collection cycle
    LuaValue
    get()
    Pops the value on top of the stack and return a LuaValue referring to it
    void
    getField(int index, String key)
    Pushes onto the stack the value t[key]
    void
    getGlobal(String name)
    Pushes onto the stack the value of the global name
    int
    getId()
    Returns the unique identifier of this Lua thread.
    @Nullable Throwable
    getJavaError()
    Fetches the most recent Java Throwable passed to Lua
    LuaNatives
    getLuaNatives()
    Returns the underlying native Lua interface.
    Lua
    getMainState()
    Returns the main Lua state.
    int
    getMetaField(int index, String field)
    Pushes onto the stack the field field from the metatable of the object at index index
    int
    getMetatable(int index)
    Pushes onto the stack the metatable of the value at the given acceptable index
    long
    getPointer()
    Returns the pointer to the internal Lua state.
    void
    getRegisteredMetatable(String typeName)
    Pushes onto the stack the metatable associated with name tname in the registry
    void
    getTable(int index)
    Pushes onto the stack the value t[k]
    int
    getTop()
    Returns the index of the top element in the stack
    void
    insert(int index)
    Moves the top element into the given valid index, shifting up the elements above this index
    boolean
    isBoolean(int index)
    Returns true if the value at the given index is a boolean, and false otherwise
    boolean
    isFunction(int index)
    Returns true if the value at the given index is a function (either C or Lua), and false otherwise
    boolean
    isInteger(int index)
    Returns true if the value at the given index is an integer, and false otherwise
    boolean
    isJavaObject(int index)
    Checks if the element is a Java object
    boolean
    isNil(int index)
    Returns true if the value at the given index is nil, and false otherwise
    boolean
    isNone(int index)
    Returns true if the given index is not valid, and false otherwise
    boolean
    isNoneOrNil(int index)
    Returns true if the given index is not valid or if the value at this index is nil, and false otherwise
    boolean
    isNumber(int index)
    Returns true if the value is a number or a string convertible to a number, and false otherwise
    boolean
    isString(int index)
    Returns true if the value at the given index is a string or a number
    boolean
    isTable(int index)
    Returns true if the value at the given index is a table, and false otherwise.
    boolean
    isThread(int index)
    Returns true if the value at the given index is a thread, and false otherwise.
    boolean
    isUserdata(int index)
    Returns true if the value at the given index is userdata (either full or light), and false otherwise.
    boolean
    lessThan(int i1, int i2)
    Returns true if the value at acceptable index i1 is smaller than the value at i2
    void
    load(String script)
    Loads a string as a Lua chunk
    void
    load(Buffer buffer, String name)
    Loads a buffer as a Lua chunk
    void
    loadExternal(String module)
    Loads a chunk from a ExternalLoader set by setExternalLoader(ExternalLoader)
    int
    newRegisteredMetatable(String typeName)
    Creates a new table to be used as a metatable for userdata, adds it to the registry
    void
    newTable()
    Creates a new empty table and pushes it onto the stack
    Lua
    newThread()
    Creates a new thread, pushes it on the stack
    int
    next(int n)
    Pops a key from the stack, and pushes a key-value pair from the table at the given index
    void
    openLibraries()
    Opens all standard Lua libraries into the given state
    void
    openLibrary(String name)
    Opens a specific library into the given state
    void
    pCall(int nArgs, int nResults)
    Calls a function in protected mode
    void
    pop(int n)
    Pops n elements from the stack
    void
    push(boolean bool)
    Pushes a boolean value onto the stack
    void
    push(long integer)
    Pushes an integer onto the stack
    void
    push(@Nullable Object object, Lua.Conversion degree)
    Push an object onto the stack, converting according to Lua.Conversion.
    void
    push(Number number)
    Pushes a floating-point number onto the stack
    void
    push(String string)
    Pushes a string onto the stack.
    void
    push(ByteBuffer buffer)
    Pushes a buffer as a raw string onto the stack
    void
    push(Collection<?> collection)
    Push the element onto the stack, converted to lua tables (index starting from 1)
    void
    push(Map<?,?> map)
    Push the element onto the stack, converted to lua tables
    void
    push(JFunction function)
    Push the function onto the stack, converted to a callable element
    void
    push(LuaFunction value)
    Push the function onto the stack, converted to a callable element
    void
    push(LuaValue value)
    Push a LuaValue onto the stack, equivalent to LuaValue.push(Lua)
    void
    pushArray(Object array)
    Push an array onto the stack, converted to luatable
    void
    pushJavaArray(Object array)
    Push the element onto the stack, converted as is to Java arrays
    void
    pushJavaClass(Class<?> clazz)
    Push a class onto the stack, which may be used with `java.new` on the lua side
    void
    pushJavaObject(Object object)
    Push the element onto the stack, converted as is to Java objects
    void
    pushNil()
    Pushes a nil value onto the stack
    void
    pushThread()
    Pushes the current thread onto the stack
    void
    pushValue(int index)
    Pushes a copy of the element at the given valid index onto the stack
    boolean
    rawEqual(int i1, int i2)
    Returns true if the two values in acceptable indices i1 and i2 are primitively equal
    void
    rawGet(int index)
    Similar to getTable(int), but does a raw access (i.e., without metamethods)
    void
    rawGetI(int index, int n)
    Pushes onto the stack the value t[n], where t is the value at the given valid index
    int
    rawLength(int index)
    Returns the raw "length" of the value at the given index
    void
    rawSet(int index)
    Similar to setTable(int), but does a raw assignment (i.e., without metamethods)
    void
    rawSetI(int index, int n)
    Does the equivalent of t[n] = v
    int
    ref()
    Calls ref(int) with the pseudo-index LUA_REGISTRYINDEX
    int
    ref(int index)
    Creates and returns a reference, in the table at index index
    void
    refGet(int ref)
    Calls rawGetI(int, int) with the pseudo-index LUA_REGISTRYINDEX and the given ref
    void
    remove(int index)
    Removes the element at the given valid index
    void
    replace(int index)
    Moves the top element into the given position (and pops it)
    boolean
    resume(int nArgs)
    Starts and resumes a coroutine in a given thread
    void
    run(String script)
    Loads and runs the given string
    void
    run(Buffer buffer, String name)
    Loads and runs a buffer
    void
    setExternalLoader(ExternalLoader loader)
    Sets a ExternalLoader for the main state
    void
    setField(int index, String key)
    Does the equivalent to t[key] = v
    void
    setGlobal(String name)
    Pops a value from the stack and sets it as the new value of global name
    void
    setMetatable(int index)
    Pops a table from the stack and sets it as the new metatable for the value at the given acceptable index
    void
    setTable(int index)
    Does the equivalent to t[k] = v
    void
    setTop(int index)
    Accepts any index, or 0, and sets the stack top to this index
    LuaException.LuaError
    status()
    Returns the status of the thread
    boolean
    toBoolean(int index)
    Converts the Lua value at the given acceptable index to a boolean value
    @Nullable ByteBuffer
    toBuffer(int index)
    Creates a ByteBuffer from the string at the specific index
    @Nullable ByteBuffer
    toDirectBuffer(int index)
    Creates a read-only direct ByteBuffer from the string at the specific index
    long
    toInteger(int index)
    Converts the Lua value at the given acceptable index to the signed integral type lua_Integer
    @Nullable Object
    toJavaObject(int index)
    Get the element at the specified stack position, if the element is a Java object / array / class
    @Nullable List<?>
    toList(int index)
    Get the element at the specified stack position, converted to List
    @Nullable Map<?,?>
    toMap(int index)
    Get the element at the specified stack position, converted to a Map
    double
    toNumber(int index)
    Converts the Lua value at the given acceptable index to a number
    @Nullable Object
    toObject(int index)
    Automatically converts a value into a Java object nil is converted to null. boolean converted to boolean or the boxed Boolean. integer / number to any of char byte short int long float double or their boxed alternative. string to String. table to Map<Object, Object>, converted recursively. jclass to Class<?>. jobject to the underlying Java object. Other types are not converted and are null on the Java side.
    @Nullable Object
    toObject(int index, Class<?> type)
    Converts a value at the stack index
    @Nullable String
    toString(int index)
    Converts the Lua value at the given acceptable index to a string
    @Nullable Lua.LuaType
    type(int index)
    Returns the Lua type of the element at the given index.
    void
    unref(int ref)
    Calls unRef(int, int) with the pseudo-index LUA_REGISTRYINDEX and the given ref
    void
    unRef(int index, int ref)
    Releases reference ref from the table at index index
    void
    xMove(Lua other, int n)
    Exchange values between different threads of the same global state
    void
    yield(int n)
    Yields a coroutine

    Methods inherited from interface party.iroiro.luajava.value.LuaThread

    eval, from, from, from, from, from, fromNull, get, register, require, set

  • Field Details

    • GLOBAL_THROWABLE

      static final String GLOBAL_THROWABLE
      The global key used to store Java exceptions in Lua.
      See Also:

  • Method Details

    • checkStack

      void checkStack(int extra) throws RuntimeException
      Ensures that there are at least extra free stack slots in the Lua stack

      It wraps lua_checkstack.

      Parameters:
      extra - the extra slots to ensure
      Throws:
      RuntimeException - when unable to grow the stack

    • push

      void push(@Nullable Object object, Lua.Conversion degree)
      Push an object onto the stack, converting according to Lua.Conversion.
      Parameters:
      object - the object to be pushed onto the stack
      degree - how the object is converted into lua values
      See Also:

    • pushNil

      void pushNil()
      Pushes a nil value onto the stack

    • push

      void push(boolean bool)
      Pushes a boolean value onto the stack
      Parameters:
      bool - the boolean value

    • push

      void push(Number number)
      Pushes a floating-point number onto the stack
      Parameters:
      number - the number, whose Number.doubleValue() will be pushed

    • push

      void push(long integer)
      Pushes an integer onto the stack

      Please note that on some 32-bit platforms, 64-bit integers are likely to get truncated instead of getting approximated into a floating-point number. If you want to approximate an integer, cast it to double and use push(Number).

      Parameters:
      integer - the number

    • push

      void push(String string)
      Pushes a string onto the stack.
      Parameters:
      string - the string

    • push

      void push(ByteBuffer buffer)
      Pushes a buffer as a raw string onto the stack

      The pushed bytes are from buffer[buffer.position()] to buffer[buffer.limit() - 1]. So remember to call ByteBuffer.flip() or set the position and limit before pushing.

      Parameters:
      buffer - the buffer, which might contain invalid UTF-8 characters and zeros

    • push

      void push(Map<?,?> map)
      Push the element onto the stack, converted to lua tables

      Inner elements are converted with Lua.Conversion.FULL.

      Parameters:
      map - the element to be pushed onto the stack

    • push

      void push(Collection<?> collection)
      Push the element onto the stack, converted to lua tables (index starting from 1)

      Inner elements are converted with Lua.Conversion.FULL.

      Parameters:
      collection - the element to be pushed onto the stack

    • pushArray

      void pushArray(Object array) throws IllegalArgumentException
      Push an array onto the stack, converted to luatable
      Parameters:
      array - a array
      Throws:
      IllegalArgumentException - when the object is not array

    • push

      void push(JFunction function)
      Push the function onto the stack, converted to a callable element

      The function is wrapped into a C closure, which means Lua will treat the function as a C function. Checking isFunction(int) on the pushed element will return true.

      Parameters:
      function - the function to be pushed onto the stack

    • pushJavaClass

      void pushJavaClass(Class<?> clazz)
      Push a class onto the stack, which may be used with `java.new` on the lua side
      Parameters:
      clazz - the class

    • push

      void push(LuaValue value)
      Push a LuaValue onto the stack, equivalent to LuaValue.push(Lua)
      Parameters:
      value - the value

    • push

      void push(LuaFunction value)
      Push the function onto the stack, converted to a callable element
      Parameters:
      value - the function
      See Also:

    • pushJavaObject

      void pushJavaObject(Object object)
      Push the element onto the stack, converted as is to Java objects
      Parameters:
      object - the element to be pushed onto the stack
      Throws:
      IllegalArgumentException - when argument is null or an array

    • pushJavaArray

      void pushJavaArray(Object array)
      Push the element onto the stack, converted as is to Java arrays
      Parameters:
      array - the element to be pushed onto the stack
      Throws:
      IllegalArgumentException - when argument is null or a non-array object

    • toNumber

      double toNumber(int index)
      Converts the Lua value at the given acceptable index to a number

      The Lua value must be a number or a string convertible to a number; otherwise, lua_tonumber returns 0.

      Parameters:
      index - the stack index
      Returns:
      the converted value, zero if not convertible

    • toInteger

      long toInteger(int index)
      Converts the Lua value at the given acceptable index to the signed integral type lua_Integer

      The Lua value must be a number or a string convertible to a number; otherwise, lua_tointeger returns 0. If the number is not an integer, it is truncated in some non-specified way.

      Parameters:
      index - the stack index
      Returns:
      the converted value, zero if not convertible

    • toBoolean

      boolean toBoolean(int index)
      Converts the Lua value at the given acceptable index to a boolean value

      Like all tests in Lua, lua_toboolean returns 1 for any Lua value different from false and nil; otherwise it returns 0. It also returns 0 when called with a non-valid index.

      Parameters:
      index - the stack index
      Returns:
      the converted value, false with and only with false, nil or TNONE

    • toObject

      @Nullable Object toObject(int index)
      Automatically converts a value into a Java object
      1. nil is converted to null.
      2. boolean converted to boolean or the boxed Boolean.
      3. integer / number to any of char byte short int long float double or their boxed alternative.
      4. string to String.
      5. table to Map<Object, Object>, converted recursively.
      6. jclass to Class<?>.
      7. jobject to the underlying Java object.
      8. Other types are not converted and are null on the Java side.
      Parameters:
      index - the stack index
      Returns:
      the converted object, null if unable to converted

    • toObject

      @Nullable Object toObject(int index, Class<?> type)
      Converts a value at the stack index
      Parameters:
      index - the stack index
      type - the target type
      Returns:
      the converted value, null if unable to converted
      See Also:

    • toString

      @Nullable String toString(int index)
      Converts the Lua value at the given acceptable index to a string

      The Lua value must be a string or a number; otherwise, the function returns NULL. If the value is a number, then lua_tolstring also changes the actual value in the stack to a string.

      Parameters:
      index - the stack index
      Returns:
      the converted string

    • toBuffer

      @Nullable ByteBuffer toBuffer(int index)
      Creates a ByteBuffer from the string at the specific index

      You may want to use this instead of toString(int) when the string is binary (e.g., those returned by string.dump and contains null characters).

      Parameters:
      index - the stack index
      Returns:
      the created buffer

    • toDirectBuffer

      @Nullable ByteBuffer toDirectBuffer(int index)
      Creates a read-only direct ByteBuffer from the string at the specific index

      The memory of this buffer is managed by Lua. So you should never use the buffer after popping the corresponding value from the Lua stack.

      Parameters:
      index - the stack index
      Returns:
      the created read-only buffer

    • toJavaObject

      @Nullable Object toJavaObject(int index)
      Get the element at the specified stack position, if the element is a Java object / array / class
      Parameters:
      index - the stack position of the element
      Returns:
      the Java object or null

    • toMap

      @Nullable Map<?,?> toMap(int index)
      Get the element at the specified stack position, converted to a Map

      The element may be a Lua table or a Java Map, or else, it returns null.

      Parameters:
      index - the stack position of the element
      Returns:
      the map or null

    • toList

      @Nullable List<?> toList(int index)
      Get the element at the specified stack position, converted to List

      The element may be a Lua table or a Java List, or else, it returns null.

      Parameters:
      index - the stack position of the element
      Returns:
      the list or null

    • isBoolean

      boolean isBoolean(int index)
      Returns true if the value at the given index is a boolean, and false otherwise
      Parameters:
      index - the stack index
      Returns:
      true if the value at the given index is a boolean, and false otherwise

    • isFunction

      boolean isFunction(int index)
      Returns true if the value at the given index is a function (either C or Lua), and false otherwise

      When one pushes a JFunction onto the stack using push(JFunction), the JFunction is wrapped into a C closure, so that it is treated as a C function in Lua.

      Parameters:
      index - the stack index
      Returns:
      true if the value at the given index is a function (either C or Lua), and false otherwise

    • isJavaObject

      boolean isJavaObject(int index)
      Checks if the element is a Java object

      Note that a JFunction pushed with push(JFunction) is not a Java object any more, but a C function.

      Parameters:
      index - the element to check type for
      Returns:
      true if the element is a Java object, a Java class, or a Java array

    • isNil

      boolean isNil(int index)
      Returns true if the value at the given index is nil, and false otherwise
      Parameters:
      index - the stack index
      Returns:
      true if the value at the given index is nil, and false otherwise

    • isNone

      boolean isNone(int index)
      Returns true if the given index is not valid, and false otherwise
      Parameters:
      index - the stack index
      Returns:
      true if the given index is not valid, and false otherwise

    • isNoneOrNil

      boolean isNoneOrNil(int index)
      Returns true if the given index is not valid or if the value at this index is nil, and false otherwise
      Parameters:
      index - the stack index
      Returns:
      true if the given index is not valid or if the value at this index is nil, and false otherwise

    • isNumber

      boolean isNumber(int index)
      Returns true if the value is a number or a string convertible to a number, and false otherwise
      Parameters:
      index - the stack index
      Returns:
      true if the value is a number or a string convertible to a number, and false otherwise

    • isInteger

      boolean isInteger(int index)
      Returns true if the value at the given index is an integer, and false otherwise

      (that is, the value is a number and is represented as an integer)

      Parameters:
      index - the stack index
      Returns:
      true if the value is an integer, and false otherwise

    • isString

      boolean isString(int index)
      Returns true if the value at the given index is a string or a number
      Parameters:
      index - the stack index
      Returns:
      true if the value at the given index is a string or a number, and false otherwise.

    • isTable

      boolean isTable(int index)
      Returns true if the value at the given index is a table, and false otherwise.
      Parameters:
      index - the stack index
      Returns:
      Returns true if the value at the given index is a table, and false otherwise.

    • isThread

      boolean isThread(int index)
      Returns true if the value at the given index is a thread, and false otherwise.
      Parameters:
      index - the stack index
      Returns:
      true if the value at the given index is a thread, and 0 otherwise.

    • isUserdata

      boolean isUserdata(int index)
      Returns true if the value at the given index is userdata (either full or light), and false otherwise.
      Parameters:
      index - the stack index
      Returns:
      true if the value at the given index is userdata (either full or light), and false otherwise.

    • type

      @Nullable Lua.LuaType type(int index)
      Returns the Lua type of the element at the given index.
      Parameters:
      index - the element to inspect
      Returns:
      the lua type of the element, null if unrecognized (in, for example, incompatible lua versions)

    • equal

      boolean equal(int i1, int i2)
      Returns true if the two values in acceptable indices i1 and i2 are equal

      Returns true if the two values in acceptable indices index1 and index2 are equal, following the semantics of the Lua == operator (that is, may call metamethods). Otherwise returns false. Also returns false if any of the indices is non valid.

      Parameters:
      i1 - the index of the first element
      i2 - the index of the second element
      Returns:
      true if the two values in acceptable indices i1 and i2 are equal

    • rawLength

      int rawLength(int index)
      Returns the raw "length" of the value at the given index

      For strings, this is the string length; for tables, this is the result of the length operator ('#') with no metamethods; for userdata, this is the size of the block of memory allocated for the userdata. For other values, this call returns 0.

      Parameters:
      index - the stack index
      Returns:
      the raw length of the element

    • lessThan

      boolean lessThan(int i1, int i2)
      Returns true if the value at acceptable index i1 is smaller than the value at i2

      It follows the semantics of the Lua < operator (that is, may call metamethods). Otherwise returns false. Also returns false if any of the indices is non valid.

      Parameters:
      i1 - the index of the first element
      i2 - the index of the second element
      Returns:
      true if the value at acceptable index i1 is smaller than the value at i2

    • rawEqual

      boolean rawEqual(int i1, int i2)
      Returns true if the two values in acceptable indices i1 and i2 are primitively equal

      It does not call metamethods. Otherwise returns false. Also returns false if any of the indices are non valid.

      Parameters:
      i1 - the index of the first element
      i2 - the index of the second element
      Returns:
      true if the two values in acceptable indices i1 and i2 are primitively equal

    • getTop

      int getTop()
      Returns the index of the top element in the stack

      Because indices start at 1, this result is equal to the number of elements in the stack (and so 0 means an empty stack).

      Returns:
      the index of the top element in the stack

    • setTop

      void setTop(int index)
      Accepts any index, or 0, and sets the stack top to this index

      If the new top is greater than the old one, then the new elements are filled with nil. If index is 0, then all stack elements are removed.

      Parameters:
      index - the new top element index

    • insert

      void insert(int index)
      Moves the top element into the given valid index, shifting up the elements above this index

      Moves the top element into the given valid index, shifting up the elements above this index to open space. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.

      Parameters:
      index - the non-pseudo index
      See Also:

    • pop

      void pop(int n)
      Pops n elements from the stack
      Parameters:
      n - the number of elements to pop

    • pushValue

      void pushValue(int index)
      Pushes a copy of the element at the given valid index onto the stack
      Parameters:
      index - the index of the element to be copied
      See Also:

    • pushThread

      void pushThread()
      Pushes the current thread onto the stack

    • remove

      void remove(int index)
      Removes the element at the given valid index

      Removes the element at the given valid index, shifting down the elements above this index to fill the gap. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.

      Parameters:
      index - the index of the element to be removed

    • replace

      void replace(int index)
      Moves the top element into the given position (and pops it)

      Moves the top element into the given position (and pops it), without shifting any element (therefore replacing the value at the given position).

      Parameters:
      index - the index to move to
      See Also:

    • xMove

      void xMove(Lua other, int n) throws IllegalArgumentException
      Exchange values between different threads of the same global state

      This function pops n values from the stack of this thread, and pushes them onto the stack of the other thread

      Parameters:
      other - the thread to move the n values to
      n - the number of elements to move
      Throws:
      IllegalArgumentException - when the two threads do not belong to the same global state

    • load

      void load(String script) throws LuaException
      Loads a string as a Lua chunk

      This function eventually uses lua_load to load the chunk in the string script. Also as lua_load, this function only loads the chunk; it does not run it.

      Parameters:
      script - the Lua chunk
      Throws:
      LuaException
      See Also:

    • load

      void load(Buffer buffer, String name) throws LuaException
      Loads a buffer as a Lua chunk

      This function eventually uses lua_load to load the chunk in the string script. Also as lua_load, this function only loads the chunk; it does not run it.

      The used contents are from buffer[buffer.position()] to buffer[buffer.limit() - 1]. So remember to call ByteBuffer.flip() or set the position and limit before pushing.

      Parameters:
      buffer - the buffer, must be a direct buffer
      name - the chunk name, used for debug information and error messages
      Throws:
      LuaException
      See Also:

    • run

      void run(String script) throws LuaException
      Loads and runs the given string

      It is equivalent to first calling load(String) and then pCall(int, int) the loaded chunk.

      Parameters:
      script - the Lua chunk
      Throws:
      LuaException

    • run

      void run(Buffer buffer, String name) throws LuaException
      Loads and runs a buffer

      It is equivalent to first calling load(Buffer, String) and then pCall(int, int) the loaded chunk.

      The used contents are from buffer[buffer.position()] to buffer[buffer.limit() - 1]. So remember to call ByteBuffer.flip() or set the position and limit before pushing.

      Parameters:
      buffer - the buffer, must be a direct buffer
      name - the chunk name, used for debug information and error messages
      Throws:
      LuaException

    • dump

      @Nullable ByteBuffer dump()
      Dumps a function as a binary chunk

      Receives a Lua function on the top of the stack and produces a binary chunk that, if loaded again, results in a function equivalent to the one dumped.

      Returns:
      the binary chunk, null if an error occurred

    • pCall

      void pCall(int nArgs, int nResults) throws LuaException
      Calls a function in protected mode

      To call a function you must use the following protocol: first, the function to be called is pushed onto the stack; then, the arguments to the function are pushed in direct order; that is, the first argument is pushed first. Finally you call lua_call; nargs is the number of arguments that you pushed onto the stack. All arguments and the function value are popped from the stack when the function is called. The function results are pushed onto the stack when the function returns. The number of results is adjusted to nresults, unless nresults is LUA_MULTRET. In this case, all results from the function are pushed. Lua takes care that the returned values fit into the stack space. The function results are pushed onto the stack in direct order (the first result is pushed first), so that after the call the last result is on the top of the stack.

      Parameters:
      nArgs - the number of arguments that you pushed onto the stack
      nResults - the number of results to adjust to
      Throws:
      LuaException

    • newThread

      Lua newThread()
      Creates a new thread, pushes it on the stack

      The new state returned by this function shares with the original state all global objects (such as tables), but has an independent execution stack.

      Returns:
      a new thread

    • resume

      boolean resume(int nArgs) throws LuaException
      Starts and resumes a coroutine in a given thread

      To start a coroutine, you first create a new thread (see lua_newthread or newThread()); then you push onto its stack the main function plus any arguments; then you call resume, with narg being the number of arguments. This call returns when the coroutine suspends or finishes its execution. When it returns, the stack contains all values passed to lua_yield, or all values returned by the body function. lua_resume returns LUA_YIELD if the coroutine yields, 0 if the coroutine finishes its execution without errors, or an error code in case of errors (see lua_pcall). In case of errors, the stack is not unwound, so you can use the debug API over it. The error message is on the top of the stack. To restart a coroutine, you put on its stack only the values to be passed as results from yield, and then call lua_resume.

      Parameters:
      nArgs - the number of arguments
      Returns:
      true if the thread yielded, or false if it ended execution
      Throws:
      LuaException

    • status

      LuaException.LuaError status()
      Returns the status of the thread
      Returns:
      the status of the thread

    • yield

      void yield(int n)
      Yields a coroutine

      This is not implemented because we have no way to resume execution from a Java stack through a C stack back to a Java stack.

      Parameters:
      n - the number of values from the stack that are passed as results to lua_resume
      Throws:
      UnsupportedOperationException - always

    • createTable

      void createTable(int nArr, int nRec)
      Creates a new empty table and pushes it onto the stack

      The new table has space pre-allocated for narr array elements and nrec non-array elements. This pre-allocation is useful when you know exactly how many elements the table will have.

      Parameters:
      nArr - pre-allocated array elements
      nRec - pre-allocated non-array elements

    • newTable

      void newTable()
      Creates a new empty table and pushes it onto the stack

      It is equivalent to createTable(0, 0).

    • getField

      void getField(int index, String key)
      Pushes onto the stack the value t[key]

      Pushes onto the stack the value t[key], where t is the value at the given valid index. As in Lua, this function may trigger a metamethod for the "index" event.

      Parameters:
      index - the index of the table-like element
      key - the key to look up

    • setField

      void setField(int index, String key)
      Does the equivalent to t[key] = v

      Does the equivalent to t[key] = v, where t is the value at the given valid index and v is the value at the top of the stack. This function pops the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event.

      Parameters:
      index - the index of the table-like element
      key - the key to assign to

    • getTable

      void getTable(int index)
      Pushes onto the stack the value t[k]

      Pushes onto the stack the value t[k], where t is the value at the given valid index and k is the value at the top of the stack. This function pops the key from the stack (putting the resulting value in its place). As in Lua, this function may trigger a metamethod for the "index" event.

      Parameters:
      index - the index of the table-like element

    • setTable

      void setTable(int index)
      Does the equivalent to t[k] = v

      Does the equivalent to t[k] = v, where t is the value at the given valid index, v is the value at the top of the stack, and k is the value just below the top. This function pops both the key and the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event.

      Parameters:
      index - the index of the table-like element

    • next

      int next(int n)
      Pops a key from the stack, and pushes a key-value pair from the table at the given index

      Pops a key from the stack, and pushes a key-value pair from the table at the given index (the "next" pair after the given key). If there are no more elements in the table, then lua_next returns 0 (and pushes nothing).

      A typical traversal looks like this: 

      
      /* table is in the stack at index 't' */
      lua_pushnil(L);  /* first key */
      while (lua_next(L, t) != 0) {
          /* uses 'key' (at index -2) and 'value' (at index -1) */
          printf("%s - %s\n",
          lua_typename(L, lua_type(L, -2)),
          lua_typename(L, lua_type(L, -1)));
          /* removes 'value'; keeps 'key' for next iteration */
          lua_pop(L, 1);
      }

      While traversing a table, do not call toString(int) directly on a key, unless you know that the key is actually a string. Recall that toString(int) changes the value at the given index; this confuses the next call to lua_next.

      Parameters:
      n - the index of the table
      Returns:
      0 if there are no more elements

    • rawGet

      void rawGet(int index)
      Similar to getTable(int), but does a raw access (i.e., without metamethods)
      Parameters:
      index - the index of the table

    • rawGetI

      void rawGetI(int index, int n)
      Pushes onto the stack the value t[n], where t is the value at the given valid index

      The access is raw; that is, it does not invoke metamethods.

      Parameters:
      index - the index of the table
      n - the key

    • rawSet

      void rawSet(int index)
      Similar to setTable(int), but does a raw assignment (i.e., without metamethods)
      Parameters:
      index - the index of the table

    • rawSetI

      void rawSetI(int index, int n)
      Does the equivalent of t[n] = v

      Does the equivalent of t[n] = v, where t is the value at the given valid index and v is the value at the top of the stack.

      This function pops the value from the stack. The assignment is raw; that is, it does not invoke metamethods.

      Parameters:
      index - the index of the table
      n - the key

    • ref

      int ref(int index)
      Creates and returns a reference, in the table at index index

      Creates and returns a reference, in the table at index t, for the object at the top of the stack (and pops the object).

      A reference is a unique integer key. As long as you do not manually add integer keys into table t, luaL_ref ensures the uniqueness of the key it returns. You can retrieve an object referred by reference r by calling rawGetI(int, int). Function unRef(int, int) frees a reference and its associated object.

      Parameters:
      index - the index of the table
      Returns:
      the created reference

    • ref

      int ref()
      Calls ref(int) with the pseudo-index LUA_REGISTRYINDEX
      Returns:
      the created reference

    • refGet

      void refGet(int ref)
      Calls rawGetI(int, int) with the pseudo-index LUA_REGISTRYINDEX and the given ref
      Parameters:
      ref - the reference on LUA_REGISTRYINDEX table

    • unRef

      void unRef(int index, int ref)
      Releases reference ref from the table at index index

      The entry is removed from the table, so that the referred object can be collected. The reference ref is also freed to be used again.

      Parameters:
      index - the index of the table
      ref - the reference to be freed

    • unref

      void unref(int ref)
      Calls unRef(int, int) with the pseudo-index LUA_REGISTRYINDEX and the given ref
      Parameters:
      ref - the reference to be freed

    • getGlobal

      void getGlobal(String name)
      Pushes onto the stack the value of the global name
      Parameters:
      name - the global name

    • setGlobal

      void setGlobal(String name)
      Pops a value from the stack and sets it as the new value of global name
      Parameters:
      name - the global name

    • getMetatable

      int getMetatable(int index)
      Pushes onto the stack the metatable of the value at the given acceptable index

      Pushes onto the stack the metatable of the value at the given acceptable index. If the index is not valid, or if the value does not have a metatable, the function returns 0 and pushes nothing on the stack.

      Parameters:
      index - the index of the element
      Returns:
      0 if the value does not have a metatable

    • setMetatable

      void setMetatable(int index)
      Pops a table from the stack and sets it as the new metatable for the value at the given acceptable index
      Parameters:
      index - the index of the element

    • getMetaField

      int getMetaField(int index, String field)
      Pushes onto the stack the field field from the metatable of the object at index index

      If the object does not have a metatable, or if the metatable does not have this field, returns 0 and pushes nothing.

      Parameters:
      index - the index of the element
      field - the meta field
      Returns:
      0 if no such field

    • getRegisteredMetatable

      void getRegisteredMetatable(String typeName)
      Pushes onto the stack the metatable associated with name tname in the registry
      Parameters:
      typeName - the name of the user-defined type
      See Also:

    • newRegisteredMetatable

      int newRegisteredMetatable(String typeName)
      Creates a new table to be used as a metatable for userdata, adds it to the registry

      If the registry already has the key typeName, returns 0. Otherwise, creates a new table to be used as a metatable for userdata, adds it to the registry with key typeName, and returns 1.

      In both cases pushes onto the stack the final value associated with tname in the registry.

      Parameters:
      typeName - the name of the user-defined type
      Returns:
      1 if added to registry, 0 if already registered

    • openLibraries

      void openLibraries()
      Opens all standard Lua libraries into the given state

      See openLibrary(String) for more info.

    • openLibrary

      void openLibrary(String name)
      Opens a specific library into the given state

      See the corresponding Lua manual for available library. For example, in Lua 5.4, calling L.openLibrary("base") will call the luaopen_base C function for the base library.

      Note that opening a library may modify global variables. For example, opening the base library in some specific Lua versions will override built-in functions like print. So make sure to make your modifications after opening all the libraries.

      Parameters:
      name - the library name

    • concat

      void concat(int n)
      Concatenates the n values at the top of the stack, pops them, and leaves the result at the top

      If n is 1, the result is the single value on the stack (that is, the function does nothing); if n is 0, the result is the empty string. Concatenation is performed following the usual semantics of Lua.

      Parameters:
      n - the number of values on top of the stack to concatenate

    • gc

      void gc()
      Performs a full garbage-collection cycle

      This also removes unneeded references created by finalized proxies and Lua values.

    • error

      void error(String message)
      Throws an error inside a Lua environment

      It currently just throws a RuntimeException.

      Parameters:
      message - the error message

    • createProxy

      Object createProxy(Class<?>[] interfaces, Lua.Conversion degree) throws IllegalArgumentException
      Creates a proxy object, implementing all the specified interfaces, with a Lua table / function on top of the stack

      This method pops the value on top on the stack and creates reference to it with ref().

      When invoking methods, the created Java object, instead of the backing Lua table, is passed as the first parameter to the Lua function.

      Parameters:
      interfaces - the interfaces to implement
      degree - the conversion degree when passing parameters and return values
      Returns:
      a proxy object, calls to which are proxied to the underlying Lua table
      Throws:
      IllegalArgumentException - if not all classes are interfaces

    • setExternalLoader

      void setExternalLoader(ExternalLoader loader)
      Sets a ExternalLoader for the main state

      The provided external loader will be integrated into Lua's module resolution progress. See require (modname) for an overview.

      We will register a new searcher by appending to package.searchers (or package.loaders for Lua 5.1) to load Lua files with this ExternalLoader.

      You need to load the package library to make the external loader effective.

      Parameters:
      loader - the loader that will be used to find files

    • loadExternal

      void loadExternal(String module) throws LuaException
      Loads a chunk from a ExternalLoader set by setExternalLoader(ExternalLoader)
      Parameters:
      module - the module
      Throws:
      LuaException

    • getLuaNatives

      LuaNatives getLuaNatives()
      Returns the underlying native Lua interface.
      Returns:
      the underlying LuaNatives natives

    • getMainState

      Lua getMainState()
      Returns the main Lua state.
      Returns:
      the main Lua state

    • getPointer

      long getPointer()
      Returns the pointer to the internal Lua state.
      Returns:
      the pointer to the internal lua_State

    • getId

      int getId()
      Returns the unique identifier of this Lua thread.
      Returns:
      the unique identifier to the Lua thread

    • getJavaError

      @Nullable Throwable getJavaError()
      Fetches the most recent Java Throwable passed to Lua
      Returns:
      value of the Lua global GLOBAL_THROWABLE

    • error

      int error(@Nullable Throwable e)
      Sets the Lua global GLOBAL_THROWABLE to the throwable

      If the exception is null, it clears the global exception and pushes nothing. Otherwise, it sets the Lua global GLOBAL_THROWABLE to the throwable, and pushes Throwable.toString() onto the stack.

      Parameters:
      e - the exception
      Returns:
      0 if e is null, -1 otherwise

    • close

      void close()
      Closes the thread

      You need to make sure that you call this method no more than once, or else the Lua binary may / will very likely just crash.

      Specified by:
      close in interface AutoCloseable

    • get

      LuaValue get()
      Pops the value on top of the stack and return a LuaValue referring to it
      Returns:
      a reference to the value