Interface IArguments
- All Known Implementing Classes:
ObjectArguments
-
Method Summary
Modifier and TypeMethodDescriptionint
count()
Get the number of arguments passed to this function.drop
(int count) Drop a number of arguments.default IArguments
escapes()
Create a version of these arguments which escapes the scope of the current function call.@Nullable Object
get
(int index) Get the argument at the specific index.default Object[]
getAll()
Get an array containing all asObject
s.default boolean
getBoolean
(int index) Get an argument as a boolean.default ByteBuffer
getBytes
(int index) Get a string argument as a byte array.default ByteBuffer
getBytesCoerced
(int index) Get the argument, converting it to the raw-byte representation of its string by following Lua conventions.default double
getDouble
(int index) Get an argument as a double.default <T extends Enum<T>>
TGet a string argument as an enum value.default double
getFiniteDouble
(int index) Get an argument as a finite number (not infinite or NaN).default int
getInt
(int index) Get an argument as an integer.default long
getLong
(int index) Get an argument as a long.default String
getString
(int index) Get an argument as a string.default String
getStringCoerced
(int index) Get the argument, converting it to a string by following Lua conventions.default Map<?,
?> getTable
(int index) Get an argument as a table.default LuaTable<?,
?> getTableUnsafe
(int index) Get an argument as a table in an unsafe manner.getType
(int index) Get the type name of the argument at the specific index.optBoolean
(int index) Get an argument as a boolean.default boolean
optBoolean
(int index, boolean def) Get an argument as a boolean.default Optional<ByteBuffer>
optBytes
(int index) Get a string argument as a byte array.optDouble
(int index) Get an argument as a double.default double
optDouble
(int index, double def) Get an argument as a double.Get a string argument as an enum value.optFiniteDouble
(int index) Get an argument as a finite number (not infinite or NaN).default double
optFiniteDouble
(int index, double def) Get an argument as a finite number (not infinite or NaN).optInt
(int index) Get an argument as an int.default int
optInt
(int index, int def) Get an argument as an int.optLong
(int index) Get an argument as a long.default long
optLong
(int index, long def) Get an argument as a long.optString
(int index) Get an argument as a string.default @Nullable String
Get an argument as a string.optTable
(int index) Get an argument as a table.default @Nullable Map<?,
?> Get an argument as a table.optTableUnsafe
(int index) Get an argument as a table in an unsafe manner.
-
Method Details
-
count
int count()Get the number of arguments passed to this function.- Returns:
- The number of passed arguments.
-
get
Get the argument at the specific index. The returned value must obey the following conversion rules:- Lua values of type "string" will be represented by a
String
. - Lua values of type "number" will be represented by a
Number
. - Lua values of type "boolean" will be represented by a
Boolean
. - Lua values of type "table" will be represented by a
Map
. - Lua values of any other type will be represented by a
null
value.
- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
null
if not present. - Throws:
LuaException
- If the argument cannot be converted to Java. This should be thrown in extraneous circumstances (if the conversion would allocate too much memory) and should not be thrown if the original argument is not present or is an unsupported data type (such as a function or userdata).IllegalStateException
- If accessing these arguments outside the scope of the original function. Seeescapes()
.
- Lua values of type "string" will be represented by a
-
getType
Get the type name of the argument at the specific index.This method is meant to be used in error reporting (namely with
LuaValues.badArgumentOf(IArguments, int, String)
), and should not be used to determine the actual type of an argument.- Parameters:
index
- The argument number.- Returns:
- The name of this type.
- See Also:
-
drop
Drop a number of arguments. The returned arguments instance will access arguments at positioni + count
, rather thani
. However, errors will still use the given argument index.- Parameters:
count
- The number of arguments to drop.- Returns:
- The new
IArguments
instance.
-
getAll
Get an array containing all asObject
s.- Returns:
- All arguments.
- Throws:
LuaException
- If an error occurred while fetching an argument.- See Also:
-
getDouble
Get an argument as a double.- Parameters:
index
- The argument number.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not a number.- See Also:
-
getInt
Get an argument as an integer.- Parameters:
index
- The argument number.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not an integer.
-
getLong
Get an argument as a long.- Parameters:
index
- The argument number.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not a long.
-
getFiniteDouble
Get an argument as a finite number (not infinite or NaN).- Parameters:
index
- The argument number.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not finite.
-
getBoolean
Get an argument as a boolean.- Parameters:
index
- The argument number.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not a boolean.
-
getString
Get an argument as a string.- Parameters:
index
- The argument number.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not a string.
-
getStringCoerced
Get the argument, converting it to a string by following Lua conventions.Unlike
Objects.toString(arguments.get(i))
, this may follow Lua's string formatting, sonil
will be converted to"nil"
and tables/functions will use their original hash.- Parameters:
index
- The argument number.- Returns:
- The argument's representation as a string.
- Throws:
LuaException
- If the argument cannot be converted to Java. This should be thrown in extraneous circumstances (if the conversion would allocate too much memory) and should not be thrown if the original argument is not present or is an unsupported data type (such as a function or userdata).IllegalStateException
- If accessing these arguments outside the scope of the original function. Seeescapes()
.- See Also:
-
getBytes
Get a string argument as a byte array.- Parameters:
index
- The argument number.- Returns:
- The argument's value. This is a read only buffer.
- Throws:
LuaException
- If the value is not a string.
-
getBytesCoerced
Get the argument, converting it to the raw-byte representation of its string by following Lua conventions.This is equivalent to
getStringCoerced(int)
, but then- Parameters:
index
- The argument number.- Returns:
- The argument's value. This is a read only buffer.
- Throws:
LuaException
- If the argument cannot be converted to Java.
-
getEnum
Get a string argument as an enum value.- Type Parameters:
T
- The type of enum to parse.- Parameters:
index
- The argument number.klass
- The type of enum to parse.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not a string or not a valid option for this enum.
-
getTable
Get an argument as a table.The returned table may be converted into a
LuaTable
(usingObjectLuaTable
) for easier parsing of table keys.- Parameters:
index
- The argument number.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not a table.
-
getTableUnsafe
Get an argument as a table in an unsafe manner.Classes implementing this interface may choose to implement a more optimised version which does not copy the table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that they do not access the table the computer thread (and so should not be used with main-thread functions) or once the initial call has finished (for instance, in a callback to
MethodResult.pullEvent(java.lang.String, dan200.computercraft.api.lua.ILuaCallback)
).- Parameters:
index
- The argument number.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not a table.
-
optDouble
Get an argument as a double.- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. - Throws:
LuaException
- If the value is not a number.
-
optInt
Get an argument as an int.- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. - Throws:
LuaException
- If the value is not a number.
-
optLong
Get an argument as a long.- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. - Throws:
LuaException
- If the value is not a number.
-
optFiniteDouble
Get an argument as a finite number (not infinite or NaN).- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. - Throws:
LuaException
- If the value is not finite.
-
optBoolean
Get an argument as a boolean.- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. - Throws:
LuaException
- If the value is not a boolean.
-
optString
Get an argument as a string.- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. - Throws:
LuaException
- If the value is not a string.
-
optBytes
Get a string argument as a byte array.- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. This is a read only buffer. - Throws:
LuaException
- If the value is not a string.
-
optEnum
Get a string argument as an enum value.- Type Parameters:
T
- The type of enum to parse.- Parameters:
index
- The argument number.klass
- The type of enum to parse.- Returns:
- The argument's value.
- Throws:
LuaException
- If the value is not a string or not a valid option for this enum.
-
optTable
Get an argument as a table.- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. - Throws:
LuaException
- If the value is not a table.
-
optTableUnsafe
Get an argument as a table in an unsafe manner.Classes implementing this interface may choose to implement a more optimised version which does not copy the table, instead returning a wrapper version, making it more efficient. However, the caller must guarantee that they do not access off the computer thread (and so should not be used with main-thread functions) or once the function call has finished (for instance, in callbacks).
- Parameters:
index
- The argument number.- Returns:
- The argument's value, or
Optional.empty()
if not present. - Throws:
LuaException
- If the value is not a table.
-
optDouble
Get an argument as a double.- Parameters:
index
- The argument number.def
- The default value, if this argument is not given.- Returns:
- The argument's value, or
def
if none was provided. - Throws:
LuaException
- If the value is not a number.
-
optInt
Get an argument as an int.- Parameters:
index
- The argument number.def
- The default value, if this argument is not given.- Returns:
- The argument's value, or
def
if none was provided. - Throws:
LuaException
- If the value is not a number.
-
optLong
Get an argument as a long.- Parameters:
index
- The argument number.def
- The default value, if this argument is not given.- Returns:
- The argument's value, or
def
if none was provided. - Throws:
LuaException
- If the value is not a number.
-
optFiniteDouble
Get an argument as a finite number (not infinite or NaN).- Parameters:
index
- The argument number.def
- The default value, if this argument is not given.- Returns:
- The argument's value, or
def
if none was provided. - Throws:
LuaException
- If the value is not finite.
-
optBoolean
Get an argument as a boolean.- Parameters:
index
- The argument number.def
- The default value, if this argument is not given.- Returns:
- The argument's value, or
def
if none was provided. - Throws:
LuaException
- If the value is not a boolean.
-
optString
@Contract("_, !null -> !null") default @Nullable String optString(int index, @Nullable String def) throws LuaException Get an argument as a string.- Parameters:
index
- The argument number.def
- The default value, if this argument is not given.- Returns:
- The argument's value, or
def
if none was provided. - Throws:
LuaException
- If the value is not a string.
-
optTable
@Contract("_, !null -> !null") default @Nullable Map<?,?> optTable(int index, @Nullable Map<Object, Object> def) throws LuaExceptionGet an argument as a table.- Parameters:
index
- The argument number.def
- The default value, if this argument is not given.- Returns:
- The argument's value, or
def
if none was provided. - Throws:
LuaException
- If the value is not a table.
-
escapes
Create a version of these arguments which escapes the scope of the current function call.Some
IArguments
implementations provide a view over the underlying Lua data structures, allowing for zero-copy implementations of some methods (such asgetTableUnsafe(int)
orgetBytes(int)
). However, this means the arguments can only be accessed inside the current function call.If the arguments escape the scope of the current call (for instance, are later accessed on the main server thread), then these arguments must be marked as "escaping", which may choose to perform a copy of the underlying arguments.
If you are using
LuaFunction.mainThread()
, this will be done automatically. However, if you callILuaContext.issueMainThreadTask(LuaTask)
(or similar), then you will need to mark arguments as escaping yourself.- Returns:
- An
IArguments
instance which can escape the current scope. May bethis
. - Throws:
LuaException
- For the same reasons asget(int)
.IllegalStateException
- If marking these arguments as escaping outside the scope of the original function.
-