view release on metacpan or  search on metacpan

lib/DBD/SQLite/VirtualTable.pm  view on Meta::CPAN

written in Perl. Such tables look like regular tables, and are accessed
through regular SQL instructions and regular L<DBI> API; but the implementation
is done through hidden calls to a Perl class. 
This is the same idea as Perl's L<tied variables|perltie>, but
at the SQLite level.

The current abstract class cannot be used directly, so the
synopsis above is just to give a general idea. Concrete, usable
classes bundled with the present distribution are :

=over 

=item *

L<DBD::SQLite::VirtualTable::FileContent> : implements a virtual
column that exposes file contents. This is especially useful
in conjunction with a fulltext index; see L<DBD::SQLite::Fulltext_search>.

=item *

L<DBD::SQLite::VirtualTable::PerlData> : binds to a Perl array
within the Perl program. This can be used for simple import/export
operations, for debugging purposes, for joining data from different
sources, etc.

=back

Other Perl virtual tables may also be published separately on CPAN.

The following chapters document the structure of the abstract class
and explain how to write new subclasses; this is meant for 
B<module authors>, not for end users. If you just need to use a
virtual table module, refer to that module's documentation.


=head1 ARCHITECTURE

=head2 Classes

A virtual table module for SQLite is implemented through a pair
of classes :

=over

=item *

the B<table> class implements methods for creating or connecting
a virtual table, for destroying it, for opening new searches, etc.

=item *

the B<cursor> class implements methods for performing a specific
SQL statement

=back


=head2 Methods

Most methods in both classes are not called directly from Perl
code : instead, they are callbacks, called from the sqlite kernel.
Following common Perl conventions, such methods have names in
uppercase.


=head1 TABLE METHODS

=head2 Class methods for registering the module

=head3 CREATE_MODULE

  $class->CREATE_MODULE($sqlite_module_name);

Called when the client code invokes

  $dbh->sqlite_create_module($sqlite_module_name => $class);

The default implementation is empty.


=head3 DESTROY_MODULE

  $class->DESTROY_MODULE();

Called automatically when the database handle is disconnected.
The default implementation is empty.


=head2 Class methods for creating a vtable instance


=head3 CREATE

  $class->CREATE($dbh_ref, $module_name, $db_name, $vtab_name, @args);

Called when sqlite receives a statement

  CREATE VIRTUAL TABLE $db_name.$vtab_name USING $module_name(@args)

The default implementation just calls L</NEW>.

=head3 CONNECT

  $class->CONNECT($dbh_ref, $module_name, $db_name, $vtab_name, @args);

Called when attempting to access a virtual table that had been created
during previous database connection. The creation arguments were stored
within the sqlite database and are passed again to the CONNECT method.

The default implementation just calls L</NEW>.


=head3 _PREPARE_SELF

  $class->_PREPARE_SELF($dbh_ref, $module_name, $db_name, $vtab_name, @args);

Prepares the datastructure for a virtual table instance.  C<@args> is
 just the collection of strings (comma-separated) that were given
 within the C<CREATE VIRTUAL TABLE> statement; each subclass should
 decide what to do with this information,