Introduce QProcess::startCommand(QString, OpenMode)

The removal of the QProcess::start(QString, OpenMode) leads to more
porting work than anticipated. A call like

    QProcess p;
    p.start(cmdline);

must be transformed in the following cumbersome way:

    QProcess p;
    QStringList args = QProcess::splitCommand(cmdline);
    QString program = args.takeFirst();
    p.start(program, args);

This patch revives QProcess::start(QString, OpenMode) and renames it to
QProcess::startCommand. This is still source-incompatible, but the
transformation is much simpler:

    QProcess p;
    p.startCommand(cmdline);

[ChangeLog][QtCore][QProcess] Added QProcess::startCommand(QString,
OpenMode) as replacement for the removed QProcess::start(QString,
OpenMode).

Change-Id: I5499bbb39a025e115042c43a4cc63affddae585c
Reviewed-by: hjk <hjk@qt.io>

2 files changed, 42 insertions, 0 deletions

diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp
index 483c99ed5f..4fdc94a202 100644
--- a/src/corelib/io/qprocess.cpp
+++ b/src/corelib/io/qprocess.cpp
@@ -2063,6 +2063,47 @@ void QProcess::start(OpenMode mode)
 }
 
 /*!
+    \since 6.0
+
+    Starts the command \a command in a new process.
+    The OpenMode is set to \a mode.
+
+    \a command is a single string of text containing both the program name
+    and its arguments. The arguments are separated by one or more spaces.
+    For example:
+
+    \snippet code/src_corelib_io_qprocess.cpp 5
+
+    Arguments containing spaces must be quoted to be correctly supplied to
+    the new process. For example:
+
+    \snippet code/src_corelib_io_qprocess.cpp 6
+
+    Literal quotes in the \a command string are represented by triple quotes.
+    For example:
+
+    \snippet code/src_corelib_io_qprocess.cpp 7
+
+    After the \a command string has been split and unquoted, this function
+    behaves like start().
+
+    On operating systems where the system API for passing command line
+    arguments to a subprocess natively uses a single string (Windows), one can
+    conceive command lines which cannot be passed via QProcess's portable
+    list-based API. In these rare cases you need to use setProgram() and
+    setNativeArguments() instead of this function.
+
+    \sa splitCommand()
+    \sa start()
+ */
+void QProcess::startCommand(const QString &command, OpenMode mode)
+{
+    QStringList args = splitCommand(command);
+    const QString program = args.takeFirst();
+    start(program, args, mode);
+}
+
+/*!
     \since 5.10
 
     Starts the program set by setProgram() with arguments set by setArguments()
diff --git a/src/corelib/io/qprocess.h b/src/corelib/io/qprocess.h
index 77980e012c..541086e1b0 100644
--- a/src/corelib/io/qprocess.h
+++ b/src/corelib/io/qprocess.h
@@ -160,6 +160,7 @@ public:
 
     void start(const QString &program, const QStringList &arguments = {}, OpenMode mode = ReadWrite);
     void start(OpenMode mode = ReadWrite);
+    void startCommand(const QString &command, OpenMode mode = ReadWrite);
     bool startDetached(qint64 *pid = nullptr);
     bool open(OpenMode mode = ReadWrite) override;