1Padre::DB::LastPositionUIsneFrilCeo(n3t)ributed Perl DocPuamdernet:a:tDiBo:n:LastPositionInFile(3)
2
3
4

NAME

6       Padre::DB::LastPositionInFile - Storage class for stateful cursor
7       positions
8

SYNOPSIS

10         Padre::DB::LastPositionInFile->set_last_pos($file, $pos);
11         my $pos = Padre::DB::LastPositionInFile->get_last_pos($file);
12

DESCRIPTION

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
18       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

METHODS

23   set_last_pos
24         set_last_pos( $file, $pos )
25
26       Record $pos as the last known cursor position in $file.
27
28       Applies appropriate path translation if we are running in Portable
29       Perl.
30
31   get_last_pos
32         get_last_pos( $file )
33
34       Return the last known cursor position for $file. Return "undef" if no
35       position was recorded for this file.
36
37       Applies appropriate path translation if we are running in Portable
38       Perl.
39
40   base
41         # Returns 'Padre::DB'
42         my $namespace = Padre::DB::LastPositionInFile->base;
43
44       Normally you will only need to work directly with a table class, and
45       only with one ORLite package.
46
47       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
52   table
53         # Returns 'last_position_in_file'
54         print Padre::DB::LastPositionInFile->table;
55
56       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
60   load
61         my $object = Padre::DB::LastPositionInFile->load( $name );
62
63       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
67       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
71       It returns a "Padre::DB::LastPositionInFile" object, or throws an
72       exception if the object does not exist.
73
74   select
75         # Get all objects in list context
76         my @list = Padre::DB::LastPositionInFile->select;
77
78         # 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
84       The "select" method executes a typical SQL "SELECT" query on the
85       last_position_in_file table.
86
87       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
92       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
96       Throws an exception on error, typically directly from the DBI layer.
97
98   iterate
99         Padre::DB::LastPositionInFile->iterate( sub {
100             print $_->name . "\n";
101         } );
102
103       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
106       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
110       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
114       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
117         foreach ( Padre::DB::LastPositionInFile->select ) {
118             print $_->name . "\n";
119         }
120
121       You can filter the list via SQL in the same way you can with "select".
122
123         Padre::DB::LastPositionInFile->iterate(
124             'order by ?', 'name',
125             sub {
126                 print $_->name . "\n";
127             }
128         );
129
130       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
135         Padre::DB->iterate(
136             'select name from last_position_in_file order by name',
137             sub {
138                 print $_->[0] . "\n";
139             }
140         );
141
142   count
143         # How many objects are in the table
144         my $rows = Padre::DB::LastPositionInFile->count;
145
146         # How many objects
147         my $small = Padre::DB::LastPositionInFile->count(
148             'where name > ?',
149             1000,
150         );
151
152       The "count" method executes a "SELECT COUNT(*)" query on the
153       last_position_in_file table.
154
155       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
160       Returns the number of objects that match the condition.
161
162       Throws an exception on error, typically directly from the DBI layer.
163
164   new
165         TO BE COMPLETED
166
167       The "new" constructor is used to create a new abstract object that is
168       not (yet) written to the database.
169
170       Returns a new Padre::DB::LastPositionInFile object.
171
172   create
173         my $object = Padre::DB::LastPositionInFile->create(
174
175             name => 'value',
176
177             position => 'value',
178
179         );
180
181       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
186       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
190       Returns a new last_position_in_file object, or throws an exception on
191       error, typically from the DBI layer.
192
193   insert
194         $object->insert;
195
196       The "insert" method commits a new object (created with the "new"
197       method) into the database.
198
199       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
203       Returns the object itself as a convenience, or throws an exception on
204       error, typically from the DBI layer.
205
206   delete
207         # Delete a single instantiated object
208         $object->delete;
209
210         # Delete multiple rows from the last_position_in_file table
211         Padre::DB::LastPositionInFile->delete('where name > ?', 1000);
212
213       The "delete" method can be used in a class form and an instance form.
214
215       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
220       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
226       Returns true on success or throws an exception on error, or if you
227       attempt to call delete without a SQL condition phrase.
228
229   truncate
230         # Delete all records in the last_position_in_file table
231         Padre::DB::LastPositionInFile->truncate;
232
233       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
237       Instead, the distinct method "truncate" is provided to delete all
238       records in a table with specific intent.
239
240       Returns true, or throws an exception on error.
241

ACCESSORS

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
250       Returns true, or throws an exception on error.
251
252       REMAINING ACCESSORS TO BE COMPLETED
253

SQL

255       The last_position_in_file table was originally created with the
256       following SQL command.
257
258         CREATE TABLE last_position_in_file (
259             name varchar(255) not null primary key,
260             position integer not null
261         )
262

SUPPORT

264       Padre::DB::LastPositionInFile is part of the Padre::DB API.
265
266       See the documentation for Padre::DB for more information.
267

AUTHOR

269       Adam Kennedy <adamk@cpan.org>
270
272       Copyright 2008-2011 The Padre development team as listed in Padre.pm.
273
274       This program is free software; you can redistribute it and/or modify it
275       under the same terms as Perl itself.
276
277       The full text of the license can be found in the LICENSE file included
278       with this module.
279
280
281
282perl v5.32.0                      2020-07-28  Padre::DB::LastPositionInFile(3)
Impressum