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       _gen_access_fastpath
85               Return a subroutine reference for fast accessing columns for
86               read-only access. This routine simply returns the
87               "_gen_access_fastpath" of the referenced table.
88
89   Method interface of SQL::Eval::Table
90       new     Constructor; use it like this:
91
92                   $eval = SQL::Eval::Table->new(\%attr);
93
94               Blesses the hash ref \%attr into the SQL::Eval::Table class (or
95               a subclass).
96
97               The following attributes are used by "SQL::Eval::Table":
98
99               col_names   Array reference containing the names of the columns
100                           in order they appear in the table. This attribute
101                           must be provided by the derived class.
102
103               col_nums    Hash reference containing the column names as keys
104                           and the column indexes as values. If this is
105                           omitted (does not exist), it will be created from
106                           "col_names".
107
108               capabilities
109                           Hash reference containing additional capabilities.
110
111               _gen_access_fastpath
112                           Return a subroutine reference for fast accessing
113                           columns for read-only access. When the instantiated
114                           object doesn't provide own methods for "column" and
115                           "column_num" a subroutine reference is returned
116                           which directly access the internal data structures.
117                           For all other cases a subroutine directly calling
118                           "$self->column($_[0])" is returned.
119
120       row     Used to get the current row as an array ref. Do not confuse
121               getting the current row with the fetch_row method! In fact this
122               method is valid only after a successful "$table->fetchrow()".
123               Example:
124
125                   $row = $table->row();
126
127       column  Get the column with a given name in the current row. Valid only
128               after a successful "$table->fetchrow()". Example:
129
130                   $col = $table->column($colName);
131
132       column_num
133               Return the number of the given column name. Column numbers
134               start with 0. Returns undef, if a column name is not defined,
135               so that you can use this for verifying column names. Example:
136
137                   $colNum = $table->column_num($colNum);
138
139       col_nums
140               Returns an hash ref of column names with the column names as
141               keys and the column indexes as the values.
142
143       col_names
144               Returns an array ref of column names ordered by their index
145               within the table.
146
147       capability
148               Returns a boolean value whether the table has the specified
149               capability or not. This method might be overridden by derived
150               classes, but ensure that in that case the parent capability
151               method is called when the derived class does not handle the
152               requested capability.
153
154               The following capabilities are used (and requested) by
155               SQL::Statement:
156
157               update_one_row
158                           Defines whether the table is able to update one
159                           single row. This capability is used for backward
160                           compatibility and might have (depending on table
161                           implementation) several limitations. Please
162                           carefully study the documentation of the table or
163                           ask the author of the table, if this information is
164                           not provided.
165
166                           This capability is evaluated automatically on first
167                           request and must not be handled by any derived
168                           classes.
169
170               update_specific_row
171                           Defines if the table is able to update one single
172                           row, but keeps the original content of the row to
173                           update.
174
175                           This capability is evaluated automatically on first
176                           request and must not be handled by derived classes.
177
178               update_current_row
179                           Defines if the table is able to update the
180                           currently touched row. This capability requires the
181                           capability of "inplace_update".
182
183                           This capability is evaluated automatically on first
184                           request and must not be handled by derived classes.
185
186               rowwise_update
187                           Defines if the table is able to do row-wise updates
188                           which means one of "update_one_row",
189                           "update_specific_row" or "update_current_row".  The
190                           "update_current_row" is only evaluated if the table
191                           has the "inplace_update" capability.
192
193                           This capability is evaluated automatically on first
194                           request and must not be handled by derived classes.
195
196               inplace_update
197                           Defines if an update of a row has side effects
198                           (capability is not available) or can be done
199                           without harming any other currently running task on
200                           the table.
201
202                           Example: The table storage is using a hash on the
203                           "PRIMARY KEY" of the table. Real perl hashes do not
204                           care when an item is updated while the hash is
205                           traversed using "each". "SDBM_File" 1.06 has a bug,
206                           which does not adjust the traversal pointer when an
207                           item is deleted.
208
209                           "SQL::Statement::RAM::Table" recognizes such
210                           situations and adjusts the traversal pointer.
211
212                           This might not be possible for all implementations
213                           which can update single rows.
214
215                           This capability could be provided by a derived
216                           class only.
217
218               delete_one_row
219                           Defines whether the table can delete one single row
220                           by it's content or not.
221
222                           This capability is evaluated automatically on first
223                           request and must not be handled by derived classes.
224
225               delete_current_row
226                           Defines whether a table can delete the current
227                           traversed row or not. This capability requires the
228                           "inplace_delete" capability.
229
230                           This capability is evaluated automatically on first
231                           request and must not be handled by derived classes.
232
233               rowwise_delete
234                           Defines if any row-wise delete operation is
235                           provided by the table. "row-wise" delete
236                           capabilities are "delete_one_row" and
237                           "delete_current_row".
238
239                           This capability is evaluated automatically on first
240                           request and must not be handled by derived classes.
241
242               inplace_delete
243                           Defines if the deletion of a row has side effects
244                           (capability is not available) or can be done
245                           without harming any other currently running task on
246                           the table.
247
248                           This capability should be provided by a derived
249                           class only.
250
251               insert_new_row
252                           Defines if a table can easily insert a new row
253                           without need to seek or truncate. This capability
254                           is provided by defining the table class method
255                           "insert_new_row".
256
257                           This capability is evaluated automatically on first
258                           request and must not be handled by derived classes.
259
260               If the capabilities rowwise_update and insert_new_row are
261               provided, the table primitive "push_row" is not required
262               anymore and may be omitted.
263
264       The above methods are implemented by SQL::Eval::Table. The following
265       methods are not, so that they *must* be implemented by the subclass.
266       See the "DBD::DBM::Table" or "DBD::CSV::Table" for example.
267
268       drop    Drops the table. All resources allocated by the table must be
269               released after "$table-"drop($data)>.
270
271       fetch_row
272               Fetches the next row from the table. Returns "undef", if the
273               last row was already fetched. The argument $data is for private
274               use of the subclass. Example:
275
276                   $row = $table->fetch_row($data);
277
278               Note, that you may use
279
280                   $row = $table->row();
281
282               for retrieving the same row again, until the next call of
283               "fetch_row".
284
285               "SQL::Statement" requires that the last fetched row is
286               available again and again via "$table-"row()>.
287
288       push_row
289               As fetch_row except for storing rows. Example:
290
291                   $table->push_row($data, $row);
292
293       push_names
294               Used by the CREATE TABLE statement to set the column names of
295               the new table. Receives an array ref of names. Example:
296
297                   $table->push_names($data, $names);
298
299       seek    Similar to the seek method of a filehandle; used for setting
300               the number of the next row being written. Example:
301
302                   $table->seek($data, $whence, $rowNum);
303
304               Actually the current implementation only uses "seek($data, 0,
305               0)" (first row) and "seek($data, 2, 0)" (beyond last row, end
306               of file).
307
308       truncate
309               Truncates a table after the current row. Example:
310
311                   $table->truncate($data);
312

INTERNALS

314       The current implementation is quite simple: An SQL::Eval object is an
315       hash ref with only two attributes. The "params" attribute is an array
316       ref of parameters. The "tables" attribute is an hash ref of table names
317       (keys) and table objects (values).
318
319       SQL::Eval::Table instances are implemented as hash refs. Attributes
320       used are "row" (the array ref of the current row), "col_nums" (an hash
321       ref of column names as keys and column numbers as values) and
322       "col_names", an array ref of column names with the column numbers as
323       indexes.
324

MULTITHREADING

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

BUGS

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

SUPPORT

338       You can find documentation for this module with the perldoc command.
339
340           perldoc SQL::Eval
341           perldoc SQL::Statement
342
343       You can also look for information at:
344
345       ·   RT: CPAN's request tracker
346
347           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL-Statement>
348
349       ·   AnnoCPAN: Annotated CPAN documentation
350
351           <http://annocpan.org/dist/SQL-Statement>
352
353       ·   CPAN Ratings
354
355           <http://cpanratings.perl.org/s/SQL-Statement>
356
357       ·   Search CPAN
358
359           <http://search.cpan.org/dist/SQL-Statement/>
360
362       Written by Jochen Wiedmann and currently maintained by Jens Rehsack.
363
364       This module is Copyright (C) 1998 by
365
366           Jochen Wiedmann
367           Am Eisteich 9
368           72555 Metzingen
369           Germany
370
371           Email: joe@ispsoft.de
372           Phone: +49 7123 14887
373
374       and Copyright (C) 2009, 2017 by
375
376            Jens Rehsack < rehsackATcpan.org>
377
378       All rights reserved.
379
380       You may distribute this module under the terms of either the GNU
381       General Public License or the Artistic License, as specified in the
382       Perl README file.
383

SEE ALSO

385       SQL::Statement(3)
386
387
388
389perl v5.28.1                      2017-04-06                      SQL::Eval(3)
Impressum