1Padre::DB::LastPositionUIsneFrilCeo(n3t)ributed Perl DocPuamdernet:a:tDiBo:n:LastPositionInFile(3)
2
6 Padre::DB::LastPositionInFile - Storage class for stateful cursor
7 positions
8
10 Padre::DB::LastPositionInFile->set_last_pos($file, $pos);
11 my $pos = Padre::DB::LastPositionInFile->get_last_pos($file);
12
14 This class allows storing in Padre's database the last cursor position
15 in a file. This is useful in order to put the cursor back to where it
16 was when re-opening this file later on.
17 Please note that due to limitations in the way we generate the class,
19 imposed by ORLite, automatic translation for Portable Perl is only
20 applied if you use the "set_last_pos" and "get_last_pos" methods.
21
23 set_last_pos
24 set_last_pos( $file, $pos )
25 Record $pos as the last known cursor position in $file.
27 Applies appropriate path translation if we are running in Portable
29 Perl.
30 get_last_pos
32 get_last_pos( $file )
33 Return the last known cursor position for $file. Return "undef" if no
35 position was recorded for this file.
36 Applies appropriate path translation if we are running in Portable
38 Perl.
39 base
41 # Returns 'Padre::DB'
42 my $namespace = Padre::DB::LastPositionInFile->base;
43 Normally you will only need to work directly with a table class, and
45 only with one ORLite package.
46 However, if for some reason you need to work with multiple ORLite
48 packages at the same time without hardcoding the root namespace all the
49 time, you can determine the root namespace from an object or table
50 class with the "base" method.
51 table
53 # Returns 'last_position_in_file'
54 print Padre::DB::LastPositionInFile->table;
55 While you should not need the name of table for any simple operations,
57 from time to time you may need it programatically. If you do need it,
58 you can use the "table" method to get the table name.
59 load
61 my $object = Padre::DB::LastPositionInFile->load( $name );
62 If your table has single column primary key, a "load" method will be
64 generated in the class. If there is no primary key, the method is not
65 created.
66 The "load" method provides a shortcut mechanism for fetching a single
68 object based on the value of the primary key. However it should only be
69 used for cases where your code trusts the record to already exists.
70 It returns a "Padre::DB::LastPositionInFile" object, or throws an
72 exception if the object does not exist.
73 select
75 # Get all objects in list context
76 my @list = Padre::DB::LastPositionInFile->select;
77 # Get a subset of objects in scalar context
79 my $array_ref = Padre::DB::LastPositionInFile->select(
80 'where name > ? order by name',
81 1000,
82 );
83 The "select" method executes a typical SQL "SELECT" query on the
85 last_position_in_file table.
86 It takes an optional argument of a SQL phrase to be added after the
88 "FROM last_position_in_file" section of the query, followed by
89 variables to be bound to the placeholders in the SQL phrase. Any SQL
90 that is compatible with SQLite can be used in the parameter.
91 Returns a list of Padre::DB::LastPositionInFile objects when called in
93 list context, or a reference to an "ARRAY" of
94 Padre::DB::LastPositionInFile objects when called in scalar context.
95 Throws an exception on error, typically directly from the DBI layer.
97 iterate
99 Padre::DB::LastPositionInFile->iterate( sub {
100 print $_->name . "\n";
101 } );
102 The "iterate" method enables the processing of large tables one record
104 at a time without loading having to them all into memory in advance.
105 This plays well to the strength of SQLite, allowing it to do the work
107 of loading arbitrarily large stream of records from disk while
108 retaining the full power of Perl when processing the records.
109 The last argument to "iterate" must be a subroutine reference that will
111 be called for each element in the list, with the object provided in the
112 topic variable $_.
113 This makes the "iterate" code fragment above functionally equivalent to
115 the following, except with an O(1) memory cost instead of O(n).
116 foreach ( Padre::DB::LastPositionInFile->select ) {
118 print $_->name . "\n";
119 }
120 You can filter the list via SQL in the same way you can with "select".
122 Padre::DB::LastPositionInFile->iterate(
124 'order by ?', 'name',
125 sub {
126 print $_->name . "\n";
127 }
128 );
129 You can also use it in raw form from the root namespace for better
131 control. Using this form also allows for the use of arbitrarily
132 complex queries, including joins. Instead of being objects, rows are
133 provided as "ARRAY" references when used in this form.
134 Padre::DB->iterate(
136 'select name from last_position_in_file order by name',
137 sub {
138 print $_->[0] . "\n";
139 }
140 );
141 count
143 # How many objects are in the table
144 my $rows = Padre::DB::LastPositionInFile->count;
145 # How many objects
147 my $small = Padre::DB::LastPositionInFile->count(
148 'where name > ?',
149 1000,
150 );
151 The "count" method executes a "SELECT COUNT(*)" query on the
153 last_position_in_file table.
154 It takes an optional argument of a SQL phrase to be added after the
156 "FROM last_position_in_file" section of the query, followed by
157 variables to be bound to the placeholders in the SQL phrase. Any SQL
158 that is compatible with SQLite can be used in the parameter.
159 Returns the number of objects that match the condition.
161 Throws an exception on error, typically directly from the DBI layer.
163 new
165 TO BE COMPLETED
166 The "new" constructor is used to create a new abstract object that is
168 not (yet) written to the database.
169 Returns a new Padre::DB::LastPositionInFile object.
171 create
173 my $object = Padre::DB::LastPositionInFile->create(
174 name => 'value',
176 position => 'value',
178 );
180 The "create" constructor is a one-step combination of "new" and
182 "insert" that takes the column parameters, creates a new
183 Padre::DB::LastPositionInFile object, inserts the appropriate row into
184 the last_position_in_file table, and then returns the object.
185 If the primary key column "name" is not provided to the constructor (or
187 it is false) the object returned will have "name" set to the new unique
188 identifier.
189 Returns a new last_position_in_file object, or throws an exception on
191 error, typically from the DBI layer.
192 insert
194 $object->insert;
195 The "insert" method commits a new object (created with the "new"
197 method) into the database.
198 If a the primary key column "name" is not provided to the constructor
200 (or it is false) the object returned will have "name" set to the new
201 unique identifier.
202 Returns the object itself as a convenience, or throws an exception on
204 error, typically from the DBI layer.
205 delete
207 # Delete a single instantiated object
208 $object->delete;
209 # Delete multiple rows from the last_position_in_file table
211 Padre::DB::LastPositionInFile->delete('where name > ?', 1000);
212 The "delete" method can be used in a class form and an instance form.
214 When used on an existing Padre::DB::LastPositionInFile instance, the
216 "delete" method removes that specific instance from the
217 "last_position_in_file", leaving the object intact for you to deal with
218 post-delete actions as you wish.
219 When used as a class method, it takes a compulsory argument of a SQL
221 phrase to be added after the "DELETE FROM last_position_in_file"
222 section of the query, followed by variables to be bound to the
223 placeholders in the SQL phrase. Any SQL that is compatible with SQLite
224 can be used in the parameter.
225 Returns true on success or throws an exception on error, or if you
227 attempt to call delete without a SQL condition phrase.
228 truncate
230 # Delete all records in the last_position_in_file table
231 Padre::DB::LastPositionInFile->truncate;
232 To prevent the common and extremely dangerous error case where deletion
234 is called accidentally without providing a condition, the use of the
235 "delete" method without a specific condition is forbidden.
236 Instead, the distinct method "truncate" is provided to delete all
238 records in a table with specific intent.
239 Returns true, or throws an exception on error.
241
243 name
244 if ( $object->name ) {
245 print "Object has been inserted\n";
246 } else {
247 print "Object has not been inserted\n";
248 }
249 Returns true, or throws an exception on error.
251 REMAINING ACCESSORS TO BE COMPLETED
253
255 The last_position_in_file table was originally created with the
256 following SQL command.
257 CREATE TABLE last_position_in_file (
259 name varchar(255) not null primary key,
260 position integer not null
261 )
262
264 Padre::DB::LastPositionInFile is part of the Padre::DB API.
265 See the documentation for Padre::DB for more information.
267
269 Adam Kennedy <adamk@cpan.org>
270
272 Copyright 2008-2011 The Padre development team as listed in Padre.pm.
273 This program is free software; you can redistribute it and/or modify it
275 under the same terms as Perl itself.
276 The full text of the license can be found in the LICENSE file included
278 with this module.
279perl v5.32.1 2021-01-27 Padre::DB::LastPositionInFile(3)