src/main/java/li/cil/oc/api/machine/Arguments.java

package li.cil.oc.api.machine;

import net.minecraft.item.ItemStack;

import java.util.Map;

/**
 * This interface provides access to arguments passed to a {@link Callback}.
 * <p/>
 * It allows checking for the presence of arguments in a uniform manner, taking
 * care of proper type checking based on what can be passed along by Lua.
 * <p/>
 * Note that integer values fetched this way are actually double values that
 * have been truncated. So if a Lua program passes <tt>1.9</tt> and you do a
 * <tt>checkInteger</tt> you'll get a <tt>1</tt>.
 * <p/>
 * The indexes passed to the various functions start at zero, i.e. to get the
 * first argument you would use <tt>checkAny(0)</tt>. This is worth mentioning
 * because Lua starts its indexes at one.
 */
public interface Arguments extends Iterable<Object> {
    /**
     * The total number of arguments that were passed to the function.
     */
    int count();

    /**
     * Get whatever is at the specified index.
     * <p/>
     * Throws an error if there are too few arguments.
     * <p/>
     * The returned object will be one of the following, based on the conversion
     * performed internally:
     * <ul>
     * <li><tt>null</tt> if the Lua value was <tt>nil</tt>.</li>
     * <li><tt>java.lang.Boolean</tt> if the Lua value was a boolean.</li>
     * <li><tt>java.lang.Double</tt> if the Lua value was a number.</li>
     * <li><tt>byte[]</tt> if the Lua value was a string.</li>
     * </ul>
     *
     * @param index the index from which to get the argument.
     * @return the raw value at that index.
     * @throws IllegalArgumentException if there is no argument at that index.
     */
    Object checkAny(int index);

    /**
     * Try to get a boolean value at the specified index.
     * <p/>
     * Throws an error if there are too few arguments.
     *
     * @param index the index from which to get the argument.
     * @return the boolean value at the specified index.
     * @throws IllegalArgumentException if there is no argument at that index,
     *                                  or if the argument is not a boolean.
     */
    boolean checkBoolean(int index);

    /**
     * Try to get an integer value at the specified index.
     * <p/>
     * Throws an error if there are too few arguments.
     *
     * @param index the index from which to get the argument.
     * @return the integer value at the specified index.
     * @throws IllegalArgumentException if there is no argument at that index,
     *                                  or if the argument is not a number.
     */
    int checkInteger(int index);

    /**
     * Try to get a double value at the specified index.
     * <p/>
     * Throws an error if there are too few arguments.
     *
     * @param index the index from which to get the argument.
     * @return the double value at the specified index.
     * @throws IllegalArgumentException if there is no argument at that index,
     *                                  or if the argument is not a number.
     */
    double checkDouble(int index);

    /**
     * Try to get a string value at the specified index.
     * <p/>
     * Throws an error if there are too few arguments.
     * <p/>
     * This will actually check for a byte array and convert it to a string
     * using UTF-8 encoding.
     *
     * @param index the index from which to get the argument.
     * @return the boolean value at the specified index.
     * @throws IllegalArgumentException if there is no argument at that index,
     *                                  or if the argument is not a string.
     */
    String checkString(int index);

    /**
     * Try to get a byte array at the specified index.
     * <p/>
     * Throws an error if there are too few arguments.
     *
     * @param index the index from which to get the argument.
     * @return the byte array at the specified index.
     * @throws IllegalArgumentException if there is no argument at that index,
     *                                  or if the argument is not a byte array.
     */
    byte[] checkByteArray(int index);

    /**
     * Try to get a table at the specified index.
     * <p/>
     * Throws an error if there are too few arguments.
     *
     * @param index the index from which to get the argument.
     * @return the table at the specified index.
     * @throws IllegalArgumentException if there is no argument at that index,
     *                                  or if the argument is not a table.
     */
    Map checkTable(int index);

    /**
     * Try to get an item stack representation at the specified index.
     * <p/>
     * This is a utility method provided to convert tables to item stacks, with
     * the tables being of a compatible format to that of tables generated by
     * the built-in item stack converter. In particular, this takes care of
     * restoring NBT data attached to the item stack.
     * <p/>
     * Throws an error if there are too few arguments.
     * <p/>
     * <em>Important</em>: usually you will not want to be using this. Some
     * items require NBT information to fully describe them, and by default
     * this information is not returned to underlying architectures when
     * item stacks are returned from callbacks. This means the scripts can
     * usually not provide this full information, so the roundtrip callback->
     * script->callback will be incomplete.
     * <p/>
     * Instead, please make use of the {@link li.cil.oc.api.internal.Database}
     * component to get complete item stack descriptors.
     *
     * @param index the index from which to get the argument.
     * @return the item stack at the specified index.
     */
    ItemStack checkItemStack(int index);

    /**
     * Get whatever is at the specified index.
     * <p/>
     * Return the specified default value if there is no such element, behaves
     * like {@link #checkAny(int)} otherwise.
     * <p/>
     * The returned object will be one of the following, based on the conversion
     * performed internally:
     * <ul>
     * <li><tt>null</tt> if the Lua value was <tt>nil</tt>.</li>
     * <li><tt>java.lang.Boolean</tt> if the Lua value was a boolean.</li>
     * <li><tt>java.lang.Double</tt> if the Lua value was a number.</li>
     * <li><tt>byte[]</tt> if the Lua value was a string.</li>
     * </ul>
     *
     * @param index the index from which to get the argument.
     * @return the raw value at that index.
     */
    Object optAny(int index, Object def);

    /**
     * Try to get a boolean value at the specified index.
     * <p/>
     * Return the specified default value if there is no such element, behaves
     * like {@link #checkBoolean(int)} otherwise.
     *
     * @param index the index from which to get the argument.
     * @return the boolean value at the specified index.
     * @throws IllegalArgumentException if the argument exists and is not a boolean.
     */
    boolean optBoolean(int index, boolean def);

    /**
     * Try to get an integer value at the specified index.
     * <p/>
     * Return the specified default value if there is no such element, behaves
     * like {@link #checkInteger(int)} otherwise.
     *
     * @param index the index from which to get the argument.
     * @return the integer value at the specified index.
     * @throws IllegalArgumentException if the argument exists but is not a number.
     */
    int optInteger(int index, int def);

    /**
     * Try to get a double value at the specified index.
     * <p/>
     * Return the specified default value if there is no such element, behaves
     * like {@link #checkDouble(int)} otherwise.
     *
     * @param index the index from which to get the argument.
     * @return the double value at the specified index.
     * @throws IllegalArgumentException if the argument exists and is not a number.
     */
    double optDouble(int index, double def);

    /**
     * Try to get a string value at the specified index.
     * <p/>
     * Return the specified default value if there is no such element, behaves
     * like {@link #checkString(int)} otherwise.
     * <p/>
     * This will actually check for a byte array and convert it to a string
     * using UTF-8 encoding.
     *
     * @param index the index from which to get the argument.
     * @return the boolean value at the specified index.
     * @throws IllegalArgumentException if the argument exists and is not a string.
     */
    String optString(int index, String def);

    /**
     * Try to get a byte array at the specified index.
     * <p/>
     * Return the specified default value if there is no such element, behaves
     * like {@link #checkByteArray(int)} otherwise.
     *
     * @param index the index from which to get the argument.
     * @return the byte array at the specified index.
     * @throws IllegalArgumentException if the argument exists and is not a byte array.
     */
    byte[] optByteArray(int index, byte[] def);

    /**
     * Try to get a table at the specified index.
     * <p/>
     * Return the specified default value if there is no such element, behaves
     * like {@link #checkTable(int)} otherwise.
     *
     * @param index the index from which to get the argument.
     * @return the table at the specified index.
     * @throws IllegalArgumentException if the argument exists and is not a table.
     */
    Map optTable(int index, Map def);

    /**
     * Try to get an item stack at the specified index.
     * <p/>
     * Return the specified default value if there is no such element, behaves
     * like {@link #checkItemStack(int)} otherwise.
     *
     * @param index the index from which to get the argument.
     * @return the item stack at the specified index.
     * @throws IllegalArgumentException if the argument exists and is not an item stack.
     */
    ItemStack optItemStack(int index, ItemStack def);

    /**
     * Tests whether the argument at the specified index is a boolean value.
     * <p/>
     * This will return false if there is <em>no</em> argument at the specified
     * index, i.e. if there are too few arguments.
     *
     * @param index the index to check.
     * @return true if the argument is a boolean; false otherwise.
     */
    boolean isBoolean(int index);

    /**
     * Tests whether the argument at the specified index is an integer value.
     * <p/>
     * This will return false if there is <em>no</em> argument at the specified
     * index, i.e. if there are too few arguments.
     *
     * @param index the index to check.
     * @return true if the argument is an integer; false otherwise.
     */
    boolean isInteger(int index);

    /**
     * Tests whether the argument at the specified index is a double value.
     * <p/>
     * This will return false if there is <em>no</em> argument at the specified
     * index, i.e. if there are too few arguments.
     *
     * @param index the index to check.
     * @return true if the argument is a double; false otherwise.
     */
    boolean isDouble(int index);

    /**
     * Tests whether the argument at the specified index is a string value.
     * <p/>
     * This will return false if there is <em>no</em> argument at the specified
     * index, i.e. if there are too few arguments.
     *
     * @param index the index to check.
     * @return true if the argument is a string; false otherwise.
     */
    boolean isString(int index);

    /**
     * Tests whether the argument at the specified index is a byte array.
     * <p/>
     * This will return false if there is <em>no</em> argument at the specified
     * index, i.e. if there are too few arguments.
     *
     * @param index the index to check.
     * @return true if the argument is a byte array; false otherwise.
     */
    boolean isByteArray(int index);

    /**
     * Tests whether the argument at the specified index is a table.
     * <p/>
     * This will return false if there is <em>no</em> argument at the specified
     * index, i.e. if there are too few arguments.
     *
     * @param index the index to check.
     * @return true if the argument is a table; false otherwise.
     */
    boolean isTable(int index);

    /**
     * Tests whether the argument at the specified index is an item stack.
     * <p/>
     * This will return false if there is <em>no</em> argument at the specified
     * index, i.e. if there are too few arguments.
     *
     * @param index the index to check.
     * @return true if the argument is an item stack; false otherwise.
     */
    boolean isItemStack(int index);

    /**
     * Converts the argument list to a standard Java array, converting byte
     * arrays to strings automatically, since this is usually what others
     * want - if you need the actual raw byte arrays, don't use this method!
     *
     * @return an array containing all arguments.
     */
    Object[] toArray();
}