run_async() and small run() documentation fix

Author: Oxtaly

docs/scarpet/api/Auxiliary.md

@@ -406,19 +406,20 @@ read_file('foo', 'shared_text')     => ['one', 'two', 'three', '', 'four', '', '
 
 ### `run(expr)`
 
-Runs a vanilla command from the string result of the `expr` and returns a triple of 0 (unused after success count removal), 
-intercepted list of output messages, and error message if the command resulted in a failure. 
-Successful commands return `null` as their error.
+Runs a vanilla command from the string result of the `expr` and returns a triple of the exit code (usually 0 or 1), 
+intercepted list of output messages, and last synchronous error message if the command resulted in a failure.
+The exit code may be null if a non command caused error occurred while running the command, 
+with the error message field giving the error message.
 
 The command return `null` if the command was not run immediately, but was scheduled for later execution 
-due to being requested while command was executed. This happens most commonly
-when running `run` from a `/script run/invoke` command since that always results in piling up command to run while `script` is being executed.
+due to being requested while command was executed. This happens most commonly when running `run` from a `/script run/invoke`
+command or from a custom app command callback function since that always results in piling up command to run while `script` is being executed.
 
-The mitigation for this is to use `run` in a separate scheduled function, or use `run` in a `tick` event, or literally in 
-any other way than directly from a `/script` command, which will ensure that the command runs immediately.
+The mitigation for this is to use `run` in a separate scheduled function, or use `run` in a `tick` event, or in other ways than
+directly from a `/script` command or custom app command callback, which will ensure that the command runs immediately.
 
 <pre>
-run('fill 1 1 1 10 10 10 air') -> [123, ["Successfully filled 123 blocks"], null]
+run('fill 1 1 1 10 10 10 air') -> [123, ["Successfully filled 123 block(s)"], null]
 run('give @s stone 4') -> [1, ["Gave 4 [Stone] to gnembon"], null]
 run('seed') -> [-170661413, [Seed: [4031384495743822299]], null]
 run('sed') -> [-1, [], "sed<--[HERE]"] // wrong command
@@ -427,6 +428,22 @@ run('sed') -> [-1, [], "sed<--[HERE]"] // wrong command
 /script run schedule(0, _() -> print(run('setblock 0 0 0 stone'))) -> [1, [Changed the block at 0, 0, 0], null]
 </pre>
 
+### `run_async(expr, callback)`
+
+Runs a vanilla command from the string result of the `expr` and calls `callback` with a triple of the exit code (usually 0 or 1),
+intercepted list of output messages, and first synchronous error message if the command resulted in a failure.
+The exit code may be null if a non command caused error occurred while running the command,
+with the error message field giving the error message.
+
+<pre>
+run_async('fill 1 1 1 10 10 10 air', _(result) -> print(result)) -> [123, ["Successfully filled 123 block(s)"], null]
+run_async('give @s stone 4', _(result) -> print(result)) -> [1, ["Gave 4 [Stone] to gnembon"], null]
+run_async('seed', _(result) -> print(result)) -> [-170661413, [Seed: [4031384495743822299]], null]
+run_async('sed', _(result) -> print(result)) -> [-1, [], "sed<--[HERE]"] // wrong command
+
+/script run run_async('setblock 0 0 0 stone', _(result) -> print(result)) -> [1, [Changed the block at 0, 0, 0], null]
+</pre>
+
 ### `save()`
 
 Performs autosave, saves all chunks, player data, etc. Useful for programs where autosave is disabled due to 

src/main/java/carpet/script/api/Auxiliary.java

@@ -706,6 +706,106 @@ else if (!interactable && targetBlock == null)
             }
         });
 
+        expression.addContextFunction("run_async", 1, (c, t, lv) ->
+        {
+            CommandSourceStack source = ((CarpetContext) c).source();
+            FunctionArgument callback = FunctionArgument.findIn(c, expression.module, lv, 1, true, false);
+            String command = lv.get(0).getString();
+            if(callback.function == null)
+            {
+                try
+                {
+                    Component[] errorOutput = {null};
+                    List<Component> output = new ArrayList<>();
+                    OptionalLong[] returnValue = {OptionalLong.empty()};
+                    source.getServer().getCommands().performPrefixedCommand(
+                            new SnoopyCommandSource(source, errorOutput, output, returnValue),
+                            command
+                    );
+                }
+                catch (Exception ignored)
+                {
+                }
+                return Value.NULL;
+            }
+            else if (callback.function.getArguments().size() < 1)
+            {
+                throw new InternalExpressionException("callback requires 1 argument for command output");
+            }
+            boolean[] isCallbackConsumed = {false};
+            try
+            {
+                boolean[] hasCommandError = {false};
+                Integer[] commandExitCode = {null};
+                Component[] errorOutput = {null};
+                List<Component> output = new ArrayList<>();
+                OptionalLong[] ignoredReturnedValue = {OptionalLong.empty()};
+
+                SnoopyCommandSource snoopyCommandSource = (SnoopyCommandSource) new SnoopyCommandSource(source, errorOutput, output, ignoredReturnedValue)
+                        .withCallback((success, exitCode) -> {
+                            if(isCallbackConsumed[0])
+                            {
+                                return;
+                            }
+                            isCallbackConsumed[0] = true;
+                            // The CommandSourceStack.sendFailure are sent after the resultConsumer, so the error output is always empty in
+                            // this resultConsumer. This workaround is using the resultConsumer in tandem with an errorCallback.
+                            if(!success)
+                            {
+                                hasCommandError[0] = true;
+                                commandExitCode[0] = exitCode;
+                                return;
+                            }
+                            List<Value> args = List.of(ListValue.of(
+                                    NumericValue.of(exitCode),
+                                    ListValue.wrap(output.stream().map(FormattedTextValue::new)),
+                                    FormattedTextValue.of(errorOutput[0])
+                            ));
+                            callback.function.callInContext(c, t, args);
+                        });
+                // To catch errors that don't call the resultConsumer and make sure the error output is set for those that do.
+                snoopyCommandSource.setErrorCallback((ignored) -> {
+                    if(isCallbackConsumed[0])
+                    {
+                        if(!hasCommandError[0])
+                        {
+                            return;
+                        }
+                        List<Value> args = List.of(ListValue.of(
+                                NumericValue.of(commandExitCode[0]),
+                                ListValue.wrap(output.stream().map(FormattedTextValue::new)),
+                                FormattedTextValue.of(errorOutput[0])
+                        ));
+                        callback.function.callInContext(c, t, args);
+                        return;
+                    }
+                    isCallbackConsumed[0] = true;
+                    List<Value> args = List.of(ListValue.of(
+                            Value.NULL,
+                            ListValue.of(),
+                            FormattedTextValue.of(errorOutput[0])
+                    ));
+                    callback.function.callInContext(c, t, args);
+                });
+
+                source.getServer().getCommands().performPrefixedCommand(snoopyCommandSource, command);
+            }
+            catch (Exception exc)
+            {
+                if(!isCallbackConsumed[0])
+                {
+                    isCallbackConsumed[0] = true;
+                    List<Value> args = List.of(ListValue.of(
+                            Value.NULL,
+                            ListValue.of(),
+                            new FormattedTextValue(Component.literal(exc.getMessage()))
+                    ));
+                    callback.function.callInContext(c, t, args);
+                }
+            }
+            return Value.NULL;
+        });
+
         expression.addContextFunction("save", 0, (c, t, lv) ->
         {
             CommandSourceStack s = ((CarpetContext) c).source();

src/main/java/carpet/script/utils/SnoopyCommandSource.java

@@ -21,6 +21,7 @@
 import java.util.List;
 import java.util.OptionalLong;
 import java.util.function.BinaryOperator;
+import java.util.function.Consumer;
 import java.util.function.Supplier;
 
 public class SnoopyCommandSource extends CommandSourceStack
@@ -44,6 +45,9 @@ public class SnoopyCommandSource extends CommandSourceStack
 
     private final TaskChainer taskChainer;
 
+    // sendFailure() callback
+    @Nullable private Consumer<Component> errorCallback = null;
+
     public SnoopyCommandSource(CommandSourceStack original, Component[] error, List<Component> chatOutput, OptionalLong[] returnValue)
     {
         super(CommandSource.NULL, original.getPosition(), original.getRotation(), original.getLevel(), Vanilla.MinecraftServer_getRunPermissionLevel(original.getServer()),
@@ -197,11 +201,26 @@ public CommandSourceStack facing(Vec3 position)
     public void sendFailure(Component message)
     {
         error[0] = message;
+        if(this.errorCallback != null)
+        {
+            this.errorCallback.accept(message);
+        }
     }
 
     @Override
     public void sendSuccess(Supplier<Component> message, boolean broadcastToOps)
     {
         chatOutput.add(message.get());
     }
+
+    /**
+     * Added for the new queue system for commands, since some early errors don't trigger the resultConsumer and all sendFailures calls
+     * are executed after the call resultConsumer when they do.
+     * @param errorCallback A consumer that will be called upon sendFailure
+     */
+    public void setErrorCallback(Consumer<Component> errorCallback)
+    {
+        this.errorCallback = errorCallback;
+    }
+
 }