File indexing completed on 2024-06-09 12:37:26

0001 /* This file is part of the KDE project
0002    Copyright (C) 2003 Lucijan Busch <lucijan@kde.org>
0003    Copyright (C) 2004-2018 Jarosław Staniek <staniek@kde.org>
0004 
0005    This library is free software; you can redistribute it and/or
0006    modify it under the terms of the GNU Library General Public
0007    License as published by the Free Software Foundation; either
0008    version 2 of the License, or (at your option) any later version.
0009 
0010    This library is distributed in the hope that it will be useful,
0011    but WITHOUT ANY WARRANTY; without even the implied warranty of
0012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0013    Library General Public License for more details.
0014 
0015    You should have received a copy of the GNU Library General Public License
0016    along with this library; see the file COPYING.LIB.  If not, write to
0017    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0018  * Boston, MA 02110-1301, USA.
0019 */
0020 
0021 #ifndef KDB_PARSER_H
0022 #define KDB_PARSER_H
0023 
0024 #include "kdb_export.h"
0025 
0026 #include <QString>
0027 #include <QCoreApplication>
0028 
0029 class KDbConnection;
0030 class KDbQuerySchema;
0031 class KDbTableSchema;
0032 class KDbEscapedString;
0033 
0034 /**
0035  * Provides detailed error description about KDbParser.
0036  *
0037  * @todo Make it explicitly shared using SDC
0038  * @todo change type to enum
0039  */
0040 class KDB_EXPORT KDbParserError
0041 {
0042 public:
0043     /**
0044      * Empty constructor.
0045      */
0046     KDbParserError();
0047 
0048     /**
0049      * Constructor.
0050      *
0051      * @param type The error type.
0052      * @param message A description of the error.
0053      * @param token Token where the Error happend.
0054      * @param position The position where the error happened.
0055      */
0056     KDbParserError(const QString &type, const QString &message, const QByteArray &token, int position);
0057 
0058     /**
0059      * Copy constructor.
0060      */
0061     KDbParserError(const KDbParserError &other);
0062 
0063     ~KDbParserError();
0064 
0065     KDbParserError& operator=(const KDbParserError &other);
0066 
0067     bool operator==(const KDbParserError &other) const;
0068 
0069     inline bool operator!=(const KDbParserError &other) const { return !operator==(other); }
0070 
0071     /**
0072      * @return the error type.
0073      */
0074     QString type() const;
0075 
0076     /**
0077      * @return translated error message.
0078      */
0079     QString message() const;
0080 
0081     /**
0082      * @return (character) position where the error happened.
0083      */
0084     int position() const;
0085 
0086 private:
0087     class Private;
0088     Private * const d;
0089 };
0090 
0091 class KDbParserPrivate; //!< @internal
0092 
0093 /**
0094  * A parser tool for SQL statements.
0095  *
0096  * The KDbParser class offers functionality of a SQL parser for database-backend-independent
0097  * KDbSQL dialect. Schema objects such as KDbQuerySchema that are created after successful parsing
0098  * can be then used for running the queries on actual data or used for further modification.
0099  *
0100  * @todo Add examples
0101  * @todo Support more types than the SELECT
0102  */
0103 class KDB_EXPORT KDbParser
0104 {
0105     Q_DECLARE_TR_FUNCTIONS(KDbParser)
0106 public:
0107 
0108     /**
0109      * The type of the statement.
0110      */
0111     enum StatementType {
0112         NoType,      //!< No statement type specified or detected
0113         Select,      //!< Query-statement
0114         CreateTable, //!< Create a new table
0115         AlterTable,  //!< Alter schema of an existing table
0116         Insert,      //!< Insert new records
0117         Update,      //!< Update existing records
0118         Delete       //!< Delete existing records
0119     };
0120 
0121     /**
0122      * Constructs an new parser object.
0123      * @a connection is used to obtain context, for example wildcards "T.*" resolution
0124      * is possible only if information about table T is available.
0125      */
0126     explicit KDbParser(KDbConnection *connection);
0127 
0128     ~KDbParser();
0129 
0130     /**
0131      * @brief Clears the parser's status and runs the parsing for a raw SQL statement
0132      *
0133      * If parsing of @a sql results in a proper query and @a query is present, it will be set to
0134      * representation of the parsed query.
0135      * @since 3.1
0136      */
0137     bool parse(const KDbEscapedString &sql, KDbQuerySchema *query = nullptr);
0138 
0139     /**
0140      * Reset the parser's status (table, query, error, statement, statement type).
0141      */
0142     void reset();
0143 
0144     /**
0145      * @return the resulting statement type
0146      * NoType is returned if parsing failed or it has not been yet performed or reset() was called.
0147      */
0148     StatementType statementType() const;
0149 
0150     /**
0151      * @return the resulting statement type as string. It is not translated.
0152      */
0153     QString statementTypeString() const;
0154 
0155     /**
0156      * @return a pointer to a query schema if 'CREATE TABLE ...' statement was parsed
0157      * or @c nullptr for any other statements or on error.
0158      * @note A proper table schema is returned only once for each successful parse() call,
0159      * and the object is owned by the caller. In all other cases @c nullptr is returned.
0160      *
0161      * @todo Implement this
0162      */
0163     Q_REQUIRED_RESULT KDbTableSchema *table();
0164 
0165     /**
0166      * @return a pointer to a new query schema created by parsing 'SELECT ...' statement
0167      * or @c nullptr for any other statements or on error.
0168      * If existing query was supplied to parse() @c nullptr is returned.
0169      * @note A proper query schema is returned only once for each successful parse() call,
0170      * and the object is owned by the caller. In all other cases nullptr is returned.
0171      */
0172     Q_REQUIRED_RESULT KDbQuerySchema *query();
0173 
0174     /**
0175      * @return a pointer to the used database connection or @c nullptr if it was not set.
0176      */
0177     KDbConnection *connection();
0178 
0179     //! @overload
0180     //! @since 3.1
0181     const KDbConnection *connection() const;
0182 
0183     /**
0184      * @return detailed information about last error.
0185      * If no error occurred KDbParserError::type() is empty.
0186      */
0187     KDbParserError error() const;
0188 
0189     /**
0190      * @return the statement passed on the most recent call of parse().
0191      */
0192     KDbEscapedString statement() const;
0193 
0194 private:
0195     void init();
0196 
0197     friend class KDbParserPrivate;
0198     KDbParserPrivate * const d; //!< @internal d-pointer class.
0199     Q_DISABLE_COPY(KDbParser)
0200 };
0201 
0202 //! Sends information about parser error @a error to debug output @a dbg.
0203 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbParserError& error);
0204 
0205 #endif