Package dan200.computercraft.api.lua

Interface IArguments

All Known Implementing Classes:
ObjectArguments
public interface IArguments
The arguments passed to a function.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    count()
    Get the number of arguments passed to this function.
    IArguments
    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.
    Object
    get(int index)
    Get the argument at the specific index.
    default Object[]
    getAll()
    Get an array containing all as Objects.
    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>>
    T
    getEnum(int index, Class<T> klass)
    Get 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.
    String
    getType(int index)
    Get the type name of the argument at the specific index.
    default Optional<Boolean>
    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.
    default Optional<Double>
    optDouble(int index)
    Get an argument as a double.
    default double
    optDouble(int index, double def)
    Get an argument as a double.
    default <T extends Enum<T>>
    Optional<T>
    optEnum(int index, Class<T> klass)
    Get a string argument as an enum value.
    default Optional<Double>
    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).
    default Optional<Integer>
    optInt(int index)
    Get an argument as an int.
    default int
    optInt(int index, int def)
    Get an argument as an int.
    default Optional<Long>
    optLong(int index)
    Get an argument as a long.
    default long
    optLong(int index, long def)
    Get an argument as a long.
    default Optional<String>
    optString(int index)
    Get an argument as a string.
    default String
    optString(int index, String def)
    Get an argument as a string.
    default Optional<Map<?,?>>
    optTable(int index)
    Get an argument as a table.
    default Map<?,?>
    optTable(int index, Map<Object,Object> def)
    Get an argument as a table.
    default Optional<LuaTable<?,?>>
    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

      @Nullable Object get(int index) throws LuaException
      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. See escapes().

    • getType

      String getType(int index)
      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

      IArguments drop(int count)
      Drop a number of arguments. The returned arguments instance will access arguments at position i + count, rather than i. However, errors will still use the given argument index.
      Parameters:
      count - The number of arguments to drop.
      Returns:
      The new IArguments instance.

    • getAll

      default Object[] getAll() throws LuaException
      Get an array containing all as Objects.
      Returns:
      All arguments.
      Throws:
      LuaException - If an error occurred while fetching an argument.
      See Also:

    • getDouble

      default double getDouble(int index) throws LuaException
      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

      default int getInt(int index) throws LuaException
      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

      default long getLong(int index) throws LuaException
      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

      default double getFiniteDouble(int index) throws LuaException
      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

      default boolean getBoolean(int index) throws LuaException
      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

      default String getString(int index) throws LuaException
      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

      default String getStringCoerced(int index) throws LuaException
      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, so nil 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. See escapes().
      See Also:

    • getBytes

      default ByteBuffer getBytes(int index) throws LuaException
      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

      default ByteBuffer getBytesCoerced(int index) throws LuaException
      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

      default <T extends Enum<T>> T getEnum(int index, Class<T> klass) throws LuaException
      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

      default Map<?,?> getTable(int index) throws LuaException
      Get an argument as a table.
      Parameters:
      index - The argument number.
      Returns:
      The argument's value.
      Throws:
      LuaException - If the value is not a table.

    • getTableUnsafe

      default LuaTable<?,?> getTableUnsafe(int index) throws LuaException
      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

      default Optional<Double> optDouble(int index) throws LuaException
      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

      default Optional<Integer> optInt(int index) throws LuaException
      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

      default Optional<Long> optLong(int index) throws LuaException
      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

      default Optional<Double> optFiniteDouble(int index) throws LuaException
      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

      default Optional<Boolean> optBoolean(int index) throws LuaException
      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

      default Optional<String> optString(int index) throws LuaException
      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

      default Optional<ByteBuffer> optBytes(int index) throws LuaException
      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

      default <T extends Enum<T>> Optional<T> optEnum(int index, Class<T> klass) throws LuaException
      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

      default Optional<Map<?,?>> optTable(int index) throws LuaException
      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

      default Optional<LuaTable<?,?>> optTableUnsafe(int index) throws LuaException
      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

      default double optDouble(int index, double def) throws LuaException
      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

      default int optInt(int index, int def) throws LuaException
      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

      default long optLong(int index, long def) throws LuaException
      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

      default double optFiniteDouble(int index, double def) throws LuaException
      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

      default boolean optBoolean(int index, boolean def) throws LuaException
      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

      @Nullable @Contract("_, !null -> !null") default 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

      @Nullable @Contract("_, !null -> !null") default Map<?,?> optTable(int index, @Nullable Map<Object,Object> def) throws LuaException
      Get 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

      default IArguments escapes() throws LuaException
      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 as getTableUnsafe(int) or getBytes(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 call ILuaContext.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 be this.
      Throws:
      LuaException - For the same reasons as get(int).
      IllegalStateException - If marking these arguments as escaping outside the scope of the original function.