1 /* 2 * Copyright (C) 2008 - 2011 Vivien Malerba <malerba@gnome-db.org> 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; if not, write to the 16 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 17 * Boston, MA 02110-1301, USA. 18 */ 19 20 21 #ifndef __GDA_SQL_PARSER_H_ 22 #define __GDA_SQL_PARSER_H_ 23 24 #include <glib-object.h> 25 #include <libgda/gda-statement.h> 26 #include <libgda/gda-batch.h> 27 #include <sql-parser/gda-statement-struct.h> 28 #include <sql-parser/gda-statement-struct-util.h> 29 30 G_BEGIN_DECLS 31 32 #define GDA_TYPE_SQL_PARSER (gda_sql_parser_get_type()) 33 #define GDA_SQL_PARSER(obj) G_TYPE_CHECK_INSTANCE_CAST (obj, gda_sql_parser_get_type(), GdaSqlParser) 34 #define GDA_SQL_PARSER_CLASS(klass) G_TYPE_CHECK_CLASS_CAST (klass, gda_sql_parser_get_type (), GdaSqlParserClass) 35 #define GDA_IS_SQL_PARSER(obj) G_TYPE_CHECK_INSTANCE_TYPE (obj, gda_sql_parser_get_type ()) 36 37 /* error reporting */ 38 extern GQuark gda_sql_parser_error_quark (void); 39 #define GDA_SQL_PARSER_ERROR gda_sql_parser_error_quark () 40 41 typedef enum 42 { 43 GDA_SQL_PARSER_SYNTAX_ERROR, 44 GDA_SQL_PARSER_OVERFLOW_ERROR, 45 GDA_SQL_PARSER_EMPTY_SQL_ERROR 46 } GdaSqlParserError; 47 48 typedef enum { 49 GDA_SQL_PARSER_MODE_PARSE, 50 GDA_SQL_PARSER_MODE_DELIMIT 51 } GdaSqlParserMode; 52 53 typedef enum { 54 GDA_SQL_PARSER_FLAVOUR_STANDARD = 0, 55 GDA_SQL_PARSER_FLAVOUR_SQLITE = 1, 56 GDA_SQL_PARSER_FLAVOUR_MYSQL = 2, 57 GDA_SQL_PARSER_FLAVOUR_ORACLE = 3, 58 GDA_SQL_PARSER_FLAVOUR_POSTGRESQL = 4 59 } GdaSqlParserFlavour; 60 61 /* struct for the object's data */ 62 struct _GdaSqlParser 63 { 64 GObject object; 65 GdaSqlParserPrivate *priv; 66 }; 67 68 /* interface with the Lemon parser */ 69 typedef struct _GdaSqlParserIface 70 { 71 GdaSqlParser *parser; 72 GdaSqlStatement *parsed_statement; 73 74 /*< private >*/ 75 /* Padding for future expansion */ 76 gpointer _gda_reserved1; 77 gpointer _gda_reserved2; 78 } GdaSqlParserIface; 79 80 /* struct for the object's class */ 81 struct _GdaSqlParserClass 82 { 83 GObjectClass parent_class; 84 85 /* virtual methods and data for sub classed parsers */ 86 void *(*delim_alloc) (void *(*f) (size_t s)); 87 void (*delim_free) (void *d, void(*f) (void *d)); 88 void (*delim_trace) (void *d, char *s); 89 void (*delim_parse) (void *d, int i, GValue *v, GdaSqlParserIface *iface); 90 gint *delim_tokens_trans; 91 92 void *(*parser_alloc) (void *(*f)(size_t s)); 93 void (*parser_free) (void *p, void(*f)(void *p)); 94 void (*parser_trace) (void *p, char *s); 95 void (*parser_parse) (void *p, int i, GValue *v, GdaSqlParserIface *iface); 96 gint *parser_tokens_trans; 97 98 /*< private >*/ 99 /* Padding for future expansion */ 100 void (*_gda_reserved1) (void); 101 void (*_gda_reserved2) (void); 102 void (*_gda_reserved3) (void); 103 void (*_gda_reserved4) (void); 104 }; 105 106 /** 107 * SECTION:gda-sql-parser 108 * @short_description: SQL parser 109 * @title: GdaSqlParser 110 * @stability: Stable 111 * @see_also: #GdaSqlBuilder, #GdaSqlStatement and #GdaStatement 112 * 113 * The #GdaSqlParser is an object dedicated to creating #GdaStatement and #GdaBatch objects from SQL strings. The actual contents 114 * of the parsed statements is represented as #GdaSqlStatement structures (which can be obtained from any #GdaStatement through the 115 * "structure" property). 116 * 117 * #GdaSqlParser parsers can be created by calling gda_server_provider_create_parser() for a provider adapted SQL parser, or using 118 * gda_sql_parser_new() for a general purpose SQL parser. 119 * 120 * The #GdaSqlParser can either work in "parse" mode where it will try to parse the SQL string, or in "delimiter" mode where it will 121 * only attempt at delimiting SQL statements in a string which may contain several SQL statements (usually separated by a semi column). 122 * If operating in "parser" mode, and the parser can't correctly parse the string, then it will switch to the "delimiter" mode 123 * for the next statement in the string to parse (and create a GDA_SQL_STATEMENT_UNKNOWN statement). 124 * 125 * The #GdaSqlParser object parses and analyzes SQL statements and reports the following statement types: 126 * <itemizedlist> 127 * <listitem><para>SELECT (and COMPOUND select), 128 * INSERT, UPDATE and DELETE SQL statements should be completely parsed. 129 * </para></listitem> 130 * <listitem><para>Transaction related statements (corresponding to the BEGIN, COMMIT, ROLLBACK, 131 * SAVEPOINT, ROLLBACK SAVEPOINT and DELETE SAVEPOINT) are parsed and a minimalist structure is created to 132 * extract some information (that structure is not enough per-se to re-create the complete SQL statement). 133 * </para></listitem> 134 * <listitem><para>Any other type of SQL statement (CREATE TABLE, ...) creates a #GdaStatement of type 135 * GDA_SQL_STATEMENT_UNKNOWN, and it only able to locate place holders (variables) and end of statement 136 * marks.</para></listitem> 137 * </itemizedlist> 138 * 139 * NOTE: Any SQL of a type which should be parsed which but which creates a #GdaStatement of type GDA_SQL_STATEMENT_UNKNOWN 140 * (check with gda_statement_get_statement_type()) should be reported as a bug. 141 * 142 * The #GdaSqlParser object recognizes place holders (variables), which can later be queried and valued using 143 * gda_statement_get_parameters(). The following syntax are recognized (other syntaxes might be 144 * recognized for specific database providers if the #GdaSqlParser is created using gda_server_provider_create_parser() 145 * but for portability reasons it's better to avoid them): 146 * <itemizedlist> 147 * <listitem><para><programlisting>##NAME[::TYPE[::NULL]]]</programlisting>: 148 * for a variable named NAME with the optional type TYPE (which can be a GType 149 * name or a custom database type name), and with the optional "::NULL" to instruct that the variable can 150 * be NULL. 151 * </para></listitem> 152 * <listitem><para> 153 * <programlisting>## /* name:NAME [type:TYPE] [nullok:[TRUE|FALSE]] [descr:DESCR] */</programlisting> 154 * for a variable named NAME with the optional type TYPE (which can be a GType 155 * name or a custom database type name), with the optional "nullok" attribute and an optional 156 * description DESCR. Note that the NAME, TYPE and DESCR literals here must be quoted (simple or double quotes) if 157 * they include non alphanumeric characters, and that there must always be at least a space between the 158 * <![CDATA[##]]> and the opening and closing comments (C style). 159 * </para></listitem> 160 * </itemizedlist> 161 * Note that the type string must be a type recognized by the 162 * <link linkend="gda-g-type-from-string">gda_g_type_from_string()</link> function (all valid GType names 163 * plus a few synonyms). Examples of correct place holders definitions are: 164 * <programlisting> 165 *## /* name:"+0" type:gchararray */ 166 *## /* name:'-5' type:string */ 167 *## /*name:myvar type:gint descr:ToBeDefined nullok:FALSE*/ 168 *## /*name:myvar type:int descr:"A long description"*/ 169 *##+0::gchararray 170 *##-5::timestamp 171 *</programlisting> 172 * 173 * Also note that variables should not be used when an SQL identifier is expected. For example the following 174 * examples <emphasis>should be avoided</emphasis> because they may not work properly (depending on the database being used): 175 *<programlisting> 176 *SELECT * FROM ##tablename::string; 177 *DELETE FROM mytable WHERE ##tcol::string = 5; 178 *ALTER GROUP mygroup ADD USER ##name::gchararray; 179 *</programlisting> 180 * 181 * The #GdaSqlParser object internally uses a LEMON generated parser (the same as the one used by SQLite). 182 * 183 * The #GdaSqlParser object implements its own locking mechanism so it is thread-safe. 184 */ 185 186 GType gda_sql_parser_get_type (void) G_GNUC_CONST; 187 GdaSqlParser *gda_sql_parser_new (void); 188 189 GdaStatement *gda_sql_parser_parse_string (GdaSqlParser *parser, 190 const gchar *sql, const gchar **remain, 191 GError **error); 192 GdaBatch *gda_sql_parser_parse_string_as_batch (GdaSqlParser *parser, 193 const gchar *sql, const gchar **remain, 194 GError **error); 195 GdaBatch *gda_sql_parser_parse_file_as_batch (GdaSqlParser *parser, 196 const gchar *filename, GError **error); 197 198 /* private API */ 199 void gda_sql_parser_set_syntax_error (GdaSqlParser *parser); 200 void gda_sql_parser_set_overflow_error (GdaSqlParser *parser); 201 202 G_END_DECLS 203 204 #endif 205