From: Rob Kinyon <rob.kinyon@gmail.com>
Date: Thu, 24 Feb 2005 15:43:19 +0000 (+0000)
Subject: Intermediate commit - just have to add/fix POD for two classes, then done
X-Git-Tag: v0.21~3
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6dd4c89d686d215eb0de41e8a2f7805bfc7eb188;p=p5sagit%2FExcel-Template.git

Intermediate commit - just have to add/fix POD for two classes, then done
---

diff --git a/lib/Excel/Template.pm b/lib/Excel/Template.pm
index d157cdb..1dbfb9a 100644
--- a/lib/Excel/Template.pm
+++ b/lib/Excel/Template.pm
@@ -6,7 +6,7 @@ BEGIN {
     use Excel::Template::Base;
     use vars qw ($VERSION @ISA);
 
-    $VERSION  = '0.20';
+    $VERSION  = '0.21';
     @ISA      = qw( Excel::Template::Base );
 }
 
@@ -14,6 +14,16 @@ use File::Basename;
 use XML::Parser;
 use IO::Scalar;
 
+use constant RENDER_NML => 'normal';
+use constant RENDER_BIG => 'big';
+use constant RENDER_XML => 'xml';
+
+my %renderers = (
+    RENDER_NML, 'Spreadsheet::WriteExcel',
+    RENDER_BIG, 'Spreadsheet::WriteExcel::Big',
+    RENDER_XML, 'Spreadsheet::WriteExcelXML',
+);
+
 sub new
 {
     my $class = shift;
@@ -23,14 +33,22 @@ sub new
         if defined $self->{FILENAME};
 
     my @renderer_classes = ( 'Spreadsheet::WriteExcel' );
-    if (exists $self->{BIG_FILE} && $self->{BIG_FILE})
+
+    if (exists $self->{RENDERER} && $self->{RENDERER})
     {
-        unshift @renderer_classes, 'Spreadsheet::WriteExcel::Big';
+        if (exists $renderers{ lc $self->{RENDERER} })
+        {
+            unshift @renderer_classes, $renderers{ lc $self->{RENDERER} };
+        }
+        elsif ($^W)
+        {
+            warn "'$self->{RENDERER}' is not recognized\n";
+        }
     }
-
-    if (exists $self->{XML} && $self->{XML})
+    elsif (exists $self->{BIG_FILE} && $self->{BIG_FILE})
     {
-        unshift @renderer_classes, 'Spreadsheet::WriteExcelXML';
+        warn "Use of BIG_FILE is deprecated.\n";
+        unshift @renderer_classes, 'Spreadsheet::WriteExcel::Big';
     }
 
     $self->{RENDERER} = undef;
@@ -120,7 +138,7 @@ sub parse_xml
 
                 my $name = uc shift;
 
-                my $node = Excel::Template::Factory->create_node($name, @_);
+                my $node = Excel::Template::Factory->_create_node($name, @_);
                 die "'$name' (@_) didn't make a node!\n" unless defined $node;
 
                 if ( $node->isa( 'WORKBOOK' ) )
@@ -186,7 +204,7 @@ sub _prepare_output
     my $self = shift;
     my ($xls) = @_;
 
-    my $context = Excel::Template::Factory->create(
+    my $context = Excel::Template::Factory->_create(
         'CONTEXT',
 
         XLS       => $xls,
@@ -275,13 +293,33 @@ This creates a Excel::Template object. If passed a FILENAME parameter, it will
 parse the template in the given file. (You can also use the parse() method,
 described below.)
 
-new() accepts an optional BIG_FILE parameter. This will attempt to change the
-renderer from L<Spreadsheet::WriteExcel> to L<Spreadsheet::WriteExcel::Big>. You
-must already have L<OLE::Storage_Lite> (required by Spreadsheet::WriteExcel::Big) installed on your system.
+=head3 Parameters
+
+=over 4
+
+=item * RENDERER
+
+The default rendering engine is Spreadsheet::WriteExcel. You may, if you choose, change that to another choice. The legal values are:
+
+=over 4
+
+=item * Excel::Template->RENDER_NML
+
+This is the default of Spreadsheet::WriteExcel.
 
-new() also accepts an optional USE_UNICODE parameter. This will use
-L<Unicode::String> to represent strings instead of Perl's internal string
-handling. You must already have L<Unicode::String> installed on your system.
+=item * Excel::Template->RENDER_BIG
+
+This attempts to load Spreadsheet::WriteExcel::Big.
+
+=item * Excel::Template->RENDER_XML
+
+This attempts to load Spreadsheet::WriteExcelXML.
+
+=back
+
+=item * USE_UNICODE
+
+This will use L<Unicode::String> to represent strings instead of Perl's internal string handling. You must already have L<Unicode::String> installed on your system.
 
 The USE_UNICODE parameter will be ignored if you are using Perl 5.8 or higher as
 Perl's internal string handling is unicode-aware.
@@ -290,6 +328,18 @@ NOTE: Certain older versions of L<OLE::Storage_Lite> and mod_perl clash for some
 reason. Upgrading to the latest version of L<OLE::Storage_Lite> should fix the
 problem.
 
+=back
+
+=head3 Deprecated
+
+=over 4
+
+=item * BIG_FILE
+
+Instead, use RENDERER => Excel::Template->RENDER_BIG
+
+=back
+
 =head2 param()
 
 This method is exactly like L<HTML::Template>'s param() method.
@@ -311,6 +361,10 @@ It will act just like HTML::Template's output() method, returning the resultant
 file as a stream, usually for output to the web. (This is when the actual
 merging of the template and the parameters occurs.)
 
+=head2 register()
+
+This allows you to register a class as handling a node. q.v. L<Excel::Template::Factory> for more info.
+
 =head1 SUPPORTED NODES
 
 This is a partial list of nodes. See the other classes in this distro for more
@@ -371,7 +425,7 @@ This is a BACKREF for a number of identically-named cells.
 This is a variable. It is generally used when the 'text' attribute isn't
 sufficient.
 
-=back 4
+=back
 
 =head1 BUGS
 
@@ -398,7 +452,7 @@ Robert Graff -
 
 =item * Fixing several bugs in worksheet naming
 
-=back 4
+=back
 
 =head1 COPYRIGHT
 
diff --git a/lib/Excel/Template/Base.pm b/lib/Excel/Template/Base.pm
index 9215ac5..082c2f0 100644
--- a/lib/Excel/Template/Base.pm
+++ b/lib/Excel/Template/Base.pm
@@ -77,3 +77,47 @@ sub render
 
 1;
 __END__
+
+=head1 NAME
+
+Excel::Template::Base - Excel::Template::Base
+
+=head1 PURPOSE
+
+Base class for all Excel::Template classes
+
+=head1 NODE NAME
+
+None
+
+=head1 INHERITANCE
+
+None
+
+=head1 ATTRIBUTES
+
+None
+
+=head1 CHILDREN
+
+None
+
+=head1 EFFECTS
+
+None
+
+=head1 DEPENDENCIES
+
+None
+
+=head1 METHODS
+
+None
+
+=head1 AUTHOR
+
+Rob Kinyon (rob.kinyon@gmail.com)
+
+=head1 SEE ALSO
+
+=cut
diff --git a/lib/Excel/Template/Container/Conditional.pm b/lib/Excel/Template/Container/Conditional.pm
index 1143a2c..45f9fb7 100644
--- a/lib/Excel/Template/Container/Conditional.pm
+++ b/lib/Excel/Template/Container/Conditional.pm
@@ -17,7 +17,7 @@ my %isOp = (
     (map { $_ => $_ } ( 'gt', 'lt', 'eq', 'ne', 'ge', 'le' )),
 );
 
-sub conditional_passes
+sub _conditional_passes
 {
     my $self = shift;
     my ($context) = @_;
@@ -82,7 +82,7 @@ sub render
     my $self = shift;
     my ($context) = @_;
 
-    return 1 unless $self->conditional_passes($context);
+    return 1 unless $self->_conditional_passes($context);
 
     return $self->iterate_over_children($context);
 }
@@ -92,7 +92,7 @@ sub max_of
     my $self = shift;
     my ($context, $attr) = @_;
 
-    return 0 unless $self->conditional_passes($context);
+    return 0 unless $self->_conditional_passes($context);
 
     return $self->SUPER::max_of($context, $attr);
 }
@@ -102,7 +102,7 @@ sub total_of
     my $self = shift;
     my ($context, $attr) = @_;
 
-    return 0 unless $self->conditional_passes($context);
+    return 0 unless $self->_conditional_passes($context);
 
     return $self->SUPER::total_of($context, $attr);
 }
@@ -151,7 +151,7 @@ string comparison operators. All 6 of each kind is supported.
 If VALUE is not set, then IS is checked. IS is allowed to be either "TRUE" or
 "FALSE". The boolean value of NAME is checked against IS.
 
-=back 4
+=back
 
 =head1 CHILDREN
 
diff --git a/lib/Excel/Template/Container/Format.pm b/lib/Excel/Template/Container/Format.pm
index c272e15..6548b28 100644
--- a/lib/Excel/Template/Container/Format.pm
+++ b/lib/Excel/Template/Container/Format.pm
@@ -52,12 +52,11 @@ Excel::Template::Container
 
 =head1 ATTRIBUTES
 
-=over 4
-
 Boolean attributes should be set to 1, 0, true, or false.
 
 Color values can be the color name or the color index. See http://search.cpan.org/~jmcnamara/Spreadsheet-WriteExcel-2.11/lib/Spreadsheet/WriteExcel.pm#COLOURS_IN_EXCEL
 
+=over 4
 
 =item * align
 
@@ -193,7 +192,7 @@ See border_color
 
 Set to top, vcenter, bottom, or vjustify. Default is vcenter. See also align.
 
-=back 4
+=back
 
 =head1 CHILDREN
 
diff --git a/lib/Excel/Template/Container/Loop.pm b/lib/Excel/Template/Container/Loop.pm
index 16e0cbc..31cd63c 100644
--- a/lib/Excel/Template/Container/Loop.pm
+++ b/lib/Excel/Template/Container/Loop.pm
@@ -26,12 +26,12 @@ sub new
     return $self;
 }
 
-sub make_iterator
+sub _make_iterator
 {
     my $self = shift;
     my ($context) = @_;
 
-    return Excel::Template::Factory->create('ITERATOR',
+    return Excel::Template::Factory->_create('ITERATOR',
         NAME     => $context->get($self, 'NAME'),
         MAXITERS => $context->get($self, 'MAXITERS'),
         CONTEXT  => $context,
@@ -45,7 +45,7 @@ sub render
 
     unless ($self->{ITERATOR} && $self->{ITERATOR}->more_params)
     {
-        $self->{ITERATOR} = $self->make_iterator($context);
+        $self->{ITERATOR} = $self->_make_iterator($context);
     }
     my $iterator = $self->{ITERATOR};
 
@@ -74,7 +74,7 @@ sub total_of
     my $self = shift;
     my ($context, $attr) = @_;
 
-    my $iterator = $self->make_iterator($context);
+    my $iterator = $self->_make_iterator($context);
 
     my $total = 0;
 
@@ -94,7 +94,7 @@ sub max_of
     my $self = shift;
     my ($context, $attr) = @_;
 
-    my $iterator = $self->make_iterator($context);
+    my $iterator = $self->_make_iterator($context);
 
     my $max = $context->get($self, $attr);
 
@@ -139,7 +139,7 @@ Excel::Template::Container
 This is the name of the loop. It's used to identify within the parameter set
 what variables to expose to the children nodes each iteration.
 
-=back 4
+=back
 
 =head1 CHILDREN
 
diff --git a/lib/Excel/Template/Container/Row.pm b/lib/Excel/Template/Container/Row.pm
index f8834d1..b3067e6 100644
--- a/lib/Excel/Template/Container/Row.pm
+++ b/lib/Excel/Template/Container/Row.pm
@@ -67,7 +67,7 @@ Excel::Template::Container
 
 Sets the height of the row. The last setting for a given row will win out.
 
-=back 4
+=back
 
 =head1 CHILDREN
 
diff --git a/lib/Excel/Template/Container/Worksheet.pm b/lib/Excel/Template/Container/Worksheet.pm
index b91dc15..37a7839 100644
--- a/lib/Excel/Template/Container/Worksheet.pm
+++ b/lib/Excel/Template/Container/Worksheet.pm
@@ -59,7 +59,7 @@ value is set will be used as the password.
 
 This activates the HIDDEN and LOCKED nodes.
 
-=back 4
+=back
 
 =head1 CHILDREN
 
diff --git a/lib/Excel/Template/Element/Backref.pm b/lib/Excel/Template/Element/Backref.pm
index 0c34f90..c64188f 100755
--- a/lib/Excel/Template/Element/Backref.pm
+++ b/lib/Excel/Template/Element/Backref.pm
@@ -51,7 +51,7 @@ Excel::Template::Element
 
 This is the name of the reference to look up.
 
-=back 4
+=back
 
 =head1 CHILDREN
 
diff --git a/lib/Excel/Template/Element/Cell.pm b/lib/Excel/Template/Element/Cell.pm
index 1f5e8d4..08aece9 100755
--- a/lib/Excel/Template/Element/Cell.pm
+++ b/lib/Excel/Template/Element/Cell.pm
@@ -14,12 +14,12 @@ sub new
     my $class = shift;
     my $self = $class->SUPER::new(@_);
                                                                                 
-    $self->{TXTOBJ} = Excel::Template::Factory->create('TEXTOBJECT');
+    $self->{TXTOBJ} = Excel::Template::Factory->_create('TEXTOBJECT');
                                                                                 
     return $self;
 }
 
-sub get_text
+sub _get_text
 {
     my $self = shift;
     my ($context) = @_;
@@ -27,7 +27,7 @@ sub get_text
     my $txt = $context->get($self, 'TEXT');
     if (defined $txt)
     {
-        my $txt_obj = Excel::Template::Factory->create('TEXTOBJECT');
+        my $txt_obj = Excel::Template::Factory->_create('TEXTOBJECT');
         push @{$txt_obj->{STACK}}, $txt;
         $txt = $txt_obj->resolve($context);
     }
@@ -100,7 +100,7 @@ sub render
 
     $context->active_worksheet->$method(
         $row, $col,
-        $self->get_text($context),
+        $self->_get_text($context),
         $context->active_format,
     );
 
diff --git a/lib/Excel/Template/Element/Range.pm b/lib/Excel/Template/Element/Range.pm
index 7a9db99..d3a84d8 100755
--- a/lib/Excel/Template/Element/Range.pm
+++ b/lib/Excel/Template/Element/Range.pm
@@ -69,7 +69,7 @@ Excel::Template::Element
 
 This is the name of the reference to look up.
 
-=back 4
+=back
 
 =head1 CHILDREN
 
diff --git a/lib/Excel/Template/Element/Var.pm b/lib/Excel/Template/Element/Var.pm
index 74bfede..3d365fc 100644
--- a/lib/Excel/Template/Element/Var.pm
+++ b/lib/Excel/Template/Element/Var.pm
@@ -38,7 +38,7 @@ Excel::Template::Element
 
 This is the name of the parameter to substitute here.
 
-=back 4
+=back
 
 =head1 CHILDREN
 
diff --git a/lib/Excel/Template/Factory.pm b/lib/Excel/Template/Factory.pm
index 266adef..cdb465a 100644
--- a/lib/Excel/Template/Factory.pm
+++ b/lib/Excel/Template/Factory.pm
@@ -107,7 +107,7 @@ sub register
     return 1;
 }
 
-sub create
+sub _create
 {
     my $class = shift;
     my $name = uc shift;
@@ -125,14 +125,14 @@ sub create
     return $Manifest{$name}->new(@_);
 }
 
-sub create_node
+sub _create_node
 {
     my $class = shift;
     my $name = uc shift;
 
     return unless exists $isBuildable{$name};
 
-    return $class->create($name, @_);
+    return $class->_create($name, @_);
 }
 
 sub isa
@@ -147,7 +147,7 @@ sub is_embedded
 {
     return unless @_ >= 1;
 
-    isa( $_[0], $_ ) && return !!1 for qw( VAR BACKREF RANGE );
+    isa( $_[0], $_ ) && return ~~1 for qw( VAR BACKREF RANGE );
     return;
 }
 
@@ -170,6 +170,14 @@ Use this to register your own nodes.
 
 Example forthcoming.
 
+=head1 METHODS
+
+=head2 isa
+
+This is a customized isa() wrapper for syntactic sugar
+
+=head2 is_embedded
+
 =head1 AUTHOR
 
 Rob Kinyon (rob.kinyon@gmail.com)
diff --git a/lib/Excel/Template/Format.pm b/lib/Excel/Template/Format.pm
index 4854eb5..c164d0a 100644
--- a/lib/Excel/Template/Format.pm
+++ b/lib/Excel/Template/Format.pm
@@ -146,3 +146,55 @@ sub blank_format
 
 1;
 __END__
+
+=head1 NAME
+
+Excel::Template::Format - Excel::Template::Format
+
+=head1 PURPOSE
+
+Helper class for FORMAT
+
+=head1 NODE NAME
+
+None
+
+=head1 INHERITANCE
+
+None
+
+=head1 ATTRIBUTES
+
+None
+
+=head1 CHILDREN
+
+None
+
+=head1 EFFECTS
+
+None
+
+=head1 DEPENDENCIES
+
+None
+
+=head1 METHODS
+
+=head2 blank_format
+
+Provides a blank format for use
+
+=head2 copy
+
+Clones an existing format, so that a new format can be built from it
+
+=head1 AUTHOR
+
+Rob Kinyon (rob.kinyon@gmail.com)
+
+=head1 SEE ALSO
+
+FORMAT
+
+=cut
diff --git a/lib/Excel/Template/Iterator.pm b/lib/Excel/Template/Iterator.pm
index ee2d75d..593bf59 100644
--- a/lib/Excel/Template/Iterator.pm
+++ b/lib/Excel/Template/Iterator.pm
@@ -188,19 +188,55 @@ Excel::Template::Iterator
 
 =head1 PURPOSE
 
+This is meant for internal use only. Documentation is provided for subclassing.
+
 =head1 NODE NAME
 
+None
+
 =head1 INHERITANCE
 
+None
+
 =head1 ATTRIBUTES
 
+None
+
 =head1 CHILDREN
 
+None
+
 =head1 AFFECTS
 
+This is a helper class for LOOP
+
 =head1 DEPENDENCIES
 
-=head1 USAGE
+None
+
+=head1 METHODS
+
+=head2 back_up
+
+Go to the previous iteration of the loop
+
+=head2 can_continue
+
+Determines if the iterator can continue.
+
+Currently, this wraps more_params(), but there other possible situations, such as the page ending.
+
+=head2 more_params
+
+Determines if the iterator for the loop has more parameters that it can consume
+
+=head2 next
+
+Go to the next iteration of the loop
+
+=head2 reset
+
+Resets the iterator
 
 =head1 AUTHOR
 
@@ -208,4 +244,6 @@ Rob Kinyon (rob.kinyon@gmail.com)
 
 =head1 SEE ALSO
 
+LOOP
+
 =cut
diff --git a/t/016.xml b/t/016.xml
new file mode 100644
index 0000000..1f2269b
--- /dev/null
+++ b/t/016.xml
@@ -0,0 +1 @@
+<workbook />
diff --git a/t/016_renderers.t b/t/016_renderers.t
new file mode 100644
index 0000000..2213d1f
--- /dev/null
+++ b/t/016_renderers.t
@@ -0,0 +1,61 @@
+use strict;
+
+use Test::More tests => 10;
+
+use lib 't';
+use mock;
+
+my $CLASS = 'Excel::Template';
+use_ok( $CLASS );
+
+{
+    mock->reset;
+    my $object = $CLASS->new(
+        renderer => 'big',
+        filename => 't/016.xml',
+    );
+    isa_ok( $object, $CLASS );
+
+    ok( $object->write_file( 'filename' ), 'Something returned' );
+
+    my @calls = mock->get_calls;
+    is( join( $/, @calls, '' ), <<__END_EXPECTED__, 'Calls match up' );
+Spreadsheet::WriteExcel::Big::new( 'filename' )
+Spreadsheet::WriteExcel::Big::add_format( '' )
+Spreadsheet::WriteExcel::Big::close( '' )
+__END_EXPECTED__
+}
+
+{
+    mock->reset;
+    my $object = $CLASS->new(
+        renderer => Excel::Template->RENDER_XML,
+        filename => 't/016.xml',
+    );
+    isa_ok( $object, $CLASS );
+
+    ok( $object->write_file( 'filename' ), 'Something returned' );
+
+    my @calls = mock->get_calls;
+    is( join( $/, @calls, '' ), <<__END_EXPECTED__, 'Calls match up' );
+Spreadsheet::WriteExcelXML::new( 'filename' )
+Spreadsheet::WriteExcelXML::close( '' )
+__END_EXPECTED__
+}
+
+{
+    mock->reset;
+    my $object = $CLASS->new(
+        renderer => Excel::Template->RENDER_NML,
+        filename => 't/016.xml',
+    );
+    isa_ok( $object, $CLASS );
+
+    ok( $object->write_file( 'filename' ), 'Something returned' );
+
+    my @calls = mock->get_calls;
+    is( join( $/, @calls, '' ), <<__END_EXPECTED__, 'Calls match up' );
+Spreadsheet::WriteExcel::new( 'filename' )
+Spreadsheet::WriteExcel::close( '' )
+__END_EXPECTED__
+}
diff --git a/t/Spreadsheet/WriteExcel/Big.pm b/t/Spreadsheet/WriteExcel/Big.pm
new file mode 100644
index 0000000..ffbd25a
--- /dev/null
+++ b/t/Spreadsheet/WriteExcel/Big.pm
@@ -0,0 +1,25 @@
+package Spreadsheet::WriteExcel::Big;
+
+use strict;
+
+use vars qw/ @ISA /;
+@ISA = qw( Spreadsheet::WriteExcel );
+
+use Spreadsheet::WriteExcel;
+
+use mock;
+
+sub new {
+    my $self = bless {
+    }, shift;
+
+    {
+        local $" = "', '";
+        push @mock::calls, ref($self) . "::new( '@_' )";
+    }
+
+    return $self;
+}
+
+1;
+__END__
diff --git a/t/Spreadsheet/WriteExcelXML.pm b/t/Spreadsheet/WriteExcelXML.pm
new file mode 100644
index 0000000..d79b767
--- /dev/null
+++ b/t/Spreadsheet/WriteExcelXML.pm
@@ -0,0 +1,25 @@
+package Spreadsheet::WriteExcelXML;
+
+use strict;
+
+use vars qw/ @ISA /;
+@ISA = qw( Spreadsheet::WriteExcel );
+
+use Spreadsheet::WriteExcel;
+
+use mock;
+
+sub new {
+    my $self = bless {
+    }, shift;
+
+    {
+        local $" = "', '";
+        push @mock::calls, ref($self) . "::new( '@_' )";
+    }
+
+    return $self;
+}
+
+1;
+__END__
diff --git a/t/pod.t b/t/pod.t
new file mode 100644
index 0000000..cbe1402
--- /dev/null
+++ b/t/pod.t
@@ -0,0 +1,10 @@
+#!/usr/bin/perl
+
+use strict;
+
+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();
diff --git a/t/pod_coverage.t b/t/pod_coverage.t
new file mode 100644
index 0000000..8352506
--- /dev/null
+++ b/t/pod_coverage.t
@@ -0,0 +1,24 @@
+#!/usr/bin/perl
+
+use strict;
+
+use Test::More;
+
+eval "use Test::Pod::Coverage 1.04";
+plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@;
+
+# These are methods that need naming work
+my @private_methods = qw(
+    render new min max resolve deltas
+    begin_page end_page max_of total_of
+    enter_scope exit_scope iterate_over_children
+);
+
+my $private_regex = do {
+    local $"='|';
+    qr/^(?:@private_methods)$/
+};
+
+all_pod_coverage_ok( {
+    also_private => [ $private_regex ],
+});