NAME

DBIx::MyParse::Query - Access the parse tree produced by DBIx::MyParse

SYNOPSIS

        use DBIx::MyParse;
        my $parser = DBIx::MyParse->new();
        my $query = $parser->parse("SELECT 1");
        print $query->getCommand();

DESCRIPTION

This module attempts to provide structured access to the parse tree that is produced by MySQL's SQL parser. Since the parser itself is not exactly perfectly structured, please make sure you read this entire document before attempting to make sense of DBIx::MyParse::Query objects.

METHODS

my $string = $query->getCommand();

Returns, as string, the name of SQL command that was parsed. All possible values can be found in enum enum_sql_command in sql/sql_lex.h from the MySQL source.

The commands that are currently supported (that is, a parse tree is created for them) are as follows:

        "SQLCOM_SELECT",
        "SQLCOM_INSERT",        "SQLCOM_INSERT_SELECT"
        "SQLCOM_REPLACE",       "SQLCOM_REPLACE_SELECT"
        "SQLCOM_UPDATE",        "SQLCOM_UPDATE_MULTI"
        "SQLCOM_DELETE",        "SQLCOM_DELETE_MULTI"

Please note that the returned value is a string, and not an integer. Please read the section COMMANDS below for notes on individual commands

my $string_array_ref = $query->getOptions();

Returns a reference to an array containing, as strings, the various options specified for the query, such as HIGH_PRIORITY, LOW_PRIORITY, DELAYED, IGNORE and the like. Some of the options are not returned with the names you expect, but rather using their internal MySQL names. [[FIXME]]

ERROR HANDLING

If there has been a parse error, $query->getCommand() eq "SQLCOM_ERROR". From there on, you can:

my $string = $query->getError()

Returns the error code as string, in English, as defined in include/mysql_error.h.

my $integer = $query->getErrno()

Returns the error code as integer

my $string = $query->getErrstr()

Returns the entire error message, in the language of the MySQL installation. This is the same text the mysql client will print for an identical error.

Since we currently only do parsing and no access checks or check if the referenced tables and fields exist, etc. getError() will most likely always return "ER_PARSE_ERROR".

COMMANDS

"SQLCOM_SELECT"

my $array_ref = $query->getSelectItems()

Returns a reference to the array of the items the SELECT query will return, each being a Item object.

my $array_ref = $query->getTables()

Rreturns a reference to the array of tables specified in the query. Each table is also an Item object for which $item->getType() eq "TABLE_ITEM" which contains information on the Join type, join conditions, indexes, etc. See DBIx::MyParse::Item for information on how to extract the individual properties.

my $item = $query->getWhere()

Returns an Item object that is the root of the tree containing the WHERE conditions.

my $item = $query->getHaving()

Operates the same way as getWhere() but for the HAVING clause.

my $array_ref = $query->getGroup()

Returns a reference to an array containing one Item object for each GROUP BY condition.

my $array_ref = $query->getOrder()

Returns a reference to an array containing the individual Items from the ORDER BY clause.

my $array_ref = $query->getLimit()

Returns a reference to a two-item array containing the two parts of the LIMIT clause as DBIx::MyParse::Item objects.

"SQLCOM_UPDATE" and "SQLCOM_UPDATE_MULTI"

my $array_ref = $query->getUpdateFields()

Returns a reference to an array containing the fields that the query would update.

my $array_ref = $query->getUpdateValues()

Returns a reference to an array containing the values that will be assigned to the fields being updated.

getTables(), getWhere(), getOrder() and getLimit() can also be used for update queries.

getTables() will return a reference to a one-item array for SQLCOM_UPDATE. Multiple-item array will be returned for SQLCOM_UPDATE_MULTI, since multiple tables will be involved.

"SQLCOM_DELETE" and "SQLCOM_DELETE_MULTI"

For a single-table delete, $query->getCommand() eq "SQLCOM_DELETE"

my $array_ref = $query->getDeleteTables()

Will return a reference to an array containing the table(s) we are deleting records from.

my $array_ref = $query->getTables()

For a multiple-table delete, getTables() will return the tables listed in the FROM clause, which are used to provide referential integrity.

getWhere(), getOrder() and getLimit() can also be used.

"SQLCOM_INSERT", "SQLCOM_INSERT_SELECT", "SQLCOM_REPLACE" and "SQLCOM_REPLACE_SELECT"

my $array_ref = $query->getInsertFields()

Returns a list of the fields you are inserting to.

my $array_ref = $query->getInsertValues()

For "SQLCOM_INSERT" and "SQLCOM_REPLACE", getInsertValues() will return a reference to an array, containing one sub-array for each row being inserted or replaced (even if there is only one row).

For "SQLCOM_INSERT_SELECT" and "SQLCOM_REPLACE_SELECT", getSelectItems(), getTables(), getWhere() and the other SELECT-related properties will describe the SELECT query used to provide values for the INSERT.

If ON DUPLICATE KEY UPDATE is also specified, then getUpdateFields() and getUpdateValues() can also be used.