io/process: add Process.exec()

src/io/process.hpp

@@ -10,7 +10,9 @@
 #include <qtypes.h>
 #include <qvariant.h>
 
+#include "../core/doc.hpp"
 #include "datastream.hpp"
+#include "processcore.hpp"
 
 // Needed when compiling with clang musl-libc++.
 // Default include paths contain macros that cause name collisions.
@@ -135,6 +137,40 @@ class Process: public QObject {
 public:
 	explicit Process(QObject* parent = nullptr);
 
+	// MUST be before exec(ctx) or the other will be called with a default constructed obj.
+	QSDOC_HIDE Q_INVOKABLE void exec(QList<QString> command);
+	/// Launch a process with the given arguments, stopping any currently running process.
+	///
+	/// The context parameter can either be a list of command arguments or a JS object with the following fields:
+	/// - `command`: A list containing the command and all its arguments. See @@Quickshell.Io.Process.command.
+	/// - `environment`: Changes to make to the process environment. See @@Quickshell.Io.Process.environment.
+	/// - `clearEnvironment`: Removes all variables from the environment if true.
+	/// - `workingDirectory`: The working directory the command should run in.
+	///
+	/// Passed parameters will change the values currently set in the process.
+	///
+	/// > [!WARNING] This does not run command in a shell. All arguments to the command
+	/// > must be in separate values in the list, e.g. `["echo", "hello"]`
+	/// > and not `["echo hello"]`.
+	/// >
+	/// > Additionally, shell scripts must be run by your shell,
+	/// > e.g. `["sh", "script.sh"]` instead of `["script.sh"]` unless the script
+	/// > has a shebang.
+	///
+	/// > [!INFO] You can use `["sh", "-c", <your command>]` to execute your command with
+	/// > the system shell.
+	///
+	/// Calling this function is equivalent to running:
+	/// ```qml
+	/// process.running = false;
+	/// process.command = ...
+	/// process.environment = ...
+	/// process.clearEnvironment = ...
+	/// process.workingDirectory = ...
+	/// process.running = true;
+	/// ```
+	Q_INVOKABLE void exec(const qs::io::process::ProcessContext& context);
+
 	/// Sends a signal to the process if @@running is true, otherwise does nothing.
 	Q_INVOKABLE void signal(qint32 signal);