Data-Page-2.02000755001750001750 011307255725 12164 5ustar00acmeacme000000000000META.yml000444001750001750 113211307255725 13510 0ustar00acmeacme000000000000Data-Page-2.02--- name: Data-Page version: 2.02 author: - |- Based on code originally by Leo Lapworth, with many changes added by by Leon Brocard . abstract: help when paging through sets of results license: perl resources: license: http://dev.perl.org/licenses/ requires: Class::Accessor::Chained::Fast: 0 Test::Exception: 0 Test::More: 0 configure_requires: Module::Build: 0.35 provides: Data::Page: file: lib/Data/Page.pm version: 2.02 generated_by: Module::Build version 0.35 meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: 1.4 README000444001750001750 1104711307255725 13145 0ustar00acmeacme000000000000Data-Page-2.02NAME Data::Page - help when paging through sets of results SYNOPSIS use Data::Page; my $page = Data::Page->new(); $page->total_entries($total_entries); $page->entries_per_page($entries_per_page); $page->current_page($current_page); print " First page: ", $page->first_page, "\n"; print " Last page: ", $page->last_page, "\n"; print "First entry on page: ", $page->first, "\n"; print " Last entry on page: ", $page->last, "\n"; DESCRIPTION When searching through large amounts of data, it is often the case that a result set is returned that is larger than we want to display on one page. This results in wanting to page through various pages of data. The maths behind this is unfortunately fiddly, hence this module. The main concept is that you pass in the number of total entries, the number of entries per page, and the current page number. You can then call methods to find out how many pages of information there are, and what number the first and last entries on the current page really are. For example, say we wished to page through the integers from 1 to 100 with 20 entries per page. The first page would consist of 1-20, the second page from 21-40, the third page from 41-60, the fourth page from 61-80 and the fifth page from 81-100. This module would help you work this out. METHODS new This is the constructor, which takes no arguments. my $page = Data::Page->new(); There is also an old, deprecated constructor, which currently takes two mandatory arguments, the total number of entries and the number of entries per page. It also optionally takes the current page number: my $page = Data::Page->new($total_entries, $entries_per_page, $current_page); total_entries This method get or sets the total number of entries: print "Entries:", $page->total_entries, "\n"; entries_per_page This method gets or sets the total number of entries per page (which defaults to 10): print "Per page:", $page->entries_per_page, "\n"; current_page This method gets or sets the current page number (which defaults to 1): print "Page: ", $page->current_page, "\n"; entries_on_this_page This methods returns the number of entries on the current page: print "There are ", $page->entries_on_this_page, " entries displayed\n"; first_page This method returns the first page. This is put in for reasons of symmetry with last_page, as it always returns 1: print "Pages range from: ", $page->first_page, "\n"; last_page This method returns the total number of pages of information: print "Pages range to: ", $page->last_page, "\n"; first This method returns the number of the first entry on the current page: print "Showing entries from: ", $page->first, "\n"; last This method returns the number of the last entry on the current page: print "Showing entries to: ", $page->last, "\n"; previous_page This method returns the previous page number, if one exists. Otherwise it returns undefined: if ($page->previous_page) { print "Previous page number: ", $page->previous_page, "\n"; } next_page This method returns the next page number, if one exists. Otherwise it returns undefined: if ($page->next_page) { print "Next page number: ", $page->next_page, "\n"; } splice This method takes in a listref, and returns only the values which are on the current page: @visible_holidays = $page->splice(\@holidays); skipped This method is useful paging through data in a database using SQL LIMIT clauses. It is simply $page->first - 1: $sth = $dbh->prepare( q{SELECT * FROM table ORDER BY rec_date LIMIT ?, ?} ); $sth->execute($date, $page->skipped, $page->entries_per_page); NOTES It has been said before that this code is "too simple" for CPAN, but I must disagree. I have seen people write this kind of code over and over again and they always get it wrong. Perhaps now they will spend more time getting the rest of their code right... SEE ALSO Related modules which may be of interest: Data::Pageset, Data::Page::Tied, Data::SpreadPagination. AUTHOR Based on code originally by Leo Lapworth, with many changes added by by Leon Brocard . COPYRIGHT Copyright (C) 2000-8, Leon Brocard LICENSE This module is free software; you can redistribute it or modify it under the same terms as Perl itself. Makefile.PL000444001750001750 101411307255725 14210 0ustar00acmeacme000000000000Data-Page-2.02# Note: this file was auto-generated by Module::Build::Compat version 0.35 use ExtUtils::MakeMaker; WriteMakefile ( 'PL_FILES' => {}, 'INSTALLDIRS' => 'site', 'NAME' => 'Data::Page', 'EXE_FILES' => [], 'VERSION_FROM' => 'lib/Data/Page.pm', 'PREREQ_PM' => { 'Test::More' => '0', 'Class::Accessor::Chained::Fast' => '0', 'Test::Exception' => '0' } ) ; NINJA000444001750001750 20711307255725 13003 0ustar00acmeacme000000000000Data-Page-2.02--- #YAML:1.0 attributes: charisma: 0.07 constitution: 1.00 dexterity: 1.00 intelligence: 0.00 strength: 0.87 wisdom: 0.33 MANIFEST.SKIP000444001750001750 25711307255725 14124 0ustar00acmeacme000000000000Data-Page-2.02_build Build$ blib ~$ \.bak$ ^MANIFEST\.SKIP$ CVS ^Makefile$ ^MakeMaker-\d \.old$ ^#.*#$ ^\.# \.# #$ \B\.svn\b \.bs$ \.c$ \.o$ pm_to_blib unpacked # autogenerated SIGNATURE CHANGES000444001750001750 357711307255725 13251 0ustar00acmeacme000000000000Data-Page-2.02Revision history for Perl module Data::Page: 2.02 Mon Dec 7 19:45:33 GMT 2009 - fix SQL documentation, spotted by Terrence Brannon - added change_entries_per_page, patch by James Laver (ELPENGUIN) - run perltidy on the modules 2.01 Wed Oct 8 15:02:25 BST 2008 - add human-readable license to the documentation 2.00 Wed Oct 20 16:30:04 BST 2004 - added accessors, deprecated old constructor style - updated the documentation 1.03 Tue Jul 20 16:12:50 CEST 2004 - added skipped thanks to Valerio 1.02 Sun Jul 11 16:03:12 IST 2004 - NO NEW FUNCTIONALITY OR BUG FIXES. - Removed the $proto||ref($proto) in the constructor. This means that you can't do my $pager2 = $pager1->new(); but you never wanted to do that anyway. - Added new t/constructor.t to check constructor errors. - Added t/pod.t and t/pod-coverage.t. - Added some tests to t/simple.t. - Test coverage is now at 100% according to Devel::Cover. - (all thanks to Andy Lester) 1.01 Wed Nov 19 10:09:48 GMT 2003 - fixed bug where splice of an empty array was not working (spotted by Alex Monney) - moved Changes to CHANGES 1.00 Mon Nov 3 19:41:21 GMT 2003 - bumped up to version 1.00 and added NINJA support 0.18 Mon Jul 14 19:31:08 BST 2003 - patches by Ken Williams to simplify the code and fix the tests 0.17 Mon May 5 16:12:58 BST 2003 - work around for makemaker and Build.PL interaction 0.16 Sun May 4 11:02:33 BST 2003 - New entries_on_this_page thanks to Dominic Mitchell 0.15 Tue Feb 11 11:15:06 GMT 2003 - do the right thing with zero entries 0.14 Tue Aug 20 10:08:45 GMT 2002 - Added splice method 0.13 Fri Aug 16 10:13:02 BST 2002 - New previous_page and next_page thanks to Tatsuhiko Miyagawa 0.12 Tue Aug 28 12:52:48 2001 - Finally released to CPAN 0.02 2000-11-03 - Made into an OO module (+ many changes) by Leon Brocard 0.01 2001-11-02 - Created by Leo Lapworth MANIFEST000444001750001750 21711307255725 13353 0ustar00acmeacme000000000000Data-Page-2.02Build.PL CHANGES Makefile.PL MANIFEST MANIFEST.SKIP META.yml NINJA README lib/Data/Page.pm t/constructor.t t/pod-coverage.t t/simple.t t/pod.t Build.PL000444001750001750 56311307255725 13522 0ustar00acmeacme000000000000Data-Page-2.02use Module::Build; use strict; my $build = Module::Build->new( create_makefile_pl => 'traditional', license => 'perl', module_name => 'Data::Page', requires => { 'Test::More' => '0', 'Class::Accessor::Chained::Fast' => '0', 'Test::Exception' => '0', }, ); $build->create_build_script; lib000755001750001750 011307255725 12653 5ustar00acmeacme000000000000Data-Page-2.02Data000755001750001750 011307255725 13524 5ustar00acmeacme000000000000Data-Page-2.02/libPage.pm000444001750001750 2022211307255725 15111 0ustar00acmeacme000000000000Data-Page-2.02/lib/Datapackage Data::Page; use Carp; use strict; use base 'Class::Accessor::Chained::Fast'; __PACKAGE__->mk_accessors(qw(total_entries entries_per_page current_page)); use vars qw($VERSION); $VERSION = '2.02'; sub new { my $class = shift; my $self = {}; bless( $self, $class ); my ( $total_entries, $entries_per_page, $current_page ) = @_; $self->total_entries( $total_entries || 0 ); $self->entries_per_page( $entries_per_page || 10 ); $self->current_page( $current_page || 1 ); return $self; } sub entries_per_page { my $self = shift; my $entries_per_page = $_[0]; if (@_) { croak("Fewer than one entry per page!") if $entries_per_page < 1; return $self->_entries_per_page_accessor(@_); } return $self->_entries_per_page_accessor(); } sub current_page { my $self = shift; if (@_) { return $self->_current_page_accessor(@_); } return $self->first_page unless defined $self->_current_page_accessor; return $self->first_page if $self->_current_page_accessor < $self->first_page; return $self->last_page if $self->_current_page_accessor > $self->last_page; return $self->_current_page_accessor(); } sub total_entries { my $self = shift; if (@_) { return $self->_total_entries_accessor(@_); } return $self->_total_entries_accessor; } sub entries_on_this_page { my $self = shift; if ( $self->total_entries == 0 ) { return 0; } else { return $self->last - $self->first + 1; } } sub first_page { my $self = shift; return 1; } sub last_page { my $self = shift; my $pages = $self->total_entries / $self->entries_per_page; my $last_page; if ( $pages == int $pages ) { $last_page = $pages; } else { $last_page = 1 + int($pages); } $last_page = 1 if $last_page < 1; return $last_page; } sub first { my $self = shift; if ( $self->total_entries == 0 ) { return 0; } else { return ( ( $self->current_page - 1 ) * $self->entries_per_page ) + 1; } } sub last { my $self = shift; if ( $self->current_page == $self->last_page ) { return $self->total_entries; } else { return ( $self->current_page * $self->entries_per_page ); } } sub previous_page { my $self = shift; if ( $self->current_page > 1 ) { return $self->current_page - 1; } else { return undef; } } sub next_page { my $self = shift; $self->current_page < $self->last_page ? $self->current_page + 1 : undef; } # This method would probably be better named 'select' or 'slice' or # something, because it doesn't modify the array the way # CORE::splice() does. sub splice { my ( $self, $array ) = @_; my $top = @$array > $self->last ? $self->last : @$array; return () if $top == 0; # empty return @{$array}[ $self->first - 1 .. $top - 1 ]; } sub skipped { my $self = shift; my $skipped = $self->first - 1; return 0 if $skipped < 0; return $skipped; } sub change_entries_per_page { my ( $self, $new_epp ) = @_; use integer; croak("Fewer than one entry per page!") if $new_epp < 1; my $new_page = 1 + ( $self->first / $new_epp ); $self->entries_per_page($new_epp); $self->current_page($new_page); } 1; __END__ =head1 NAME Data::Page - help when paging through sets of results =head1 SYNOPSIS use Data::Page; my $page = Data::Page->new(); $page->total_entries($total_entries); $page->entries_per_page($entries_per_page); $page->current_page($current_page); print " First page: ", $page->first_page, "\n"; print " Last page: ", $page->last_page, "\n"; print "First entry on page: ", $page->first, "\n"; print " Last entry on page: ", $page->last, "\n"; =head1 DESCRIPTION When searching through large amounts of data, it is often the case that a result set is returned that is larger than we want to display on one page. This results in wanting to page through various pages of data. The maths behind this is unfortunately fiddly, hence this module. The main concept is that you pass in the number of total entries, the number of entries per page, and the current page number. You can then call methods to find out how many pages of information there are, and what number the first and last entries on the current page really are. For example, say we wished to page through the integers from 1 to 100 with 20 entries per page. The first page would consist of 1-20, the second page from 21-40, the third page from 41-60, the fourth page from 61-80 and the fifth page from 81-100. This module would help you work this out. =head1 METHODS =head2 new This is the constructor, which takes no arguments. my $page = Data::Page->new(); There is also an old, deprecated constructor, which currently takes two mandatory arguments, the total number of entries and the number of entries per page. It also optionally takes the current page number: my $page = Data::Page->new($total_entries, $entries_per_page, $current_page); =head2 total_entries This method get or sets the total number of entries: print "Entries:", $page->total_entries, "\n"; =head2 entries_per_page This method gets or sets the total number of entries per page (which defaults to 10): print "Per page:", $page->entries_per_page, "\n"; =head2 current_page This method gets or sets the current page number (which defaults to 1): print "Page: ", $page->current_page, "\n"; =head2 entries_on_this_page This methods returns the number of entries on the current page: print "There are ", $page->entries_on_this_page, " entries displayed\n"; =head2 first_page This method returns the first page. This is put in for reasons of symmetry with last_page, as it always returns 1: print "Pages range from: ", $page->first_page, "\n"; =head2 last_page This method returns the total number of pages of information: print "Pages range to: ", $page->last_page, "\n"; =head2 first This method returns the number of the first entry on the current page: print "Showing entries from: ", $page->first, "\n"; =head2 last This method returns the number of the last entry on the current page: print "Showing entries to: ", $page->last, "\n"; =head2 previous_page This method returns the previous page number, if one exists. Otherwise it returns undefined: if ($page->previous_page) { print "Previous page number: ", $page->previous_page, "\n"; } =head2 next_page This method returns the next page number, if one exists. Otherwise it returns undefined: if ($page->next_page) { print "Next page number: ", $page->next_page, "\n"; } =head2 splice This method takes in a listref, and returns only the values which are on the current page: @visible_holidays = $page->splice(\@holidays); =head2 skipped This method is useful paging through data in a database using SQL LIMIT clauses. It is simply $page->first - 1: $sth = $dbh->prepare( q{SELECT * FROM table ORDER BY rec_date LIMIT ?, ?} ); $sth->execute($page->skipped, $page->entries_per_page); =head2 change_entries_per_page This method changes the number of entries per page and the current page number such that the L item on the current page will be present on the new page. $page->total_entries(50); $page->entries_per_page(20); $page->current_page(3); print $page->first; # 41 $page->change_entries_per_page(30); print $page->current_page; # 2 - the page that item 41 will show in =head1 NOTES It has been said before that this code is "too simple" for CPAN, but I must disagree. I have seen people write this kind of code over and over again and they always get it wrong. Perhaps now they will spend more time getting the rest of their code right... =head1 SEE ALSO Related modules which may be of interest: L, L, L. =head1 AUTHOR Based on code originally by Leo Lapworth, with many changes added by by Leon Brocard . =head1 CONTRIBUTORS James Laver (ELPENGUIN) =head1 COPYRIGHT Copyright (C) 2000-9, Leon Brocard =head1 LICENSE This module is free software; you can redistribute it or modify it under the same terms as Perl itself. t000755001750001750 011307255725 12350 5ustar00acmeacme000000000000Data-Page-2.02pod.t000444001750001750 21411307255725 13431 0ustar00acmeacme000000000000Data-Page-2.02/t#!perl -T use Test::More; eval "use Test::Pod 1.14"; plan skip_all => "Test::Pod 1.14 required for testing POD" if $@; all_pod_files_ok(); pod-coverage.t000444001750001750 25411307255725 15226 0ustar00acmeacme000000000000Data-Page-2.02/t#!perl -T use Test::More; eval "use Test::Pod::Coverage 1.04"; plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@; all_pod_coverage_ok(); constructor.t000444001750001750 264611307255725 15267 0ustar00acmeacme000000000000Data-Page-2.02/t#!perl -T use warnings; use strict; use Test::More tests => 23; use Test::Exception; use_ok('Data::Page'); my $page = Data::Page->new(7, 10, 12); isa_ok($page, 'Data::Page'); is($page->first_page, 1, "Adjusted to first possible page"); $page = Data::Page->new(0, 10, -1); isa_ok($page, 'Data::Page'); is($page->first_page, 1, "Adjusted to first possible page"); throws_ok { my $page = Data::Page->new(12, -1, 1); } qr/one entry per page/, "Can't have entries-per-page less than 1"; # The new empty constructor means we might be empty, let's check for sensible defaults $page = Data::Page->new; is($page->entries_per_page, 10); is($page->total_entries, 0); is($page->entries_on_this_page, 0); is($page->first_page, 1); is($page->last_page, 1); is($page->first, 0); is($page->last, 0); is($page->previous_page, undef); is($page->current_page, 1); is($page->next_page, undef); is($page->skipped, 0); my @integers = (0 .. 100); @integers = $page->splice(\@integers); my $integers = join ',', @integers; is($integers, ''); $page->current_page(undef); is($page->current_page, 1); $page->current_page(-5); is($page->current_page, 1); $page->current_page(5); is($page->current_page, 1); $page->total_entries(100); $page->entries_per_page(20); $page->current_page(2); is($page->first, 21); $page->current_page(3); is($page->first, 41); simple.t000444001750001750 1073511307255725 14211 0ustar00acmeacme000000000000Data-Page-2.02/t#!/usr/bin/perl -wT use strict; use Test::More tests => 843; use_ok('Data::Page'); my $name; foreach my $line () { chomp $line; next unless $line; if ( $line =~ /^# ?(.+)/ ) { $name = $1; next; } print "Line is: $line\n"; my @vals = map { /^undef$/ ? undef : /^''$/ ? '' : $_ } split /\s+/, $line; my $page = Data::Page->new( @vals[ 0, 1, 2 ] ); print "Old style\n"; check( $page, $name, @vals ); $page = Data::Page->new(); $page->total_entries( $vals[0] ); $page->entries_per_page( $vals[1] ); $page->current_page( $vals[2] ); print "New style\n"; check( $page, $name, @vals ); } my $page = Data::Page->new( 0, 10 ); isa_ok( $page, 'Data::Page' ); my @empty; my @spliced = $page->splice( \@empty ); is( scalar(@spliced), 0, "Splice on empty is empty" ); sub check { my ( $page, $name, @vals ) = @_; isa_ok( $page, 'Data::Page' ); is( $page->first_page, $vals[3], "$name: first page" ); is( $page->last_page, $vals[4], "$name: last page" ); is( $page->first, $vals[5], "$name: first" ); is( $page->last, $vals[6], "$name: last" ); is( $page->previous_page, $vals[7], "$name: previous_page" ); is( $page->current_page, $vals[8], "$name: current_page" ); is( $page->next_page, $vals[9], "$name: next_page" ); my @integers = ( 0 .. $vals[0] - 1 ); @integers = $page->splice( \@integers ); my $integers = join ',', @integers; is( $integers, $vals[10], "$name: splice" ); is( $page->entries_on_this_page, $vals[11], "$name: entries_on_this_page" ); my $skipped = $vals[5] - 1; $skipped = 0 if $skipped < 0; is( $page->skipped, $skipped, "$name: skipped" ); $page->change_entries_per_page( $vals[12] ); is( $page->current_page, $vals[13], "$name: change_entries_per_page" ); } # Format of test data: 0=number of entries, 1=entries per page, 2=current page, # 3=first page, 4=last page, 5=first entry on page, 6=last entry on page, # 7=previous page, 8=current page, 9=next page, 10=current entries, # 11=current number of entries, 12=new entries per page, 13=new page __DATA__ # Initial test 50 10 1 1 5 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 15 1 50 10 2 1 5 11 20 1 2 3 10,11,12,13,14,15,16,17,18,19 10 15 1 50 10 3 1 5 21 30 2 3 4 20,21,22,23,24,25,26,27,28,29 10 15 2 50 10 4 1 5 31 40 3 4 5 30,31,32,33,34,35,36,37,38,39 10 15 3 50 10 5 1 5 41 50 4 5 undef 40,41,42,43,44,45,46,47,48,49 10 15 3 # Under 10 1 10 1 1 1 1 1 undef 1 undef 0 1 15 1 2 10 1 1 1 1 2 undef 1 undef 0,1 2 15 1 3 10 1 1 1 1 3 undef 1 undef 0,1,2 3 15 1 4 10 1 1 1 1 4 undef 1 undef 0,1,2,3 4 15 1 5 10 1 1 1 1 5 undef 1 undef 0,1,2,3,4 5 15 1 6 10 1 1 1 1 6 undef 1 undef 0,1,2,3,4,5 6 15 1 7 10 1 1 1 1 7 undef 1 undef 0,1,2,3,4,5,6 7 15 1 8 10 1 1 1 1 8 undef 1 undef 0,1,2,3,4,5,6,7 8 15 1 9 10 1 1 1 1 9 undef 1 undef 0,1,2,3,4,5,6,7,8 9 15 1 10 10 1 1 1 1 10 undef 1 undef 0,1,2,3,4,5,6,7,8,9 10 15 1 # Over 10 11 10 1 1 2 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 10 1 11 10 2 1 2 11 11 1 2 undef 10 1 10 2 12 10 1 1 2 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 10 1 12 10 2 1 2 11 12 1 2 undef 10,11 2 10 2 13 10 1 1 2 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 10 1 13 10 2 1 2 11 13 1 2 undef 10,11,12 3 10 2 # Under 20 19 10 1 1 2 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 4 1 19 10 2 1 2 11 19 1 2 undef 10,11,12,13,14,15,16,17,18 9 4 3 20 10 1 1 2 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 4 1 20 10 2 1 2 11 20 1 2 undef 10,11,12,13,14,15,16,17,18,19 10 4 3 # Over 20 21 10 1 1 3 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 19 1 21 10 2 1 3 11 20 1 2 3 10,11,12,13,14,15,16,17,18,19 10 19 1 21 10 3 1 3 21 21 2 3 undef 20 1 19 2 22 10 1 1 3 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 19 1 22 10 2 1 3 11 20 1 2 3 10,11,12,13,14,15,16,17,18,19 10 19 1 22 10 3 1 3 21 22 2 3 undef 20,21 2 19 2 23 10 1 1 3 1 10 undef 1 2 0,1,2,3,4,5,6,7,8,9 10 19 1 23 10 2 1 3 11 20 1 2 3 10,11,12,13,14,15,16,17,18,19 10 19 1 23 10 3 1 3 21 23 2 3 undef 20,21,22 3 19 2 # Zero test 0 10 1 1 1 0 0 undef 1 undef '' 0 5 1