File Coverage

blib/lib/ORLite/Pod.pm

Criterion	Covered	Total	%
statement	154	173	89.0
branch	17	38	44.7
condition	2	6	33.3
subroutine	27	28	96.4
pod	0	17	0.0
total	200	262	76.3

package ORLite::Pod;

=pod

=head1 NAME

ORLite::Pod - Documentation generator for ORLite

=head1 SYNOPSIS

  my $generator = ORLite::Pod->new(
      from   => 'My::Project::DB',
      to     => 'My-Project/lib',
      author => 'Adam Kennedy',
      email  => '[e-mail]',
  );

  $generator->run;

=head1 DESCRIPTION

The biggest downside of L is that because it can generate you
an entire ORM in one line of code, you can have a large an extensive
API without anywhere for documentation for the API to exist.

The result is quick efficient creation of APIs that nobody can
understand or use :)

B was created to fix this problem by allowing you to keep
your slimline Perl module as is, but generating a tree of .pod files
alongside the regular modules containing the documentation for the API.

B connects directly to a loaded ORLite instance,
interrogating it to find the database it connects to, and discovering
which tables have or don't have classes generated for them.

TO BE COMPLETED

=head1 METHODS

=cut

use 5.008;
use strict;
use Carp                    ();
use File::Spec       3.2701 ();
use File::Path         2.07 ();
use File::Basename        0 ();
use Params::Util       1.00 ();
use Class::Inspector   1.23 ();
use ORLite             1.23 ();
use Template           2.20 ();

our $VERSION = '0.11';

my $year = (localtime(time))[5] + 1900;





#####################################################################
# Constructor and Accessors

sub new {
	my $class = shift;
	my $self  = bless { @_ }, $class;

	# Normalise flags
	unless ( defined $self->trace ) {
		$self->{trace} = 1;
	}
	$self->{trace} = !! $self->{trace};

	# Check params
	unless (
		Params::Util::_CLASS($self->from)
		and
		$self->from->can('orlite')
	) {
		die("Did not provide a 'from' ORLite root class to generate from");
	}
	my $to = $self->to;
	unless ( $self->to ) {
		die("Did not provide a 'to' lib directory to write into");
	}
	unless ( -d $self->to ) {
		die("The 'to' lib directory '$to' does not exist");
	}
	unless ( -w $self->to ) {
		die("No permission to write to directory '$to'");
	}
	unless ( defined $self->author ) {
		$self->{author} = '';
	}
	unless ( defined $self->email ) {
		$self->{email} = '';
	}
	unless ( $self->year ) {
		$self->{year} = $year;
	}

	# Create the copyright year
	if ( $self->{year} == $year ) {
		$self->{copyyear} = $self->{year};
	} else {
		$self->{copyyear} = "$self->{year} - $year";
	}

	# Create the Template Toolkit context
	$self->{template} = Template->new( {
		PRE_CHOMP => 1,
	} );

	return $self;
}

sub from {
	$_[0]->{from};
}

sub dist {
	my $dist = $_[0]->from;
	$dist =~ s/::/-/g;
	return $dist;
}

sub to {
	$_[0]->{to};
}

sub author {
	$_[0]->{author};
}

sub author_pod {
	my $self = shift;
	if ( $self->author and $self->email ) {
		return $self->author . ' E' . $self->email . 'E';
	} elsif ( $self->author ) {
		return $self->author;
	} else {
		return '';
	}
}

sub email {
	$_[0]->{email};
}

sub year {
	$_[0]->{year};
}

sub template {
	$_[0]->{template};
}





#####################################################################
# POD Generation

sub run {
	my $self = shift;
	my $pkg  = $self->from;

	# Capture the raw schema information
	$self->trace("Analyzing " . $pkg->dsn . "...\n");
	my $dbh    = $pkg->dbh;
	my $tables = $dbh->selectall_arrayref(
		'select * from sqlite_master where type = ?',
		{ Slice => {} }, 'table',
	);
	foreach my $table ( @$tables ) {
		$table->{columns} = $dbh->selectall_arrayref(
			"pragma table_info('$table->{name}')",
		 	{ Slice => {} },
		);
	}

	# Generate the main additional table level metadata
	my %tindex = map { $_->{name} => $_ } @$tables;
	foreach my $table ( @$tables ) {
		my @columns      = @{ $table->{columns} };
		my @names        = map { $_->{name} } @columns;
		$table->{cindex} = map { $_->{name} => $_ } @columns;

		# Discover the primary key
		$table->{pk}     = List::Util::first { $_->{pk} } @columns;
		$table->{pk}     = $table->{pk}->{name} if $table->{pk};

		# What will be the class for this table
		$table->{class}  = ucfirst lc $table->{name};
		$table->{class}  =~ s/_([a-z])/uc($1)/ge;
		$table->{class}  = "${pkg}::$table->{class}";

		# Generate various SQL fragments
		my $sql = $table->{sql} = { create => $table->{sql} };
		$sql->{cols}     = join ', ', map { '"' . $_ . '"' } @names;
		$sql->{vals}     = join ', ', ('?') x scalar @columns;
		$sql->{select}   = "select $table->{sql}->{cols} from $table->{name}";
		$sql->{count}    = "select count(*) from $table->{name}";
		$sql->{insert}   = join ' ',
			"insert into $table->{name}" .
			"( $table->{sql}->{cols} )"  .
			" values ( $table->{sql}->{vals} )";
	}

	# Generate the foreign key metadata
	foreach my $table ( @$tables ) {
		# Locate the foreign keys
		my %fk     = ();
		my @fk_sql = $table->{sql}->{create} =~ /[(,]\s*(.+?REFERENCES.+?)\s*[,)]/g;

		# Extract the details
		foreach ( @fk_sql ) {
			unless ( /^(\w+).+?REFERENCES\s+(\w+)\s*\(\s*(\w+)/ ) {
				die "Invalid foreign key $_";
			}
			$fk{"$1"} = [ "$2", $tindex{"$2"}, "$3" ];
		}
		foreach ( @{ $table->{columns} } ) {
			$_->{fk} = $fk{$_->{name}};
		}
	}

	# Generate the root module .pod file
	$self->write_db( $tables );

	# Generate the table .pod files
	foreach my $table ( @$tables ) {
		# Beautify the create fragment
		$table->{create} = $self->beautify(
			$table->{sql}->{create}
		);

		# Skip tables we aren't modelling
		next unless $table->{class}->can('select');

		# Generate the table-specific file
		$self->write_table( $tables, $table );
	}

	return 1;
}

sub beautify {
	my $sql  = $_[1];
	my $copy = $sql;

	# Normalise and trim whitespace
	$copy =~ s/\s+/ /sg;
	$copy =~ s/\(\s+/(/sg;
	$copy =~ s/\s+\)/)/sg;
	$copy =~ s/\s*,\s*/,/sg;
	$copy =~ s/^\s+//s;
	$copy =~ s/\s+$//s;

	# Find the outermost braces
	unless ( $copy =~ /^(.+?\()(.+)(\).*)\z/ ) {
		# Give up
		return $sql;
	}
	my $create  = $1;
	my $colspec = $2;
	my $suffix  = $3;

	# Split the columns
	my @columns = split /(?<=,)/, $colspec;

	# Reassemble the pieces
	return join '', (
		"$create\n",
		( map { "    $_\n" } @columns ),
		"$suffix\n",
	);
}





#####################################################################
# Generation of Base Documentation

sub write {
	my $self  = shift;
	my $file  = shift;
	my $input = shift;
	my $hash  = shift;

	# Strip the leading pipes off the template
	$input =~ s/^\|//gm;

	# Process the template
	my $template = $self->template;
	my $output   = '';
	my $rv       = $template->process(\$input, $hash, \$output);
	unless ( $rv ) {
		die $template->error;
	}

	# Write the file
	local *FILE;
	open( FILE, '>', $file ) or die "open: $!";
	print FILE $output;
	close FILE;

	return 1;
}

sub trace {
	my $self = shift;
	if ( $self->{trace} ) {
		print @_;
	}
	return 1;
}

sub write_db {
	my $self    = shift;
	my $tables  = shift;
	my $pkg     = $self->from;
	my $methods = Class::Inspector->methods($pkg);

	# Determine the file we're going to be writing to
	my $file = File::Spec->catfile(
		$self->to,
		 split( /::/, $pkg )
	) . '.pod';

	# Generate and write the file
	$self->trace("Generating $file...\n");
	$self->write( $file, template_db(), {
		self       => $self,
		pkg        => $pkg,
		tables     => $tables,
		orlite2pod => $ORLite::Pod::VERSION,
		method     => {
			map { $_ => 1 } @$methods,
		},
	} );
}





#####################################################################
# Generation of Table-Specific Documentation

sub write_table {
	my $self    = shift;
	my $tables  = shift;
	my $table   = shift;
	my $root    = $self->from;
	my $pkg     = $table->{class};
	my $methods = Class::Inspector->methods($pkg);

	# Determine the file we're going to be writing to
	my $file = File::Spec->catfile(
		$self->to,
		 split( /::/, $pkg )
	) . '.pod';

	# Create the parent directory if needed
	my $dir = File::Basename::dirname($file);
	unless ( -d $dir ) {
		File::Path::make_path( $dir, { verbose => 0 } );
	}

	# Generate and write the file
	$self->trace("Generating $file...\n");
	$self->write( $file, template_table(), {
		self   => $self,
		pkg    => $pkg,
		root   => $root,
		tables => $tables,
		table  => $table,
		method => {
			map { $_ => 1 } @$methods,
		},
	} );
}





#####################################################################
# Root Template

sub template_db { <<'END_TT' }
|=head1 NAME
|
|[%+ pkg %] - An ORLite-based ORM Database API
|
|=head1 DESCRIPTION
|
|TO BE COMPLETED
|
|=head1 METHODS
|
[% IF method.dsn %]
|=head2 dsn
|
|  my $string = [%+ pkg %]->dsn;
|
|The C accessor returns the L connection string used to connect
|to the SQLite database as a string.
|
[% END %]
[% IF method.dbh %]
|=head2 dbh
|
|  my $handle = [%+ pkg %]->dbh;
|
|To reliably prevent potential L deadlocks resulting from multiple
|connections in a single process, each ORLite package will only ever
|maintain a single connection to the database.
|
|During a transaction, this will be the same (cached) database handle.
|
|Although in most situations you should not need a direct DBI connection
|handle, the C method provides a method for getting a direct
|connection in a way that is compatible with connection management in
|L.
|
|Please note that these connections should be short-lived, you should
|never hold onto a connection beyond your immediate scope.
|
|The transaction system in ORLite is specifically designed so that code
|using the database should never have to know whether or not it is in a
|transation.
|
|Because of this, you should B call the -Edisconnect method
|on the database handles yourself, as the handle may be that of a
|currently running transaction.
|
|Further, you should do your own transaction management on a handle
|provided by the  method.
|
|In cases where there are extreme needs, and you B have to
|violate these connection handling rules, you should create your own
|completely manual DBI-Econnect call to the database, using the connect
|string provided by the C method.
|
|The C method returns a L object, or throws an exception on
|error.
|
[% END %]
[% IF method.begin %]
|=head2 begin
|
|  [%+ pkg %]->begin;
|
|The C method indicates the start of a transaction.
|
|In the same way that ORLite allows only a single connection, likewise
|it allows only a single application-wide transaction.
|
|No indication is given as to whether you are currently in a transaction
|or not, all code should be written neutrally so that it works either way
|or doesn't need to care.
|
|Returns true or throws an exception on error.
|
[% END %]
[% IF method.commit %]
|=head2 commit
|
|  [%+ pkg %]->commit;
|
|The C method commits the current transaction. If called outside
|of a current transaction, it is accepted and treated as a null operation.
|
|Once the commit has been completed, the database connection falls back
|into auto-commit state. If you wish to immediately start another
|transaction, you will need to issue a separate -Ebegin call.
|
|Returns true or throws an exception on error.
|
[% END %]
[% IF method.rollback %]
|=head2 rollback
|
|The C method rolls back the current transaction. If called outside
|of a current transaction, it is accepted and treated as a null operation.
|
|Once the rollback has been completed, the database connection falls back
|into auto-commit state. If you wish to immediately start another
|transaction, you will need to issue a separate -Ebegin call.
|
|If a transaction exists at END-time as the process exits, it will be
|automatically rolled back.
|
|Returns true or throws an exception on error.
|
|=head2 do
|
|  [%+ pkg %]->do(
|      'insert into table ( foo, bar ) values ( ?, ? )', {},
|      \$foo_value,
|      \$bar_value,
|  );
|
|The C method is a direct wrapper around the equivalent L method,
|but applied to the appropriate locally-provided connection or transaction.
|
|It takes the same parameters and has the same return values and error
|behaviour.
|
[% END %]
[% IF method.selectall_arrayref %]
|=head2 selectall_arrayref
|
|The C method is a direct wrapper around the equivalent
|L method, but applied to the appropriate locally-provided connection
|or transaction.
|
|It takes the same parameters and has the same return values and error
|behaviour.
|
[% END %]
[% IF method.selectall_hashref %]
|=head2 selectall_hashref
|
|The C method is a direct wrapper around the equivalent
|L method, but applied to the appropriate locally-provided connection
|or transaction.
|
|It takes the same parameters and has the same return values and error
|behaviour.
|
[% END %]
[% IF method.selectcol_arrayref %]
|=head2 selectcol_arrayref
|
|The C method is a direct wrapper around the equivalent
|L method, but applied to the appropriate locally-provided connection
|or transaction.
|
|It takes the same parameters and has the same return values and error
|behaviour.
|
[% END %]
[% IF method.selectrow_array %]
|=head2 selectrow_array
|
|The C method is a direct wrapper around the equivalent
|L method, but applied to the appropriate locally-provided connection
|or transaction.
|
|It takes the same parameters and has the same return values and error
|behaviour.
|
[% END %]
[% IF method.selectrow_arrayref %]
|=head2 selectrow_arrayref
|
|The C method is a direct wrapper around the equivalent
|L method, but applied to the appropriate locally-provided connection
|or transaction.
|
|It takes the same parameters and has the same return values and error
|behaviour.
|
[% END %]
[% IF method.selectrow_hashref %]
|=head2 selectrow_hashref
|
|The C method is a direct wrapper around the equivalent
|L method, but applied to the appropriate locally-provided connection
|or transaction.
|
|It takes the same parameters and has the same return values and error
|behaviour.
|
[% END %]
[% IF method.prepare %]
|=head2 prepare
|
|The C method is a direct wrapper around the equivalent
|L method, but applied to the appropriate locally-provided connection
|or transaction
|
|It takes the same parameters and has the same return values and error
|behaviour.
|
|In general though, you should try to avoid the use of your own prepared
|statements if possible, although this is only a recommendation and by
|no means prohibited.
|
[% END %]
[% IF method.pragma %]
|=head2 pragma
|
|  # Get the user_version for the schema
|  my $version = [% pkg %]->pragma('user_version');
|
|The C method provides a convenient method for fetching a pragma
|for a database. See the L documentation for more details.
|
[% END %]
|=head1 SUPPORT
|
|B<[%+ pkg %]> is based on L.
|
|Documentation created by L [% orlite2pod %].
|
|[% IF self.rt %]
|Bugs should be reported via the CPAN bug tracker at
|
|L
|
|For other issues, contact the author.
[% ELSE %]
|For general support please see the support section of the main
|project documentation.
[% END %]
|
[% IF self.author_pod %]
|=head1 AUTHOR
|
|[%+ self.author_pod %]
[% END %]
|=head1 COPYRIGHT
|
|Copyright [% self.copyyear %] [%+ self.author %].
|
|This program is free software; you can redistribute
|it and/or modify it under the same terms as Perl itself.
|
|The full text of the license can be found in the
|LICENSE file included with this module.
|
END_TT





#####################################################################
# Table Template

sub template_table { <<'END_TT' }
|=head1 NAME
|
|[%+ pkg %] - [% root %] class for the [% table.name %] table
|
|=head1 DESCRIPTION
|
|TO BE COMPLETED
|
|=head1 METHODS
|
[% IF method.base %]
|=head2 base
|
|  # Returns '[% root %]'
|  my $namespace = [% pkg %]->base;
|
|Normally you will only need to work directly with a table class,
|and only with one ORLite package.
|
|However, if for some reason you need to work with multiple ORLite packages
|at the same time without hardcoding the root namespace all the time, you
|can determine the root namespace from an object or table class with the
|C method.
|
[% END %]
[% IF method.table %]
|=head2 table
|
|  # Returns '[% table.name %]'
|  print [% pkg %]->table;
|
|While you should not need the name of table for any simple operations,
|from time to time you may need it programatically. If you do need it,
|you can use the C method to get the table name. 




684




 





 





 





 





 





 



 | 




685




 





 





 





 





 





 



 [% END %] 




686




 





 





 





 





 





 



 [% IF method.load %] 




687




 





 





 





 





 





 



 |=head2 load 




688




 





 





 





 





 





 



 | 




689




 





 





 





 





 





 



 |  my $object = [% pkg %]->load( $[% table.pk %] ); 




690




 





 





 





 





 





 



 | 




691




 





 





 





 





 





 



 |If your table has single column primary key, a C method will be 




692




 





 





 





 





 





 



 |generated in the class. If there is no primary key, the method is not 




693




 





 





 





 





 





 



 |created. 




694




 





 





 





 





 





 



 | 




695




 





 





 





 





 





 



 |The C method provides a shortcut mechanism for fetching a single 




696




 





 





 





 





 





 



 |object based on the value of the primary key. However it should only 




697




 





 





 





 





 





 



 |be used for cases where your code trusts the record to already exists. 




698




 





 





 





 





 





 



 | 




699




 





 





 





 





 





 



 |It returns a C<[% pkg %]> object, or throws an exception if the 




700




 





 





 





 





 





 



 |object does not exist. 




701




 





 





 





 





 





 



 | 




702




 





 





 





 





 





 



 [% END %] 




703




 





 





 





 





 





 



 [% IF method.select %] 




704




 





 





 





 





 





 



 |=head2 select 




705




 





 





 





 





 





 



 | 




706




 





 





 





 





 





 



 |  # Get all objects in list context 




707




 





 





 





 





 





 



 |  my @list = [% pkg %]->select; 




708




 





 





 





 





 





 



 |   




709




 





 





 





 





 





 



 |  # Get a subset of objects in scalar context 




710




 





 





 





 





 





 



 |  my $array_ref = [% pkg %]->select( 




711




 





 





 





 





 





 



 |      'where [% table.pk %] > ? order by [% table.pk %]', 




712




 





 





 





 





 





 



 |      1000, 




713




 





 





 





 





 





 



 |  ); 




714




 





 





 





 





 





 



 | 




715




 





 





 





 





 





 



 |The C method executes a typical SQL C query on the 




716




 





 





 





 





 





 



 |[%+ table.name %] table. 




717




 





 





 





 





 





 



 | 




718




 





 





 





 





 





 



 |It takes an optional argument of a SQL phrase to be added after the 




719




 





 





 





 





 





 



 |C section of the query, followed by variables 




720




 





 





 





 





 





 



 |to be bound to the placeholders in the SQL phrase. Any SQL that is 




721




 





 





 





 





 





 



 |compatible with SQLite can be used in the parameter. 




722




 





 





 





 





 





 



 | 




723




 





 





 





 





 





 



 |Returns a list of B<[% pkg %]> objects when called in list context, or a 




724




 





 





 





 





 





 



 |reference to an C of B<[% pkg %]> objects when called in scalar 




725




 





 





 





 





 





 



 |context. 




726




 





 





 





 





 





 



 | 




727




 





 





 





 





 





 



 |Throws an exception on error, typically directly from the L layer. 




728




 





 





 





 





 





 



 | 




729




 





 





 





 





 





 



 [% END %] 




730




 





 





 





 





 





 



 [% IF method.iterate %] 




731




 





 





 





 





 





 



 |=head2 iterate 




732




 





 





 





 





 





 



 | 




733




 





 





 





 





 





 



 |  [%+ pkg %]->iterate( sub { 




734




 





 





 





 





 





 



 |      print $_->[% table.pk %] . "\n"; 




735




 





 





 





 





 





 



 |  } ); 




736




 





 





 





 





 





 



 | 




737




 





 





 





 





 





 



 |The C method enables the processing of large tables one record at 




738




 





 





 





 





 





 



 |a time without loading having to them all into memory in advance. 




739




 





 





 





 





 





 



 | 




740




 





 





 





 





 





 



 |This plays well to the strength of SQLite, allowing it to do the work of 




741




 





 





 





 





 





 



 |loading arbitrarily large stream of records from disk while retaining the 




742




 





 





 





 





 





 



 |full power of Perl when processing the records. 




743




 





 





 





 





 





 



 | 




744




 





 





 





 





 





 



 |The last argument to C must be a subroutine reference that will be 




745




 





 





 





 





 





 



 |called for each element in the list, with the object provided in the topic 




746




 





 





 





 





 





 



 |variable C<$_>. 




747




 





 





 





 





 





 



 | 




748




 





 





 





 





 





 



 |This makes the C code fragment above functionally equivalent to the 




749




 





 





 





 





 





 



 |following, except with an O(1) memory cost instead of O(n). 




750




 





 





 





 





 





 



 | 




751




 





 





 





 





 





 



 |  foreach ( [% pkg %]->select ) { 




752




 





 





 





 





 





 



 |      print $_->[% table.pk %] . "\n"; 




753




 





 





 





 





 





 



 |  } 




754




 





 





 





 





 





 



 | 




755




 





 





 





 





 





 



 |You can filter the list via SQL in the same way you can with C. 




756




 





 





 





 





 





 



 | 




757




 





 





 





 





 





 



 |  [%+ pkg %]->iterate( 




758




 





 





 





 





 





 



 |      'order by ?', '[% table.pk %]', 




759




 





 





 





 





 





 



 |      sub { 




760




 





 





 





 





 





 



 |          print $_->[% table.pk %] . "\n"; 




761




 





 





 





 





 





 



 |      } 




762




 





 





 





 





 





 



 |  ); 




763




 





 





 





 





 





 



 | 




764




 





 





 





 





 





 



 |You can also use it in raw form from the root namespace for better control. 




765




 





 





 





 





 





 



 |Using this form also allows for the use of arbitrarily complex queries, 




766




 





 





 





 





 





 



 |including joins. Instead of being objects, rows are provided as C 




767




 





 





 





 





 





 



 |references when used in this form. 




768




 





 





 





 





 





 



 | 




769




 





 





 





 





 





 



 |  [%+ root %]->iterate( 




770




 





 





 





 





 





 



 |      'select name from [% table.name %] order by [% table.pk %]', 




771




 





 





 





 





 





 



 |      sub { 




772




 





 





 





 





 





 



 |          print $_->[0] . "\n"; 




773




 





 





 





 





 





 



 |      } 




774




 





 





 





 





 





 



 |  ); 




775




 





 





 





 





 





 



 | 




776




 





 





 





 





 





 



 [% END %] 




777




 





 





 





 





 





 



 [% IF method.count %] 




778




 





 





 





 





 





 



 |=head2 count 




779




 





 





 





 





 





 



 | 




780




 





 





 





 





 





 



 |  # How many objects are in the table 




781




 





 





 





 





 





 



 |  my $rows = [% pkg %]->count; 




782




 





 





 





 





 





 



 |   




783




 





 





 





 





 





 



 |  # How many objects  




784




 





 





 





 





 





 



 |  my $small = [% pkg %]->count( 




785




 





 





 





 





 





 



 |      'where [% table.pk %] > ?', 




786




 





 





 





 





 





 



 |      1000, 




787




 





 





 





 





 





 



 |  ); 




788




 





 





 





 





 





 



 | 




789




 





 





 





 





 





 



 |The C method executes a C query on the 




790




 





 





 





 





 





 



 |[%+ table.name %] table. 




791




 





 





 





 





 





 



 | 




792




 





 





 





 





 





 



 |It takes an optional argument of a SQL phrase to be added after the 




793




 





 





 





 





 





 



 |C section of the query, followed by variables 




794




 





 





 





 





 





 



 |to be bound to the placeholders in the SQL phrase. Any SQL that is 




795




 





 





 





 





 





 



 |compatible with SQLite can be used in the parameter. 




796




 





 





 





 





 





 



 | 




797




 





 





 





 





 





 



 |Returns the number of objects that match the condition. 




798




 





 





 





 





 





 



 | 




799




 





 





 





 





 





 



 |Throws an exception on error, typically directly from the L layer. 




800




 





 





 





 





 





 



 | 




801




 





 





 





 





 





 



 [% END %] 




802




 





 





 





 





 





 



 [% IF method.new %] 




803




 





 





 





 





 





 



 |=head2 new 




804




 





 





 





 





 





 



 | 




805




 





 





 





 





 





 



 |  TO BE COMPLETED 




806




 





 





 





 





 





 



 | 




807




 





 





 





 





 





 



 |The C constructor is used to create a new abstract object that 




808




 





 





 





 





 





 



 |is not (yet) written to the database. 




809




 





 





 





 





 





 



 | 




810




 





 





 





 





 





 



 |Returns a new L<[% pkg %]> object. 




811




 





 





 





 





 





 



 | 




812




 





 





 





 





 





 



 [% END %] 




813




 





 





 





 





 





 



 [% IF method.create %] 




814




 





 





 





 





 





 



 |=head2 create 




815




 





 





 





 





 





 



 | 




816




 





 





 





 





 





 



 |  my $object = [% pkg %]->create( 




817




 





 





 





 





 





 



 |[%- FOREACH column IN table.columns %] 




818




 





 





 





 





 





 



 |      [%+ column.name %] => 'value', 




819




 





 





 





 





 





 



 |[%- END %] 




820




 





 





 





 





 





 



 |  ); 




821




 





 





 





 





 





 



 | 




822




 





 





 





 





 





 



 |The C constructor is a one-step combination of C and 




823




 





 





 





 





 





 



 |C that takes the column parameters, creates a new 




824




 





 





 





 





 





 



 |L<[% pkg %]> object, inserts the appropriate row into the 




825




 





 





 





 





 





 



 |L<[% table.name %]> table, and then returns the object. 




826




 





 





 





 





 





 



 | 




827




 





 





 





 





 





 



 |If the primary key column C<[% table.pk %]> is not provided to the 




828




 





 





 





 





 





 



 |constructor (or it is false) the object returned will have 




829




 





 





 





 





 





 



 |C<[% table.pk %]> set to the new unique identifier. 




830




 





 





 





 





 





 



 |  




831




 





 





 





 





 





 



 |Returns a new L<[% table.name %]> object, or throws an exception on 




832




 





 





 





 





 





 



 |error, typically from the L layer. 




833




 





 





 





 





 





 



 | 




834




 





 





 





 





 





 



 [% END %] 




835




 





 





 





 





 





 



 [% IF method.insert %] 




836




 





 





 





 





 





 



 |=head2 insert 




837




 





 





 





 





 





 



 | 




838




 





 





 





 





 





 



 |  $object->insert; 




839




 





 





 





 





 





 



 | 




840




 





 





 





 





 





 



 |The C method commits a new object (created with the C method) 




841




 





 





 





 





 





 



 |into the database. 




842




 





 





 





 





 





 



 | 




843




 





 





 





 





 





 



 |If a the primary key column C<[% table.pk %]> is not provided to the 




844




 





 





 





 





 





 



 |constructor (or it is false) the object returned will have 




845




 





 





 





 





 





 



 |C<[% table.pk %]> set to the new unique identifier. 




846




 





 





 





 





 





 



 | 




847




 





 





 





 





 





 



 |Returns the object itself as a convenience, or throws an exception 




848




 





 





 





 





 





 



 |on error, typically from the L layer. 




849




 





 





 





 





 





 



 | 




850




 





 





 





 





 





 



 [% END %] 




851




 





 





 





 





 





 



 [% IF method.delete %] 




852




 





 





 





 





 





 



 |=head2 delete 




853




 





 





 





 





 





 



 | 




854




 





 





 





 





 





 



 |  # Delete a single instantiated object 




855




 





 





 





 





 





 



 |  $object->delete; 




856




 





 





 





 





 





 



 |   




857




 





 





 





 





 





 



 |  # Delete multiple rows from the [% table.name %] table 




858




 





 





 





 





 





 



 |  [%+ pkg %]->delete('where [% table.pk %] > ?', 1000); 




859




 





 





 





 





 





 



 | 




860




 





 





 





 





 





 



 |The C method can be used in a class form and an instance form. 




861




 





 





 





 





 





 



 | 




862




 





 





 





 





 





 



 |When used on an existing B<[% pkg %]> instance, the C method 




863




 





 





 





 





 





 



 |removes that specific instance from the C<[% table.name %]>, leaving 




864




 





 





 





 





 





 



 |the object intact for you to deal with post-delete actions as you wish. 




865




 





 





 





 





 





 



 | 




866




 





 





 





 





 





 



 |When used as a class method, it takes a compulsory argument of a SQL 




867




 





 





 





 





 





 



 |phrase to be added after the C section 




868




 





 





 





 





 





 



 |of the query, followed by variables to be bound to the placeholders 




869




 





 





 





 





 





 



 |in the SQL phrase. Any SQL that is compatible with SQLite can be used 




870




 





 





 





 





 





 



 |in the parameter. 




871




 





 





 





 





 





 



 | 




872




 





 





 





 





 





 



 |Returns true on success or throws an exception on error, or if you 




873




 





 





 





 





 





 



 |attempt to call delete without a SQL condition phrase. 




874




 





 





 





 





 





 



 | 




875




 





 





 





 





 





 



 [% END %] 




876




 





 





 





 





 





 



 [% IF method.truncate %] 




877




 





 





 





 





 





 



 |=head2 truncate 




878




 





 





 





 





 





 



 | 




879




 





 





 





 





 





 



 |  # Delete all records in the [% table.name %] table 




880




 





 





 





 





 





 



 |  [%+ pkg %]->truncate; 




881




 





 





 





 





 





 



 | 




882




 





 





 





 





 





 



 |To prevent the common and extremely dangerous error case where 




883




 





 





 





 





 





 



 |deletion is called accidentally without providing a condition, 




884




 





 





 





 





 





 



 |the use of the C method without a specific condition 




885




 





 





 





 





 





 



 |is forbidden. 




886




 





 





 





 





 





 



 | 




887




 





 





 





 





 





 



 |Instead, the distinct method C is provided to delete 




888




 





 





 





 





 





 



 |all records in a table with specific intent. 




889




 





 





 





 





 





 



 | 




890




 





 





 





 





 





 



 |Returns true, or throws an exception on error. 




891




 





 





 





 





 





 



 | 




892




 





 





 





 





 





 



 [% END %] 




893




 





 





 





 





 





 



 |=head1 ACCESSORS 




894




 





 





 





 





 





 



 | 




895




 





 





 





 





 





 



 [% pk = table.pk %] 




896




 





 





 





 





 





 



 [% IF method.$pk %] 




897




 





 





 





 





 





 



 |=head2 [% pk %] 




898




 





 





 





 





 





 



 | 




899




 





 





 





 





 





 



 |  if ( $object->[% pk %] ) { 




900




 





 





 





 





 





 



 |      print "Object has been inserted\n"; 




901




 





 





 





 





 





 



 |  } else { 




902




 





 





 





 





 





 



 |      print "Object has not been inserted\n"; 




903




 





 





 





 





 





 



 |  } 




904




 





 





 





 





 





 



 | 




905




 





 





 





 





 





 



 |Returns true, or throws an exception on error. 




906




 





 





 





 





 





 



 | 




907




 





 





 





 





 





 



 [% END %] 




908




 





 





 





 





 





 



 |REMAINING ACCESSORS TO BE COMPLETED 




909




 





 





 





 





 





 



 | 




910




 





 





 





 





 





 



 |=head1 SQL 




911




 





 





 





 





 





 



 | 




912




 





 





 





 





 





 



 |The [% table.name %] table was originally created with the 




913




 





 





 





 





 





 



 |following SQL command. 




914




 





 





 





 





 





 



 | 




915




 





 





 





 





 





 



 |[%+ table.create | indent('  ') -%] 




916




 





 





 





 





 





 



 | 




917




 





 





 





 





 





 



 |=head1 SUPPORT 




918




 





 





 





 





 





 



 | 




919




 





 





 





 





 





 



 |[%+ pkg %] is part of the L<[% root %]> API. 




920




 





 





 





 





 





 



 | 




921




 





 





 





 





 





 



 |See the documentation for L<[% root %]> for more information. 




922




 





 





 





 





 





 



 | 




923




 





 





 





 





 





 



 [% IF self.author_pod %] 




924




 





 





 





 





 





 



 |=head1 AUTHOR 




925




 





 





 





 





 





 



 | 




926




 





 





 





 





 





 



 |[%+ self.author_pod %] 




927




 





 





 





 





 





 



 | 




928




 





 





 





 





 





 



 [% END %] 




929




 





 





 





 





 





 



 |=head1 COPYRIGHT 




930




 





 





 





 





 





 



 | 




931




 





 





 





 





 





 



 |Copyright [% self.copyyear %] [%+ self.author %]. 




932




 





 





 





 





 





 



 | 




933




 





 





 





 





 





 



 |This program is free software; you can redistribute 




934




 





 





 





 





 





 



 |it and/or modify it under the same terms as Perl itself. 




935




 





 





 





 





 





 



 | 




936




 





 





 





 





 





 



 |The full text of the license can be found in the 




937




 





 





 





 





 





 



 |LICENSE file included with this module. 




938




 





 





 





 





 





 



 | 




939




 





 





 





 





 





 



 END_TT 




940




 





 





 





 





 





 



   




941




 





 





 





 





 





 



 1; 




942




 





 





 





 





 





 



   




943




 





 





 





 





 





 



 =pod 




944




 





 





 





 





 





 



   




945




 





 





 





 





 





 



 =head1 SUPPORT 




946




 





 





 





 





 





 



   




947




 





 





 





 





 





 



 Bugs should be reported via the CPAN bug tracker at 




948




 





 





 





 





 





 



   




949




 





 





 





 





 





 



 L 




950




 





 





 





 





 





 



   




951




 





 





 





 





 





 



 For other issues, contact the author. 




952




 





 





 





 





 





 



   




953




 





 





 





 





 





 



 =head1 AUTHOR 




954




 





 





 





 





 





 



   




955




 





 





 





 





 





 



 Adam Kennedy [e-mail] 




956




 





 





 





 





 





 



   




957




 





 





 





 





 





 



 =head1 COPYRIGHT 




958




 





 





 





 





 





 



   




959




 





 





 





 





 





 



 Copyright 2009 - 2011 Adam Kennedy. 




960




 





 





 





 





 





 



   




961




 





 





 





 





 





 



 This program is free software; you can redistribute 




962




 





 





 





 





 





 



 it and/or modify it under the same terms as Perl itself. 




963




 





 





 





 





 





 



   




964




 





 





 





 





 





 



 The full text of the license can be found in the 




965




 





 





 





 





 





 



 LICENSE file included with this module. 




966




 





 





 





 





 





 



   




967




 





 





 





 





 





 



 =cut
|
[% END %]
[% IF method.load %]
|=head2 load
|
|  my $object = [% pkg %]->load( $[% table.pk %] );
|
|If your table has single column primary key, a C method will be
|generated in the class. If there is no primary key, the method is not
|created.
|
|The C method provides a shortcut mechanism for fetching a single
|object based on the value of the primary key. However it should only
|be used for cases where your code trusts the record to already exists.
|
|It returns a C<[% pkg %]> object, or throws an exception if the
|object does not exist.
|
[% END %]
[% IF method.select %]
|=head2 select
|
|  # Get all objects in list context
|  my @list = [% pkg %]->select;
|
|  # Get a subset of objects in scalar context
|  my $array_ref = [% pkg %]->select(
|      'where [% table.pk %] > ? order by [% table.pk %]',
|      1000,
|  );
|
|The C method executes a typical SQL C query on the
|[%+ table.name %] table.
|
|It takes an optional argument of a SQL phrase to be added after the
|C section of the query, followed by variables
|to be bound to the placeholders in the SQL phrase. Any SQL that is
|compatible with SQLite can be used in the parameter.
|
|Returns a list of B<[% pkg %]> objects when called in list context, or a
|reference to an C of B<[% pkg %]> objects when called in scalar
|context.
|
|Throws an exception on error, typically directly from the L layer.
|
[% END %]
[% IF method.iterate %]
|=head2 iterate
|
|  [%+ pkg %]->iterate( sub {
|      print $_->[% table.pk %] . "\n";
|  } );
|
|The C method enables the processing of large tables one record at
|a time without loading having to them all into memory in advance.
|
|This plays well to the strength of SQLite, allowing it to do the work of
|loading arbitrarily large stream of records from disk while retaining the
|full power of Perl when processing the records.
|
|The last argument to C must be a subroutine reference that will be
|called for each element in the list, with the object provided in the topic
|variable C<$_>.
|
|This makes the C code fragment above functionally equivalent to the
|following, except with an O(1) memory cost instead of O(n).
|
|  foreach ( [% pkg %]->select ) {
|      print $_->[% table.pk %] . "\n";
|  }
|
|You can filter the list via SQL in the same way you can with C.
|
|  [%+ pkg %]->iterate(
|      'order by ?', '[% table.pk %]',
|      sub {
|          print $_->[% table.pk %] . "\n";
|      }
|  );
|
|You can also use it in raw form from the root namespace for better control.
|Using this form also allows for the use of arbitrarily complex queries,
|including joins. Instead of being objects, rows are provided as C
|references when used in this form.
|
|  [%+ root %]->iterate(
|      'select name from [% table.name %] order by [% table.pk %]',
|      sub {
|          print $_->[0] . "\n";
|      }
|  );
|
[% END %]
[% IF method.count %]
|=head2 count
|
|  # How many objects are in the table
|  my $rows = [% pkg %]->count;
|
|  # How many objects
|  my $small = [% pkg %]->count(
|      'where [% table.pk %] > ?',
|      1000,
|  );
|
|The C method executes a C query on the
|[%+ table.name %] table.
|
|It takes an optional argument of a SQL phrase to be added after the
|C section of the query, followed by variables
|to be bound to the placeholders in the SQL phrase. Any SQL that is
|compatible with SQLite can be used in the parameter.
|
|Returns the number of objects that match the condition.
|
|Throws an exception on error, typically directly from the L layer.
|
[% END %]
[% IF method.new %]
|=head2 new
|
|  TO BE COMPLETED
|
|The C constructor is used to create a new abstract object that
|is not (yet) written to the database.
|
|Returns a new L<[% pkg %]> object.
|
[% END %]
[% IF method.create %]
|=head2 create
|
|  my $object = [% pkg %]->create(
|[%- FOREACH column IN table.columns %]
|      [%+ column.name %] => 'value',
|[%- END %]
|  );
|
|The C constructor is a one-step combination of C and
|C that takes the column parameters, creates a new
|L<[% pkg %]> object, inserts the appropriate row into the
|L<[% table.name %]> table, and then returns the object.
|
|If the primary key column C<[% table.pk %]> is not provided to the
|constructor (or it is false) the object returned will have
|C<[% table.pk %]> set to the new unique identifier.
|
|Returns a new L<[% table.name %]> object, or throws an exception on
|error, typically from the L layer.
|
[% END %]
[% IF method.insert %]
|=head2 insert
|
|  $object->insert;
|
|The C method commits a new object (created with the C method)
|into the database.
|
|If a the primary key column C<[% table.pk %]> is not provided to the
|constructor (or it is false) the object returned will have
|C<[% table.pk %]> set to the new unique identifier.
|
|Returns the object itself as a convenience, or throws an exception
|on error, typically from the L layer.
|
[% END %]
[% IF method.delete %]
|=head2 delete
|
|  # Delete a single instantiated object
|  $object->delete;
|
|  # Delete multiple rows from the [% table.name %] table
|  [%+ pkg %]->delete('where [% table.pk %] > ?', 1000);
|
|The C method can be used in a class form and an instance form.
|
|When used on an existing B<[% pkg %]> instance, the C method
|removes that specific instance from the C<[% table.name %]>, leaving
|the object intact for you to deal with post-delete actions as you wish.
|
|When used as a class method, it takes a compulsory argument of a SQL
|phrase to be added after the C section
|of the query, followed by variables to be bound to the placeholders
|in the SQL phrase. Any SQL that is compatible with SQLite can be used
|in the parameter.
|
|Returns true on success or throws an exception on error, or if you
|attempt to call delete without a SQL condition phrase.
|
[% END %]
[% IF method.truncate %]
|=head2 truncate
|
|  # Delete all records in the [% table.name %] table
|  [%+ pkg %]->truncate;
|
|To prevent the common and extremely dangerous error case where
|deletion is called accidentally without providing a condition,
|the use of the C method without a specific condition
|is forbidden.
|
|Instead, the distinct method C is provided to delete
|all records in a table with specific intent.
|
|Returns true, or throws an exception on error.
|
[% END %]
|=head1 ACCESSORS
|
[% pk = table.pk %]
[% IF method.$pk %]
|=head2 [% pk %]
|
|  if ( $object->[% pk %] ) {
|      print "Object has been inserted\n";
|  } else {
|      print "Object has not been inserted\n";
|  }
|
|Returns true, or throws an exception on error.
|
[% END %]
|REMAINING ACCESSORS TO BE COMPLETED
|
|=head1 SQL
|
|The [% table.name %] table was originally created with the
|following SQL command.
|
|[%+ table.create | indent('  ') -%]
|
|=head1 SUPPORT
|
|[%+ pkg %] is part of the L<[% root %]> API.
|
|See the documentation for L<[% root %]> for more information.
|
[% IF self.author_pod %]
|=head1 AUTHOR
|
|[%+ self.author_pod %]
|
[% END %]
|=head1 COPYRIGHT
|
|Copyright [% self.copyyear %] [%+ self.author %].
|
|This program is free software; you can redistribute
|it and/or modify it under the same terms as Perl itself.
|
|The full text of the license can be found in the
|LICENSE file included with this module.
|
END_TT

1;

=pod

=head1 SUPPORT

Bugs should be reported via the CPAN bug tracker at

L

For other issues, contact the author.

=head1 AUTHOR

Adam Kennedy [e-mail]

=head1 COPYRIGHT

Copyright 2009 - 2011 Adam Kennedy.

This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the
LICENSE file included with this module.

=cut