![]() |
![]() |
![]() |
GNOME Data Access 4.0 manual | ![]() |
---|---|---|---|---|
#include <sql-parser/gda-sql-parser.h> GdaSqlParser; enum GdaSqlParserMode; GdaSqlParser* gda_sql_parser_new (void); GdaStatement* gda_sql_parser_parse_string (GdaSqlParser *parser, const gchar *sql, const gchar **remain, GError **error); GdaBatch* gda_sql_parser_parse_string_as_batch (GdaSqlParser *parser, const gchar *sql, const gchar **remain, GError **error); GdaBatch* gda_sql_parser_parse_file_as_batch (GdaSqlParser *parser, const gchar *filename, GError **error); gboolean gda_sql_identifier_needs_quotes (const gchar *str); gchar* gda_sql_identifier_add_quotes (const gchar *str); gchar* gda_sql_identifier_remove_quotes (gchar *str);
"column-error" gint : Read "debug" gboolean : Write "line-error" gint : Read "mode" gint : Read / Write "tokenizer-flavour" gint : Read / Write
The GdaSqlParser is an object dedicated to creating GdaStatement and GdaBatch objects from SQL strings. The actual contents of the parsed statements is represented as GdaSqlStatement structures (which can be obtained from any GdaStatement through the "structure" property).
GdaSqlParser parsers can be created by calling gda_server_provider_create_parser() for a provider adapted SQL parser, or using gda_sql_parser_new() for a general purpose SQL parser.
The GdaSqlParser can either work in "parse" mode where it will try to parse the SQL string, or in "delimiter" mode where it will only attempt at delimiting SQL statements in a string which may contain several SQL statements (usually separated by a semi column). If operating in "parser" mode, and the parser can't correctly parse the string, then it will switch to the "delimiter" mode for the next statement in the string to parse (and create a GDA_SQL_STATEMENT_UNKNOWN statement).
The GdaSqlParser object parses and analyses SQL statements and reports the following statement types:
SELECT (and COMPOUND select), INSERT, UPDATE and DELETE SQL statements should be completely parsed.
Transaction related statements (corresponding to the BEGIN, COMMIT, ROLLBACK, SAVEPOINT, ROLLBACK SAVEPOINT and DELETE SAVEPOINT) are parsed and a minimalist structure is created to extract some information (that structure is not enough per-se to re-create the complete SQL statement).
Any other type of SQL statement (CREATE TABLE, ...) creates a GdaStatement of type GDA_SQL_STATEMENT_UNKNOW, and it only able to locate place holders (variables) and end of statement marks.
NOTE: Any SQL of a type which should be parsed which but which creates a GdaStatement of type GDA_SQL_STATEMENT_UNKNOWN (check with gda_statement_get_statement_type()) should be reported as a bug.
The GdaSqlParser object recognizes place holders (variables), which can later be queried and valued using gda_statement_get_parameters(). The folllowing syntax are recognized (other syntaxes might be recognized for specific database providers if the GdaSqlParser is created using gda_server_provider_create_parser() but for portability reasons it's better to avoid them):
##NAME[::TYPE[::NULL]]: for a variable named NAME with the optional type TYPE (which can be a GType name or a custom database type name), and with the optional "::NULL" to instruct that the variable can be NULL.
## /* name:NAME [type:TYPE] [nullok:[TRUE|FALSE]] [descr:DESCR] */ for a variable named NAME with the optional type TYPE (which can be a GType name or a custom database type name), with the optional "nullok" attribute and an optional description DESCR. Note that the NAME, TYPE and DESCR literals here must be quoted (simple or double quotes) if they include non alphanumeric characters, and that there must always be at least a space between the ## and the /* ... */.
Examples of correct place holders definitions are:
## /* name:"+0" type:gchararray */ ## /* name:'-5' type:string */ ## /*name:myvar type:gint descr:ToBeDefined nullok:FALSE*/ ## /*name:myvar type:gint descr:"A long description"*/ ##+0::gcharaccar ##-5::string
The GdaSqlParser object internally uses a LEMON generated parser (the same as the one used by SQLite).
typedef enum { GDA_SQL_PARSER_MODE_PARSE, GDA_SQL_PARSER_MODE_DELIMIT } GdaSqlParserMode;
GdaSqlParser* gda_sql_parser_new (void);
Creates a new GdaSqlParser object
Returns : | the new object |
GdaStatement* gda_sql_parser_parse_string (GdaSqlParser *parser, const gchar *sql, const gchar **remain, GError **error);
Parses sql and creates a GdaStatement statement from the first SQL statement contained in sql: if sql contains more than one statement, then the remaining part of the string is not parsed at all, and remain (if not NULL) will point at the first non parsed character.
parser : | a GdaSqlParser object |
sql : | the SQL string to parse |
remain : | location to store a pointer to remaining part of sql in case sql has multiple statement, or NULL |
error : | location to store error, or NULL |
Returns : | a new GdaStatement object, or NULL if an error occurred |
GdaBatch* gda_sql_parser_parse_string_as_batch (GdaSqlParser *parser, const gchar *sql, const gchar **remain, GError **error);
Parse sql and creates a GdaBatch object which contains all the GdaStatement objects created while parsing (one object per SQL statement). Empty statements (composed of spaces only) do not appear in the resulting object.
sql is parsed and GdaStatement objects are created as long as no error is found in sql. If an error is found at some point, then the parsing stops and remain may contain a non NULL pointer, error may be set, and NULL is returned.
if sql is NULL, then the returned GdaBatch object will contain no statement.
parser : | a GdaSqlParser object |
sql : | the SQL string to parse |
remain : | location to store a pointer to remaining part of sql in case an error occurred while parsing sql, or NULL |
error : | location to store error, or NULL |
Returns : | a new GdaBatch object, or NULL if an error occurred |
GdaBatch* gda_sql_parser_parse_file_as_batch (GdaSqlParser *parser, const gchar *filename, GError **error);
Parse filename's contents and creates a GdaBatch object which contains all the GdaStatement objects created while parsing (one object per SQL statement).
filename's contents are parsed and GdaStatement objects are created as long as no error is found. If an error is found at some point, then the parsing stops, error may be set and NULL is returned
if sql is NULL, then the returned GdaBatch object will contain no statement.
parser : | a GdaSqlParser object |
filename : | name of the file to parse |
error : | location to store error, or NULL |
Returns : | a new GdaBatch object, or NULL if an error occurred |
gboolean gda_sql_identifier_needs_quotes (const gchar *str);
Tells if str needs to be quoted before using it in an SQL statement. To actually add quotes, use gda_sql_identifier_add_quotes().
str : | an SQL identifier |
Returns : | TRUE if str needs some quotes |
gchar* gda_sql_identifier_add_quotes (const gchar *str);
Add double quotes around the str identifier. Use the gda_sql_identifier_needs_quotes() function to tell if an identifier needs to be quoted.
str : | an SQL identifier |
Returns : | a new string |
gchar* gda_sql_identifier_remove_quotes (gchar *str);
Prepares str to be compared: - if surrounded by double quotes, then just remove the quotes - otherwise convert to lower case
WARNING: str must NOT be a composed identifier (<part1>."<part2>" for example)
str : | a quoted string |
Returns : | str |
"column-error" gint : Read
Internal usage only.
Allowed values: >= 0
Default value: 0
"debug" gboolean : Write
Forces the parser to display somme debug information.
Default value: FALSE
"line-error" gint : Read
Internal usage only.
Allowed values: >= 0
Default value: 0
"mode" gint : Read / Write
Controls the parsing mode determining how the parser operates.
Allowed values: [0,1]
Default value: 0
"tokenizer-flavour" gint : Read / Write
Modifies the behaviour of the tokenizer, reserved for GdaServerProvider implementations
Allowed values: [0,4]
Default value: 0