File indexing completed on 2021-12-21 14:36:55

0001 /*
0002     SPDX-FileCopyrightText: 2008 Rolf Eike Beer <kde@opensource.sf-tec.de>
0003     SPDX-License-Identifier: GPL-2.0-or-later
0004 */
0005 
0006 #ifndef KLINEBUFFEREDPROCESS_H
0007 #define KLINEBUFFEREDPROCESS_H
0008 
0009 #include <KProcess>
0010 
0011 #include "klinebufferedprocessprivate.h"
0012 
0013 class QByteArray;
0014 
0015 /**
0016  * Read output of a process split into lines
0017  *
0018  * This class reads the output of a process and splits it up into lines. This
0019  * is especially useful if you try to parse the output of a command line tool.
0020  *
0021  * \b Usage \n
0022  *
0023  * The class is created and set up like a KProcess. After this you can do
0024  * something like this:
0025  *
0026  * \code
0027  * connect(m_linebufprocess, &KLineBufferedProcess::lineReadyStandardOutput, this, &Class::dataStdout);
0028  * ...
0029  * void myobj::dataStdout()
0030  * {
0031  *   while (m_linebufprocess->hasLineStandardOutput()) {
0032  *     QByteArray line;
0033  *     m_linebufprocess->readLineStandardOutput(line);
0034  *     ...
0035  *   }
0036  * }
0037  * \endcode
0038  *
0039  * Never use the read functionality of KProcess with this class. This class
0040  * needs to read all data from the process into an internal buffer first. If
0041  * you try to use the read functions of the parent classes you would normally
0042  * get no output at all.
0043  *
0044  * The write functions of the parent classes are not effected. You can use
0045  * them exactly the same way as in KProcess.
0046  *
0047  * @author Rolf Eike Beer
0048  */
0049 class KLineBufferedProcess : public KProcess
0050 {
0051     Q_OBJECT
0052     friend class KLineBufferedProcessPrivate;
0053 
0054 public:
0055     /**
0056      * Constructor
0057      */
0058     explicit KLineBufferedProcess(QObject *parent = nullptr);
0059 
0060     /**
0061      * Destructor
0062      */
0063     ~KLineBufferedProcess() override;
0064 
0065     /**
0066      * Reads a line of text (excluding '\\n') from stdout.
0067      *
0068      * Use readLineStdout() in response to a lineReadyStdout() signal or
0069      * when hasLineStdout() returns true. You may use it multiple times if
0070      * more than one line of data is available. If no complete line is
0071      * available the content of line is undefined and the function returns
0072      * false.
0073      *
0074      * @param line is used to store the line that was read.
0075      * @return if data was read or not
0076      */
0077     bool readLineStandardOutput(QByteArray *line);
0078 
0079     /**
0080      * Reads a line of text (excluding '\\n') from stderr.
0081      *
0082      * Use readLineStderr() in response to a lineReadyStderr() signal or
0083      * when hasLineStderr() returns true. You may use it multiple times if
0084      * more than one line of data is available. If no complete line is
0085      * available the content of line is undefined and the function returns
0086      * false.
0087      *
0088      * @param line is used to store the line that was read.
0089      * @return if data was read or not
0090      */
0091     bool readLineStandardError(QByteArray *line);
0092 
0093     /**
0094      * Checks if a line is ready on stdout
0095      *
0096      * @return true if a complete line can be read
0097      */
0098     bool hasLineStandardOutput() const;
0099 
0100     /**
0101      * Checks if a line is ready on stdout
0102      *
0103      * @return true if a complete line can be read
0104      */
0105     bool hasLineStandardError() const;
0106 
0107 Q_SIGNALS:
0108     /**
0109      * Emitted when there is a line of data available from stdout when there was
0110      * previously none.
0111      * There may or may not be more than one line available for reading when this
0112      * signal is emitted.
0113      */
0114     void lineReadyStandardOutput();
0115 
0116     /**
0117      * Emitted when there is a line of data available from stderr when there was
0118      * previously none.
0119      * There may or may not be more than one line available for reading when this
0120      * signal is emitted.
0121      */
0122     void lineReadyStandardError();
0123 
0124 private:
0125     KLineBufferedProcessPrivate* const d;
0126 };
0127 
0128 #endif // KLINEBUFFEREDPROCESS_H