SQL::Eval(3pm)

1SQL::Eval(3)          User Contributed Perl Documentation         SQL::Eval(3)
2
3
4

NAME

6       SQL::Eval - Base for deriving evaluation objects for SQL::Statement
7

SYNOPSIS

9           require SQL::Statement;
10           require SQL::Eval;
11
12           # Create an SQL statement; use a concrete subclass of
13           # SQL::Statement
14           my $stmt = MyStatement->new("SELECT * FROM foo, bar",
15                                       SQL::Parser->new('Ansi'));
16
17           # Get an eval object by calling open_tables; this
18           # will call MyStatement::open_table
19           my $eval = $stmt->open_tables($data);
20
21           # Set parameter 0 to 'Van Gogh'
22           $eval->param(0, 'Van Gogh');
23           # Get parameter 2
24           my $param = $eval->param(2);
25
26           # Get the SQL::Eval::Table object referring the 'foo' table
27           my $fooTable = $eval->table('foo');
28

DESCRIPTION

30       This module implements two classes that can be used for deriving
31       subclasses to evaluate SQL::Statement objects. The SQL::Eval object can
32       be thought as an abstract state engine for executing SQL queries and
33       the SQL::Eval::Table object is a table abstraction. It implements
34       methods for fetching or storing rows, retrieving column names and
35       numbers and so on.  See the "test.pl" script as an example for
36       implementing a subclass.
37
38       While reading on, keep in mind that these are abstract classes, you
39       *must* implement at least some of the methods described below.  In
40       addition, you need not derive from SQL::Eval or SQL::Eval::Table, you
41       just need to implement the method interface.
42
43       All methods throw a Perl exception in case of errors.
44
45   Method interface of SQL::Eval
46       new     Constructor; use it like this:
47
48                   $eval = SQL::Eval->new(\%attr);
49
50               Blesses the hash ref \%attr into the SQL::Eval class (or a
51               subclass).
52
53       param   Used for getting or setting input parameters, as in the SQL
54               query
55
56                   INSERT INTO foo VALUES (?, ?);
57
58               Example:
59
60                   $eval->param(0, $val);        # Set parameter 0
61                   $eval->param(0);              # Get parameter 0
62
63       params  Used for getting or setting the complete array of input
64               parameters. Example:
65
66                   $eval->params($params);       # Set the array
67                   $eval->params();              # Get the array
68
69       table   Returns or sets a table object. Example:
70
71                   $eval->table('foo', $fooTable);  # Set the 'foo' table object
72                   $eval->table('foo');             # Return the 'foo' table object
73
74       column  Return the value of a column with a given name; example:
75
76                   $col = $eval->column('foo', 'id');  # Return the 'id' column of
77                                                       # the current row in the
78                                                       # 'foo' table
79
80               This is equivalent to and a shorthand for
81
82                   $col = $eval->table('foo')->column('id');
83
84   Method interface of SQL::Eval::Table
85       new     Constructor; use it like this:
86
87                   $eval = SQL::Eval::Table->new(\%attr);
88
89               Blesses the hash ref \%attr into the SQL::Eval::Table class (or
90               a subclass).
91
92               The following attributes are used by "SQL::Eval::Table":
93
94               col_names   Array reference containing the names of the columns
95                           in order they appear in the table. This attribute
96                           must be provided by the derived class.
97
98               col_nums    Hash reference containing the column names as keys
99                           and the column indexes as values. If this is
100                           omitted (does not exist), it will be created from
101                           "col_names".
102
103               capabilities
104                           Hash reference containing additional capabilities.
105
106       row     Used to get the current row as an array ref. Do not confuse
107               getting the current row with the fetch_row method! In fact this
108               method is valid only after a successful "$table->fetchrow()".
109               Example:
110
111                   $row = $table->row();
112
113       column  Get the column with a given name in the current row. Valid only
114               after a successful "$table->fetchrow()". Example:
115
116                   $col = $table->column($colName);
117
118       column_num
119               Return the number of the given column name. Column numbers
120               start with 0. Returns undef, if a column name is not defined,
121               so that you can use this for verifying column names. Example:
122
123                   $colNum = $table->column_num($colNum);
124
125       col_nums
126               Returns an hash ref of column names with the column names as
127               keys and the column indexes as the values.
128
129       col_names
130               Returns an array ref of column names ordered by their index
131               within the table.
132
133       capability
134               Returns a boolean value whether the table has the specified
135               capability or not. This method might be overridden by derived
136               classes, but ensure that in that case the parent capability
137               method is called when the derived class does not handle the
138               requested capability.
139
140               The following capabilities are used (and requested) by
141               SQL::Statement:
142
143               update_one_row
144                           Defines whether the table is able to update one
145                           single row. This capability is used for backward
146                           compatibility and might have (depending on table
147                           implementation) several limitations. Please
148                           carefully study the documentation of the table or
149                           ask the author of the table, if this information is
150                           not provided.
151
152                           This capability is evaluated automatically on first
153                           request and must not be handled by any derived
154                           classes.
155
156               update_specific_row
157                           Defines if the table is able to update one single
158                           row, but keeps the original content of the row to
159                           update.
160
161                           This capability is evaluated automatically on first
162                           request and must not be handled by derived classes.
163
164               update_current_row
165                           Defines if the table is able to update the
166                           currently touched row. This capability requires the
167                           capability of "inplace_update".
168
169                           This capability is evaluated automatically on first
170                           request and must not be handled by derived classes.
171
172               rowwise_update
173                           Defines if the table is able to do row-wise updates
174                           which means one of "update_one_row",
175                           "update_specific_row" or "update_current_row".  The
176                           "update_current_row" is only evaluated if the table
177                           has the "inplace_update" capability.
178
179                           This capability is evaluated automatically on first
180                           request and must not be handled by derived classes.
181
182               inplace_update
183                           Defines if an update of a row has side effects
184                           (capability is not available) or can be done
185                           without harming any other currently running task on
186                           the table.
187
188                           Example: The table storage is using a hash on the
189                           "PRIMARY KEY" of the table. Real perl hashes do not
190                           care when an item is updated while the hash is
191                           traversed using "each". "SDBM_File" 1.06 has a bug,
192                           which does not adjust the traversal pointer when an
193                           item is deleted.
194
195                           "SQL::Statement::RAM::Table" recognizes such
196                           situations and adjusts the traversal pointer.
197
198                           This might not be possible for all implementations
199                           which can update single rows.
200
201                           This capability could be provided by a derived
202                           class only.
203
204               delete_one_row
205                           Defines whether the table can delete one single row
206                           by it's content or not.
207
208                           This capability is evaluated automatically on first
209                           request and must not be handled by derived classes.
210
211               delete_current_row
212                           Defines whether a table can delete the current
213                           traversed row or not. This capability requires the
214                           "inplace_delete" capability.
215
216                           This capability is evaluated automatically on first
217                           request and must not be handled by derived classes.
218
219               rowwise_delete
220                           Defines if any row-wise delete operation is
221                           provided by the table. "row-wise" delete
222                           capabilities are "delete_one_row" and
223                           "delete_current_row".
224
225                           This capability is evaluated automatically on first
226                           request and must not be handled by derived classes.
227
228               inplace_delete
229                           Defines if the deletion of a row has side effects
230                           (capability is not available) or can be done
231                           without harming any other currently running task on
232                           the table.
233
234                           This capability should be provided by a derived
235                           class only.
236
237               insert_new_row
238                           Defines if a table can easily insert a new row
239                           without need to seek or truncate. This capability
240                           is provided by defining the table class method
241                           "insert_new_row".
242
243                           This capability is evaluated automatically on first
244                           request and must not be handled by derived classes.
245
246               If the capabilities rowwise_update and insert_new_row are
247               provided, the table primitive "push_row" is not required
248               anymore and may be omitted.
249
250       The above methods are implemented by SQL::Eval::Table. The following
251       methods are not, so that they *must* be implemented by the subclass.
252       See the "DBD::DBM::Table" or "DBD::CSV::Table" for example.
253
254       drop    Drops the table. All resources allocated by the table must be
255               released after "$table-"drop($data)>.
256
257       fetch_row
258               Fetches the next row from the table. Returns "undef", if the
259               last row was already fetched. The argument $data is for private
260               use of the subclass. Example:
261
262                   $row = $table->fetch_row($data);
263
264               Note, that you may use
265
266                   $row = $table->row();
267
268               for retrieving the same row again, until the next call of
269               "fetch_row".
270
271               "SQL::Statement" requires that the last fetched row is
272               available again and again via "$table-"row()>.
273
274       push_row
275               As fetch_row except for storing rows. Example:
276
277                   $table->push_row($data, $row);
278
279       push_names
280               Used by the CREATE TABLE statement to set the column names of
281               the new table. Receives an array ref of names. Example:
282
283                   $table->push_names($data, $names);
284
285       seek    Similar to the seek method of a filehandle; used for setting
286               the number of the next row being written. Example:
287
288                   $table->seek($data, $whence, $rowNum);
289
290               Actually the current implementation only uses "seek($data, 0,
291               0)" (first row) and "seek($data, 2, 0)" (beyond last row, end
292               of file).
293
294       truncate
295               Truncates a table after the current row. Example:
296
297                   $table->truncate($data);
298

INTERNALS

300       The current implementation is quite simple: An SQL::Eval object is an
301       hash ref with only two attributes. The "params" attribute is an array
302       ref of parameters. The "tables" attribute is an hash ref of table names
303       (keys) and table objects (values).
304
305       SQL::Eval::Table instances are implemented as hash refs. Attributes
306       used are "row" (the array ref of the current row), "col_nums" (an hash
307       ref of column names as keys and column numbers as values) and
308       "col_names", an array ref of column names with the column numbers as
309       indexes.
310

MULTITHREADING

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

BUGS

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

SUPPORT

325       You can find documentation for this module with the perldoc command.
326
327           perldoc SQL::Eval
328           perldoc SQL::Statement
329
330       You can also look for information at:
331
332       ·   RT: CPAN's request tracker
333
334           http://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL-Statement
335           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL-Statement>
336
337       ·   AnnoCPAN: Annotated CPAN documentation
338
339           http://annocpan.org/dist/SQL-Statement
340           <http://annocpan.org/dist/SQL-Statement>
341
342       ·   CPAN Ratings
343
344           http://cpanratings.perl.org/s/SQL-Statement
345           <http://cpanratings.perl.org/s/SQL-Statement>
346
347       ·   Search CPAN
348
349           http://search.cpan.org/dist/SQL-Statement/
350           <http://search.cpan.org/dist/SQL-Statement/>
351

AUTHOR AND COPYRIGHT

353       Written by Jochen Wiedmann and currently maintained by Jens Rehsack.
354
355       This module is Copyright (C) 1998 by
356
357           Jochen Wiedmann
358           Am Eisteich 9
359           72555 Metzingen
360           Germany
361
362           Email: joe@ispsoft.de
363           Phone: +49 7123 14887
364
365       and Copyright (C) 2009, 2010 by
366
367            Jens Rehsack < rehsackATcpan.org>
368
369       All rights reserved.
370
371       You may distribute this module under the terms of either the GNU
372       General Public License or the Artistic License, as specified in the
373       Perl README file.
374