/ 
SQL-Statement-1.27_01
River stage two • 22 direct dependents • 83 total dependents
/ SQL::Eval

NAME

SQL::Eval - Base for deriving evalution objects for SQL::Statement

SYNOPSIS

    require SQL::Statement;
    require SQL::Eval;

    # Create an SQL statement; use a concrete subclass of
    # SQL::Statement
    my $stmt = MyStatement->new("SELECT * FROM foo, bar",
			        SQL::Parser->new('Ansi'));

    # Get an eval object by calling open_tables; this
    # will call MyStatement::open_table
    my $eval = $stmt->open_tables($data);

    # Set parameter 0 to 'Van Gogh'
    $eval->param(0, 'Van Gogh');
    # Get parameter 2
    my $param = $eval->param(2);

    # Get the SQL::Eval::Table object referring the 'foo' table
    my $fooTable = $eval->table('foo');

DESCRIPTION

This module implements two classes that can be used for deriving concrete subclasses to evaluate SQL::Statement objects. The SQL::Eval object can be thought as an abstract state engine for executing SQL queries, the SQL::Eval::Table object can be considered a *very* table abstraction. It implements method for fetching or storing rows, retrieving column names and numbers and so on. See the test.pl script as an example for implementing a concrete subclass.

While reading on, keep in mind that these are abstract classes, you *must* implement at least some of the methods describe below. Even more, you need not derive from SQL::Eval or SQL::Eval::Table, you just need to implement the method interface.

All methods just throw a Perl exception in case of errors.

Method interface of SQL::Eval

new

Constructor; use it like this:

$eval = SQL::Eval->new(\%attr);

Blesses the hash ref \%attr into the SQL::Eval class (or a subclass).

param

Used for getting or setting input parameters, as in the SQL query

INSERT INTO foo VALUES (?, ?);

Example:

$eval->param(0, $val);        # Set parameter 0
$eval->param(0);              # Get parameter 0
params

Likewise used for getting or setting the complete array of input parameters. Example:

$eval->params($params);       # Set the array
$eval->params();              # Get the array
table

Returns or sets a table object. Example:

$eval->table('foo', $fooTable);  # Set the 'foo' table object
$eval->table('foo');             # Return the 'foo' table object
column

Return the value of a column with a given name; example:

$col = $eval->column('foo', 'id');  # Return the 'id' column of
                                    # the current row in the
                                    # 'foo' table

This is equivalent and just a shorthand for

$col = $eval->table('foo')->column('id');

Method interface of SQL::Eval::Table

new

Constructor; use it like this:

$eval = SQL::Eval::Table->new(\%attr);

Blesses the hash ref \%attr into the SQL::Eval::Table class (or a subclass).

The following attributes are used by SQL::Eval::Table:

col_names

Array reference containing the names of the columns in order they appear in the table. This attribute must be provided by the inheritent.

col_nums

Hash reference containing the column names as index and the column index as value. If this is omitted (not exists), it will be created from col_names.

capabilities

Hash reference containing additional capabilities.

row

Used to get the current row as an array ref. Do not mismatch getting the current row with the fetch_row method! In fact this method is valid only after a successfull $table->fetchrow(). Example:

$row = $table->row();
column

Get the column with a given name in the current row. Valid only after a successfull $table->fetchrow(). Example:

$col = $table->column($colName);
column_num

Return the number of the given column name. Column numbers start with 0. Returns undef, if a column name is not defined, so that you can well use this for verifying valid column names. Example:

$colNum = $table->column_num($colNum);
col_nums

Returns an hash ref of column names with the column name as index and the column index as value.

col_names

Returns an array ref of column names ordered by their index within the table.

capability

Returns a boolean value whether the table has the specified capability or not. This method might be overwritten by derived classes, but ensure that in that case the parent capability method is called when the derived class doesn't handle the requested capability.

Following capabilities are used (and requested) by SQL::Statement:

update_one_row

Tells if the table is able to update one single row. This capability is used for backward compatibility and might have (depending on table implementation several limitations). Please carefully study the documentation of the table or ask the author of the table, if this information isn't provided.

This capability is evaluated automatically on first request and must not be handled be derived classes.

update_specific_row

Tells if the table is able to update one single row, but keeps the original content of the row to update.

This capability is evaluated automatically on first request and must not be handled be derived classes.

update_current_row

Tells if the table is able to update the currently touched row. This capability requires the capability of inplace_update.

This capability is evaluated automatically on first request and must not be handled be derived classes.

rowwise_update

Tells if the table is able to do an row-wise update, means one of update_one_row, update_specific_row or update_current_row. The update_current_row is only evaluated, if the table has the capability inplace_update.

This capability is evaluated automatically on first request and must not be handled be derived classes.

inplace_update

Tells if an update of a row has side effects (capability is not available) or can be done without harming any other currently running task on the table.

Example: The table storage is using a hash on the PRIMARY KEY of the table. Real perl hashes don't care when an item is updated while the hash is traversed using each. SDBM_File 1.06 has a bug, which doesn't corrent the traversion pointer when an item is deleted.

SQL::Statement::RAM::Table recognize such situations and corrent the traversion pointer.

This might not be possible for all implementations which can update single rows.

This capability could be provided by a derived class only.

delete_one_row

This capability tells SQL::Statement whether the table can delete one single row by it's content or not.

This capability is evaluated automatically on first request and must not be handled be derived classes.

delete_current_row

This capability tells SQL::Statement whether a table can delete current traversed row or not. This capability requires the capability of inplace_delete.

This capability is evaluated automatically on first request and must not be handled be derived classes.

rowwise_delete

Tells if any row-wise delete operation is provided by the table. row-wise delete capabilities are delete_one_row and delete_current_row.

This capability is evaluated automatically on first request and must not be handled be derived classes.

inplace_delete

Tells if a deletion of a row has side effects (capability is not available) or can be done without harming any other currently running task on the table.

This capability could be provided by a derived class only.

insert_new_row

Tells if a table can easily insert a new row, without need of seeking and truncating. This capability is provided by defining the table class method insert_new_row.

This capability is evaluated automatically on first request and must not be handled be derived classes.

If the capabilities rowwise_update and insert_new_row are provided, the table primitive push_row is not needed anymore and may omitted.

The above methods are implemented by SQL::Eval::Table. The following methods aren't, so that they *must* be implemented by concrete subclassed. See the DBD::DBM::Table or DBD::CSV::Table for example.

drop

Drops the table. All resources allocated by the table must be released after $table-drop($data)>.

fetch_row

Fetches the next row from the table. Returns undef, if the last row was already fetched. The argument $data is for private use of the concrete subclass. Example:

$row = $table->fetch_row($data);

Note, that you may use

$row = $table->row();

for retrieving the same row again, until the next call of fetch_row.

SQL::Statement requires that the last fetched row is available again and again via $table-row()>.

push_row

Likewise for storing rows. Example:

$table->push_row($data, $row);
push_names

Used by the CREATE TABLE statement to set the column names of the new table. Receives an array ref of names. Example:

$table->push_names($data, $names);
seek

Similar to the seek method of a filehandle; used for setting the number of the next row being written. Example:

$table->seek($data, $whence, $rowNum);

Actually the current implementation is using only seek($data, 0, 0) (first row) and seek($data, 2, 0) (beyond last row, end of file).

truncate

Truncates a table after the current row. Example:

$table->truncate($data);

INTERNALS

The current implementation is quite simple: An SQL::Eval object is an hash ref with only two attributes. The params attribute is an array ref of parameters. The tables attribute is an hash ref of table names (keys) and table objects (values).

SQL::Eval::Table instances are implemented as hash refs. Used attributes are row (the array ref of the current row), col_nums (an hash ref of column names as keys and column numbers as values) and col_names, an array ref of column names with the column numbers as indexes.

MULTITHREADING

All methods are working with instance-local data only, thus the module is reentrant and thread safe, if you either don't share handles between threads or grant serialized use.

BUGS

Please report any bugs or feature requests to bug-sql-statement at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SQL-Statement. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc SQL::Eval
perldoc SQL::Statement

You can also look for information at:

AUTHOR AND COPYRIGHT

Written by Jochen Wiedmann and currently maintained by Jens Rehsack.

This module is Copyright (C) 1998 by

Jochen Wiedmann
Am Eisteich 9
72555 Metzingen
Germany

Email: joe@ispsoft.de
Phone: +49 7123 14887

and Copyright (C) 2009, 2010 by

Jens Rehsack < rehsackATcpan.org>

All rights reserved.

You may distribute this module under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

SEE ALSO

SQL::Statement(3)