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>

4 files changed, 60 insertions, 3 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_io_qprocess.cpp b/src/corelib/doc/snippets/code/src_corelib_io_qprocess.cpp
index f6ea843ab6..3ec7791bd6 100644
--- a/src/corelib/doc/snippets/code/src_corelib_io_qprocess.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_io_qprocess.cpp
@@ -111,7 +111,7 @@ void runSandboxed(const QString &name, const QStringList &arguments)
 
 //! [5]
 QProcess process;
-process.start("del /s *.txt");
+process.startCommand("del /s *.txt");
 // same as process.start("del", QStringList() << "/s" << "*.txt");
 ...
 //! [5]
@@ -119,13 +119,13 @@ process.start("del /s *.txt");
 
 //! [6]
 QProcess process;
-process.start("dir \"My Documents\"");
+process.startCommand("dir \"My Documents\"");
 //! [6]
 
 
 //! [7]
 QProcess process;
-process.start("dir \"Epic 12\"\"\" Singles\"");
+process.startCommand("dir \"Epic 12\"\"\" Singles\"");
 //! [7]
 
 
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;
 
diff --git a/tests/auto/corelib/io/qprocess/tst_qprocess.cpp b/tests/auto/corelib/io/qprocess/tst_qprocess.cpp
index 317db0574c..023e254dc5 100644
--- a/tests/auto/corelib/io/qprocess/tst_qprocess.cpp
+++ b/tests/auto/corelib/io/qprocess/tst_qprocess.cpp
@@ -64,6 +64,7 @@ private slots:
     void constructing();
     void simpleStart();
     void setChildProcessModifier();
+    void startCommand();
     void startWithOpen();
     void startWithOldOpen();
     void execute();
@@ -303,6 +304,20 @@ void tst_QProcess::setChildProcessModifier()
 #endif
 }
 
+void tst_QProcess::startCommand()
+{
+    QProcess process;
+    process.startCommand("testProcessSpacesArgs/nospace foo \"b a r\" baz");
+    QVERIFY2(process.waitForStarted(), qPrintable(process.errorString()));
+    QVERIFY2(process.waitForFinished(), qPrintable(process.errorString()));
+    QCOMPARE(process.exitStatus(), QProcess::NormalExit);
+    QCOMPARE(process.exitCode(), 0);
+    QByteArray actual = process.readAll();
+    actual.remove(0, actual.indexOf('|') + 1);
+    QByteArray expected = "foo|b a r|baz";
+    QCOMPARE(actual, expected);
+}
+
 void tst_QProcess::startWithOpen()
 {
     QProcess p;