SQL::Eval(3) User Contributed Perl Documentation SQL::Eval(3)NAMESQL::Eval - Base for deriving evaluation 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
subclasses to evaluate SQL::Statement objects. The SQL::Eval object can
be thought as an abstract state engine for executing SQL queries and
the SQL::Eval::Table object is a table abstraction. It implements
methods for fetching or storing rows, retrieving column names and
numbers and so on. See the "test.pl" script as an example for
implementing a subclass.
While reading on, keep in mind that these are abstract classes, you
*must* implement at least some of the methods described below. In
addition, you need not derive from SQL::Eval or SQL::Eval::Table, you
just need to implement the method interface.
All methods 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 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 to and 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 derived class.
col_nums Hash reference containing the column names as keys
and the column indexes as values. If this is
omitted (does not exist), 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 confuse
getting the current row with the fetch_row method! In fact this
method is valid only after a successful "$table->fetchrow()".
Example:
$row = $table->row();
column Get the column with a given name in the current row. Valid only
after a successful "$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 use this for verifying column names. Example:
$colNum = $table->column_num($colNum);
col_nums
Returns an hash ref of column names with the column names as
keys and the column indexes as the values.
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 overridden by derived
classes, but ensure that in that case the parent capability
method is called when the derived class does not handle the
requested capability.
The following capabilities are used (and requested) by
SQL::Statement:
update_one_row
Defines whether 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 is
not provided.
This capability is evaluated automatically on first
request and must not be handled by any derived
classes.
update_specific_row
Defines 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 by derived classes.
update_current_row
Defines 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 by derived classes.
rowwise_update
Defines if the table is able to do row-wise updates
which 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 "inplace_update" capability.
This capability is evaluated automatically on first
request and must not be handled by derived classes.
inplace_update
Defines 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 do not
care when an item is updated while the hash is
traversed using "each". "SDBM_File" 1.06 has a bug,
which does not adjust the traversal pointer when an
item is deleted.
"SQL::Statement::RAM::Table" recognizes such
situations and adjusts the traversal 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
Defines 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 by derived classes.
delete_current_row
Defines whether a table can delete the current
traversed row or not. This capability requires the
"inplace_delete" capability.
This capability is evaluated automatically on first
request and must not be handled by derived classes.
rowwise_delete
Defines 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 by derived classes.
inplace_delete
Defines if the 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 should be provided by a derived
class only.
insert_new_row
Defines if a table can easily insert a new row
without need to seek or truncate. 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 by derived classes.
If the capabilities rowwise_update and insert_new_row are
provided, the table primitive "push_row" is not required
anymore and may be omitted.
The above methods are implemented by SQL::Eval::Table. The following
methods are not, so that they *must* be implemented by the subclass.
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 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
As fetch_row except 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 only uses "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. Attributes
used 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
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SQL-Statement>. I will
be notified, and then you will 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:
· RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL-Statement
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL-Statement>
· AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/SQL-Statement
<http://annocpan.org/dist/SQL-Statement>
· CPAN Ratings
http://cpanratings.perl.org/s/SQL-Statement
<http://cpanratings.perl.org/s/SQL-Statement>
· Search CPAN
http://search.cpan.org/dist/SQL-Statement/
<http://search.cpan.org/dist/SQL-Statement/>
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 ALSOSQL::Statement(3)perl v5.14.1 2011-02-01 SQL::Eval(3)
