gradle=7.1.1, gradle migrateMappings

remappedSrc/dan200/computercraft/api/lua/MethodResult.java

@@ -0,0 +1,177 @@
+/*
+ * This file is part of the public ComputerCraft API - http://www.computercraft.info
+ * Copyright Daniel Ratcliffe, 2011-2021. This API may be redistributed unmodified and in full only.
+ * For help using the API, and posting your mods, visit the forums at computercraft.info.
+ */
+
+package dan200.computercraft.api.lua;
+
+import dan200.computercraft.api.peripheral.IComputerAccess;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import java.nio.ByteBuffer;
+import java.util.Collection;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * The result of invoking a Lua method.
+ *
+ * Method results either return a value immediately ({@link #of(Object...)} or yield control to the parent coroutine. When the current coroutine is resumed,
+ * we invoke the provided {@link ILuaCallback#resume(Object[])} callback.
+ */
+public final class MethodResult
+{
+    private static final MethodResult empty = new MethodResult( null, null );
+
+    private final Object[] result;
+    private final ILuaCallback callback;
+    private final int adjust;
+
+    private MethodResult( Object[] arguments, ILuaCallback callback )
+    {
+        result = arguments;
+        this.callback = callback;
+        adjust = 0;
+    }
+
+    private MethodResult( Object[] arguments, ILuaCallback callback, int adjust )
+    {
+        result = arguments;
+        this.callback = callback;
+        this.adjust = adjust;
+    }
+
+    /**
+     * Return no values immediately.
+     *
+     * @return A method result which returns immediately with no values.
+     */
+    @Nonnull
+    public static MethodResult of()
+    {
+        return empty;
+    }
+
+    /**
+     * Return a single value immediately.
+     *
+     * Integers, doubles, floats, strings, booleans, {@link Map}, {@link Collection}s, arrays and {@code null} will be converted to their corresponding Lua
+     * type. {@code byte[]} and {@link ByteBuffer} will be treated as binary strings. {@link ILuaFunction} will be treated as a function.
+     *
+     * In order to provide a custom object with methods, one may return a {@link IDynamicLuaObject}, or an arbitrary class with {@link LuaFunction}
+     * annotations. Anything else will be converted to {@code nil}.
+     *
+     * @param value The value to return to the calling Lua function.
+     * @return A method result which returns immediately with the given value.
+     */
+    @Nonnull
+    public static MethodResult of( @Nullable Object value )
+    {
+        return new MethodResult( new Object[] { value }, null );
+    }
+
+    /**
+     * Return any number of values immediately.
+     *
+     * @param values The values to return. See {@link #of(Object)} for acceptable values.
+     * @return A method result which returns immediately with the given values.
+     */
+    @Nonnull
+    public static MethodResult of( @Nullable Object... values )
+    {
+        return values == null || values.length == 0 ? empty : new MethodResult( values, null );
+    }
+
+    /**
+     * Wait for an event to occur on the computer, suspending the thread until it arises. This method is exactly equivalent to {@code os.pullEvent()} in
+     * lua.
+     *
+     * @param filter   A specific event to wait for, or null to wait for any event.
+     * @param callback The callback to resume with the name of the event that occurred, and any event parameters.
+     * @return The method result which represents this yield.
+     * @see IComputerAccess#queueEvent(String, Object[])
+     */
+    @Nonnull
+    public static MethodResult pullEvent( @Nullable String filter, @Nonnull ILuaCallback callback )
+    {
+        Objects.requireNonNull( callback, "callback cannot be null" );
+        return new MethodResult( new Object[] { filter }, results -> {
+            if( results.length >= 1 && results[0].equals( "terminate" ) )
+            {
+                throw new LuaException( "Terminated", 0 );
+            }
+            return callback.resume( results );
+        } );
+    }
+
+    /**
+     * The same as {@link #pullEvent(String, ILuaCallback)}, except "terminated" events are ignored. Only use this if you want to prevent program
+     * termination, which is not recommended. This method is exactly equivalent to {@code os.pullEventRaw()} in Lua.
+     *
+     * @param filter   A specific event to wait for, or null to wait for any event.
+     * @param callback The callback to resume with the name of the event that occurred, and any event parameters.
+     * @return The method result which represents this yield.
+     * @see #pullEvent(String, ILuaCallback)
+     */
+    @Nonnull
+    public static MethodResult pullEventRaw( @Nullable String filter, @Nonnull ILuaCallback callback )
+    {
+        Objects.requireNonNull( callback, "callback cannot be null" );
+        return new MethodResult( new Object[] { filter }, callback );
+    }
+
+    /**
+     * Yield the current coroutine with some arguments until it is resumed. This method is exactly equivalent to {@code coroutine.yield()} in lua. Use
+     * {@code pullEvent()} if you wish to wait for events.
+     *
+     * @param arguments An object array containing the arguments to pass to coroutine.yield()
+     * @param callback  The callback to resume with an array containing the return values from coroutine.yield()
+     * @return The method result which represents this yield.
+     * @see #pullEvent(String, ILuaCallback)
+     */
+    @Nonnull
+    public static MethodResult yield( @Nullable Object[] arguments, @Nonnull ILuaCallback callback )
+    {
+        Objects.requireNonNull( callback, "callback cannot be null" );
+        return new MethodResult( arguments, callback );
+    }
+
+    @Nullable
+    public Object[] getResult()
+    {
+        return result;
+    }
+
+    @Nullable
+    public ILuaCallback getCallback()
+    {
+        return callback;
+    }
+
+    public int getErrorAdjust()
+    {
+        return adjust;
+    }
+
+    /**
+     * Increase the Lua error by a specific amount. One should never need to use this function - it largely exists for some CC internal code.
+     *
+     * @param adjust The amount to increase the level by.
+     * @return The new {@link MethodResult} with an adjusted error. This has no effect on immediate results.
+     */
+    @Nonnull
+    public MethodResult adjustError( int adjust )
+    {
+        if( adjust < 0 )
+        {
+            throw new IllegalArgumentException( "cannot adjust by a negative amount" );
+        }
+        if( adjust == 0 || callback == null )
+        {
+            return this;
+        }
+        return new MethodResult( result, callback, this.adjust + adjust );
+    }
+}