1SQL::Eval(3) User Contributed Perl Documentation SQL::Eval(3)
2
6 SQL::Eval - Base for deriving evaluation objects for SQL::Statement
7
9 require SQL::Statement;
10 require SQL::Eval;
11 # 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 # Get an eval object by calling open_tables; this
18 # will call MyStatement::open_table
19 my $eval = $stmt->open_tables($data);
20 # Set parameter 0 to 'Van Gogh'
22 $eval->param(0, 'Van Gogh');
23 # Get parameter 2
24 my $param = $eval->param(2);
25 # Get the SQL::Eval::Table object referring the 'foo' table
27 my $fooTable = $eval->table('foo');
28
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 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 All methods throw a Perl exception in case of errors.
44 Method interface of SQL::Eval
46 new Constructor; use it like this:
47 $eval = SQL::Eval->new(\%attr);
49 Blesses the hash ref \%attr into the SQL::Eval class (or a
51 subclass).
52 param Used for getting or setting input parameters, as in the SQL
54 query
55 INSERT INTO foo VALUES (?, ?);
57 Example:
59 $eval->param(0, $val); # Set parameter 0
61 $eval->param(0); # Get parameter 0
62 params Used for getting or setting the complete array of input
64 parameters. Example:
65 $eval->params($params); # Set the array
67 $eval->params(); # Get the array
68 table Returns or sets a table object. Example:
70 $eval->table('foo', $fooTable); # Set the 'foo' table object
72 $eval->table('foo'); # Return the 'foo' table object
73 column Return the value of a column with a given name; example:
75 $col = $eval->column('foo', 'id'); # Return the 'id' column of
77 # the current row in the
78 # 'foo' table
79 This is equivalent to and a shorthand for
81 $col = $eval->table('foo')->column('id');
83 _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 Method interface of SQL::Eval::Table
90 new Constructor; use it like this:
91 $eval = SQL::Eval::Table->new(\%attr);
93 Blesses the hash ref \%attr into the SQL::Eval::Table class (or
95 a subclass).
96 The following attributes are used by "SQL::Eval::Table":
98 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 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 capabilities
109 Hash reference containing additional capabilities.
110 _gen_access_fastpath
112 Return a subroutine reference for fast accessing
113 columns for read-only access. When the instantiated
114 object does not provide own methods for "column"
115 and "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 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 $row = $table->row();
126 column Get the column with a given name in the current row. Valid only
128 after a successful "$table->fetchrow()". Example:
129 $col = $table->column($colName);
131 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 $colNum = $table->column_num($colNum);
138 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 col_names
144 Returns an array ref of column names ordered by their index
145 within the table.
146 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 The following capabilities are used (and requested) by
155 SQL::Statement:
156 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 This capability is evaluated automatically on first
167 request and must not be handled by any derived
168 classes.
169 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 This capability is evaluated automatically on first
176 request and must not be handled by derived classes.
177 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 This capability is evaluated automatically on first
184 request and must not be handled by derived classes.
185 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 This capability is evaluated automatically on first
194 request and must not be handled by derived classes.
195 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 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 "SQL::Statement::RAM::Table" recognizes such
210 situations and adjusts the traversal pointer.
211 This might not be possible for all implementations
213 which can update single rows.
214 This capability could be provided by a derived
216 class only.
217 delete_one_row
219 Defines whether the table can delete one single row
220 by it's content or not.
221 This capability is evaluated automatically on first
223 request and must not be handled by derived classes.
224 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 This capability is evaluated automatically on first
231 request and must not be handled by derived classes.
232 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 This capability is evaluated automatically on first
240 request and must not be handled by derived classes.
241 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 This capability should be provided by a derived
249 class only.
250 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 This capability is evaluated automatically on first
258 request and must not be handled by derived classes.
259 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 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 drop Drops the table. All resources allocated by the table must be
269 released after "$table-"drop($data)>.
270 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 $row = $table->fetch_row($data);
277 Note, that you may use
279 $row = $table->row();
281 for retrieving the same row again, until the next call of
283 "fetch_row".
284 "SQL::Statement" requires that the last fetched row is
286 available again and again via "$table-"row()>.
287 push_row
289 As fetch_row except for storing rows. Example:
290 $table->push_row($data, $row);
292 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 $table->push_names($data, $names);
298 seek Similar to the seek method of a filehandle; used for setting
300 the number of the next row being written. Example:
301 $table->seek($data, $whence, $rowNum);
303 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 truncate
309 Truncates a table after the current row. Example:
310 $table->truncate($data);
312
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 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
326 All methods are working with instance-local data only, thus the module
327 is reentrant and thread safe, if you either do not share handles
328 between threads or grant serialized use.
329
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
338 You can find documentation for this module with the perldoc command.
339 perldoc SQL::Eval
341 perldoc SQL::Statement
342 You can also look for information at:
344 • RT: CPAN's request tracker
346 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=SQL-Statement>
348 • AnnoCPAN: Annotated CPAN documentation
350 <http://annocpan.org/dist/SQL-Statement>
352 • CPAN Ratings
354 <http://cpanratings.perl.org/s/SQL-Statement>
356 • Search CPAN
358 <http://search.cpan.org/dist/SQL-Statement/>
360
362 Written by Jochen Wiedmann and currently maintained by Jens Rehsack.
363 This module is Copyright (C) 1998 by
365 Jochen Wiedmann
367 Am Eisteich 9
368 72555 Metzingen
369 Germany
370 Email: joe@ispsoft.de
372 Phone: +49 7123 14887
373 and Copyright (C) 2009, 2017 by
375 Jens Rehsack < rehsackATcpan.org>
377 All rights reserved.
379 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
385 SQL::Statement(3)
386perl v5.34.0 2022-01-21 SQL::Eval(3)