[Bps-public-commit] template-declare branch, mixmaster_shuffle, created. 2829ccc56a6bb2fc0c2547e6f7d03cf9dc5830e9

jesse jesse at bestpractical.com
Fri Oct 16 17:48:48 EDT 2009


The branch, mixmaster_shuffle has been created
        at  2829ccc56a6bb2fc0c2547e6f7d03cf9dc5830e9 (commit)

- Log -----------------------------------------------------------------
commit 31c75274cecca2dd5bc5d8a60313896bd88106bf
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date:   Sat Oct 10 12:51:42 2009 +0000

    shuffle methods around

commit 8eda0b50e56f55cdb43ba26fa7f95e70f9f951c2
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date:   Sat Oct 10 12:53:41 2009 +0000

    shuffle methods for better POD and cleanup POD

diff --git a/lib/Template/Declare.pm b/lib/Template/Declare.pm
index 8e2755b..8ff47d3 100644
--- a/lib/Template/Declare.pm
+++ b/lib/Template/Declare.pm
@@ -45,27 +45,6 @@ sub roots {
     return [ reverse @{ $class->dispatch_to } ];
 }
 
-# Removed methods that no longer work (and were never documented anyway).
-# Remove these no-ops after a few releases (added for 0.41).
-
-=begin comment
-
-=head3 aliases
-
-=head3 alias_metadata
-
-=cut
-
-sub aliases {
-    require Carp;
-    Carp::cluck( 'aliases() is a deprecated no-op' );
-}
-
-sub alias_metadata {
-    require Carp;
-    Carp::cluck( 'alias_metadata() is a deprecated no-op' );
-}
-
 =head1 NAME
 
 Template::Declare - Perlish declarative templates
@@ -147,7 +126,7 @@ Public and private templates
 
 =head2 Basic usage
 
-A simple HTML example is in the L<SYNOPSIS/SYNOPSIS>. So let's do XUL!
+A simple HTML example is in the L</SYNOPSIS>. So let's do XUL!
 
     package MyApp::Templates;
     use base 'Template::Declare';
@@ -357,10 +336,6 @@ And the output:
  <h1>Hello</h1>
  <div>first post</div>
 
-=head2 Aliasing and Mixins
-
-=head2 Class Search Dispatching
-
 =head1 METHODS
 
 =head2 init
@@ -424,109 +399,139 @@ sub init {
 
 }
 
-=head2 buffer
+=head2 show TEMPLATE_NAME
 
-Gets or sets the L<String::BufferStack> object; this is a class method. You
-can use it to manipulate the output from tags as they are output. It's used
-internally to make the tags nest correctly, and be output to the right place.
-We're not sure if there's ever a need for you to frob it by hand, but it does
-enable things like the following:
+    Template::Declare->show( 'howdy', name => 'Larry' );
+    my $output = Template::Declare->show('index');
 
-    template simple => sub {
-       html {
-           head {}
-           body {
-               Template::Declare->buffer->set_filter( sub {uc shift} );
-               p { 'Whee!' }
-               p { 'Hello, world wide web!' }
-               Template::Declare->buffer->clear_top if rand() < 0.5;
-           }
-       }
-    };
+Call C<show> with a C<template_name> and C<Template::Declare> will render that
+template. Subsequent arguments will be passed to the template. Content
+generated by C<show()> can be accessed via the C<output()> method if the
+output method you've chosen returns content instead of outputting it directly.
 
-...which outputs, with equal regularity, either:
+If called in scalar context, this method will also just return the content
+when available.
 
- <html>
-  <head></head>
-  <body>
-   <P>WHEE!</P>
-   <P>HELLO, WORLD WIDE WEB!</P>
-  </body>
- </html>
+=cut
 
-...or:
+sub show {
+    my $class    = shift;
+    my $template = shift;
+    local %Template::Declare::Tags::ELEMENT_ID_CACHE = ();
+    return Template::Declare::Tags::show_page($template => @_);
+}
 
- <html>
-  <head></head>
-  <body></body>
- </html>
+=head2 Mixing templates
 
-We'll leave it to you to judge whether or not that's actually useful.
+Sometimes you want to mix templates from one class into another class;
+C<mix()> is your key to doing so.
 
-=head2 new_buffer_frame
+=head3 mix
 
-  $td->new_buffer_frame();
+    mix Some::Clever::Mixin      under '/mixin';
+    mix Some::Other::Mixin       under '/otmix', setting { name => 'Larry' };
+    mix My::Mixin into My::View, under '/mymix';
 
-Creates a new buffer frame, using L<String::BufferStack/push> with C<private>.
-This use is deprecated in favor of dealing with L</buffer> directly.
+In the first example, if Some::Clever::Mixin
+creates templates named C<foo> and C<bar>, they will be mixed into the calling
+template class as C<mixin/foo> and C<mixin/bar>.
 
-=cut
+The second example mixes in the templates defined in Some::Other::Mixin into
+into the calling class under the C</mymix> path. Furthermore, those mixed-in
+templates have package variables set for them that are accessible only from
+their mixed-in paths. For example, if this template was defined in
+Some::Other::Mixin:
 
-sub new_buffer_frame {
-    __PACKAGE__->buffer->push( private => 1 );
-}
+    template howdy => sub {
+        my $self = shift;
+        outs "Howdy, " . $self->package_variable('name') || 'Jesse';
+    };
+
+Then C<show('mymixin/howdy')> will output "Howdy, Larry", while the output
+from C<show('howdy')> will output "Howdy, Jesse". In other words, package
+variables defined for the mixed-in templates are available only to the mixins
+and not to the original.
+
+In either case, ineritance continues to work. A template package that inherits
+from Some::Other::Mixin, for example, will be able to access both
+C<mymixin/howdy> and C<howdy>.
+
+By default, C<mix()> will mix templates into the class from which it's called.
+But sometimes you might want to mix templates into some other template class.
+Such might be useful for end users to compose template structures from
+collections of template classes. In such a case, use the C<into> keyword to
+specify into what class the templates should be mixed in. The third example
+demonstrates this, where My::Mixin templates are mixed into My::View. Of
+course, you can still specify variables to set for those mixins.
 
-=head2 end_buffer_frame
+If you should happen to forget to pass the C<into> argument before C<under>,
+worry not, C<mix()> will figure it out and do the right thing.
 
-  my $buf = $td->end_buffer_frame();
+For those who prefer a direct OO syntax for mixins, just call C<mix()> as a
+method on the class to be mixed in. To replicate the above three exmaples
+without the use of the sugar:
 
-Deletes and returns the topmost buffer, using L<String::BufferStack/pop>. This
-use is deprecated in favor of dealing with L</buffer> directly..
+    Some::Clver::Mixin->mix( '/mixin' );
+    Some::Other::Mixin->mix( '/otmix', { name => 'Larry' } );
+    My::Mixin->mix('My::View', '/mymix');
 
 =cut
 
-sub end_buffer_frame {
-    __PACKAGE__->buffer->pop;
+sub mix {
+    my $mixin = shift;
+    my ($into, $under);
+    if ( eval { $_[0]->isa(__PACKAGE__) } ) {
+        ($into, $under) = (shift, shift);
+    } elsif ( eval { $_[1]->isa(__PACKAGE__) } ) {
+        ($under, $into) = (shift, shift);
+    } else {
+        $into  = caller(0);
+        $under = shift;
+    }
+    $mixin->_import($into, $under, @_);
 }
 
-=head2 show TEMPLATE_NAME
-
-    Template::Declare->show( 'howdy', name => 'Larry' );
-    my $output = Template::Declare->show('index');
+=head3 package_variable( VARIABLE )
 
-Call C<show> with a C<template_name> and C<Template::Declare> will render that
-template. Subsequent arguments will be passed to the template. Content
-generated by C<show()> can be accessed via the C<output()> method if the
-output method you've chosen returns content instead of outputting it directly.
+  $td->package_variable( $varname => $value );
+  $value = $td->package_variable( $varname );
 
-If called in scalar context, this method will also just return the content
-when available.
+Returns a value set for a mixed-in template's variable, if any were specified
+when the template was mixed-in. See L</mix> for details.
 
 =cut
 
-sub show {
-    my $class    = shift;
-    my $template = shift;
-    local %Template::Declare::Tags::ELEMENT_ID_CACHE = ();
-    return Template::Declare::Tags::show_page($template => @_);
+sub package_variable {
+    my $self = shift;
+    my $var  = shift;
+    if (@_) {
+        $TEMPLATE_VARS->{$self}->{$var} = shift;
+    }
+    return $TEMPLATE_VARS->{$self}->{$var};
 }
 
-=head2 path_for $template
+=head3 package_variables( VARIABLE )
 
-    my $path = Template::Declare->path_for('index');
+    $td->package_variables( $variables );
+    $variables = $td->package_variables;
 
-Returns the path for the template name to be used for show, adjusted with
-paths used in C<mix>.
+Get or set a hash reference of variables for a mixed-in template. See
+L</mix> for details.
 
 =cut
 
-sub path_for {
-    my $class = shift;
-    my $template = shift;
-    return ($class->imported_into ||'') . '/' . $template;
+sub package_variables {
+    my $self = shift;
+    if (@_) {
+        %{ $TEMPLATE_VARS->{$self} } = shift;
+    }
+    return $TEMPLATE_VARS->{$self};
 }
 
-=head2 resolve_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
+
+=head2 Templates registration and lookup
+
+=head3 resolve_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
 
     my $code = Template::Declare->resolve_template($template);
     my $code = Template::Declare->has_template($template, 1);
@@ -539,10 +544,6 @@ First it looks through all the valid Template::Declare classes defined via
 C<dispatch_to>. For each class, it looks to see if it has a template called
 $template_name directly (or via a mixin).
 
-=head2 has_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
-
-An alias for C<resolve_template>.
-
 =cut
 
 sub resolve_template {
@@ -568,9 +569,15 @@ sub resolve_template {
     }
 }
 
+=head3 has_template TEMPLATE_PATH INCLUDE_PRIVATE_TEMPLATES
+
+An alias for C<resolve_template>.
+
+=cut
+
 sub has_template { resolve_template(@_) }
 
-=head2 register_template( TEMPLATE_NAME, CODEREF )
+=head3 register_template( TEMPLATE_NAME, CODEREF )
 
     MyApp::Templates->register_template( howdy => sub { ... } );
 
@@ -589,7 +596,7 @@ sub register_template {
     _register_template( $class, _template_name_to_sub($template_name), $code )
 }
 
-=head2 register_private_template( TEMPLATE_NAME, CODEREF )
+=head3 register_private_template( TEMPLATE_NAME, CODEREF )
 
     MyApp::Templates->register_private_template( howdy => sub { ... } );
 
@@ -613,142 +620,161 @@ sub register_private_template {
 
 }
 
-=head2 mix
-
-    mix Some::Clever::Mixin      under '/mixin';
-    mix Some::Other::Mixin       under '/otmix', setting { name => 'Larry' };
-    mix My::Mixin into My::View, under '/mymix';
+=head3 buffer
 
-Sometimes you want to mix templates from one class into another class;
-C<mix()> is your key to doing so. In the first example, if Some::Clever::Mixin
-creates templates named C<foo> and C<bar>, they will be mixed into the calling
-template class as C<mixin/foo> and C<mixin/bar>.
+Gets or sets the L<String::BufferStack> object; this is a class method.
 
-The second example mixes in the templates defined in Some::Other::Mixin into
-into the calling class under the C</mymix> path. Furthermore, those mixed-in
-templates have package variables set for them that are accessible only from
-their mixed-in paths. For example, if this template was defined in
-Some::Other::Mixin:
+You can use it to manipulate the output from tags as they are output. It's used
+internally to make the tags nest correctly, and be output to the right place.
+We're not sure if there's ever a need for you to frob it by hand, but it does
+enable things like the following:
 
-    template howdy => sub {
-        my $self = shift;
-        outs "Howdy, " . $self->package_variable('name') || 'Jesse';
+    template simple => sub {
+       html {
+           head {}
+           body {
+               Template::Declare->buffer->set_filter( sub {uc shift} );
+               p { 'Whee!' }
+               p { 'Hello, world wide web!' }
+               Template::Declare->buffer->clear_top if rand() < 0.5;
+           }
+       }
     };
 
-Then C<show('mymixin/howdy')> will output "Howdy, Larry", while the output
-from C<show('howdy')> will output "Howdy, Jesse". In other words, package
-variables defined for the mixed-in templates are available only to the mixins
-and not to the original.
-
-In either case, ineritance continues to work. A template package that inherits
-from Some::Other::Mixin, for example, will be able to access both
-C<mymixin/howdy> and C<howdy>.
+...which outputs, with equal regularity, either:
 
-By default, C<mix()> will mix templates into the class from which it's called.
-But sometimes you might want to mix templates into some other template class.
-Such might be useful for end users to compose template structures from
-collections of template classes. In such a case, use the C<into> keyword to
-specify into what class the templates should be mixed in. The third example
-demonstrates this, where My::Mixin templates are mixed into My::View. Of
-course, you can still specify variables to set for those mixins.
+ <html>
+  <head></head>
+  <body>
+   <P>WHEE!</P>
+   <P>HELLO, WORLD WIDE WEB!</P>
+  </body>
+ </html>
 
-If you should happen to forget to pass the C<into> argument before C<under>,
-worry not, C<mix()> will figure it out and do the right thing.
+...or:
 
-For those who prefer a direct OO syntax for mixins, just call C<mix()> as a
-method on the class to be mixed in. To replicate the above three exmaples
-without the use of the sugar:
+ <html>
+  <head></head>
+  <body></body>
+ </html>
 
-    Some::Clver::Mixin->mix( '/mixin' );
-    Some::Other::Mixin->mix( '/otmix', { name => 'Larry' } );
-    My::Mixin->mix('My::View', '/mymix');
+We'll leave it to you to judge whether or not that's actually useful.
 
-=cut
+=head2 Helpers
 
-sub mix {
-    my $mixin = shift;
-    my ($into, $under);
-    if ( eval { $_[0]->isa(__PACKAGE__) } ) {
-        ($into, $under) = (shift, shift);
-    } elsif ( eval { $_[1]->isa(__PACKAGE__) } ) {
-        ($under, $into) = (shift, shift);
-    } else {
-        $into  = caller(0);
-        $under = shift;
-    }
-    $mixin->_import($into, $under, @_);
-}
+You don't need to call any of this directly.
 
-=head2 into
+=head3 into
 
-  $class = into $class;
+    $class = into $class;
 
-C<into> is a helper method providing semantic sugar for the C<mix()> method.
+C<into> is a helper method providing semantic sugar for the L</mix> method.
 All it does is return the name of the class on which it was called.
 
 =cut
 
 sub into { shift }
 
-=head2 alias
+=head2 Old, deprecated or just better to avoid
+
+=head3 alias
 
     alias Some::Clever::Mixin under '/mixin';
     alias Some::Other::Mixin  under '/mymix', { name => 'Larry' };
 
 Like C<mix()>, but without support for the C<into> keyword. That is, it mixes
-templates into the calling template class. Deprecated in favor of C<mix()>.
+templates into the calling template class.
+
+B<Deprecated> in favor of L</mix>. Will be supported for a long time, but
+new code should use C<mix()>.
 
 =cut
 
 sub alias { shift->_import(scalar caller(0), @_) }
 
-=head2 import_templates
+=head3 import_templates
 
     import_templates MyApp::Templates under '/something';
 
 Like C<mix()>, but without support for the C<into> or C<setting> keywords.
 That is, it mixes templates into the calling template class and does not
-support package variables for those mixins. Deprecated in favor of C<mix()>.
+support package variables for those mixins.
+
+B<Deprecated> in favor of L</mix>. Will be supported for a long time, but
+new code should use C<mix()>.
 
 =cut
 
 sub import_templates { shift->_import(scalar caller(0), @_) }
 
-=head2 package_variable( VARIABLE )
+=head3 new_buffer_frame
 
-  $td->package_variable( $varname => $value );
-  $value = $td->package_variable( $varname );
+    $td->new_buffer_frame;
+    # same as 
+    $td->buffer->push( private => 1 );
 
-Returns a value set for a mixed-in template's variable, if any were specified
-when the template was mixed-in. See L<mix/mix> for details.
+Creates a new buffer frame, using L<String::BufferStack/push> with C<private>.
+
+B<Deprecated> in favor of dealing with L</buffer> directly.
 
 =cut
 
-sub package_variable {
-    my $self = shift;
-    my $var  = shift;
-    if (@_) {
-        $TEMPLATE_VARS->{$self}->{$var} = shift;
-    }
-    return $TEMPLATE_VARS->{$self}->{$var};
+sub new_buffer_frame {
+    __PACKAGE__->buffer->push( private => 1 );
 }
 
-=head2 package_variables( VARIABLE )
+=head3 end_buffer_frame
 
-  $td->package_variables( $variables );
-  $variables = $td->package_variables( );
+    my $buf = $td->end_buffer_frame;
+    # same as
+    my $buf = $td->buffer->pop;
 
-Get or set a hash reference of variables for a mixed-in template. See
-L<mix/mix> for details.
+Deletes and returns the topmost buffer, using L<String::BufferStack/pop>.
+
+B<Deprecated> in favor of dealing with L</buffer> directly.
 
 =cut
 
-sub package_variables {
-    my $self = shift;
-    if (@_) {
-        %{ $TEMPLATE_VARS->{$self} } = shift;
-    }
-    return $TEMPLATE_VARS->{$self};
+sub end_buffer_frame {
+    __PACKAGE__->buffer->pop;
+}
+
+=head3 path_for $template
+
+    my $path = Template::Declare->path_for('index');
+
+Returns the path for the template name to be used for show, adjusted with
+paths used in C<mix>.
+
+=cut
+
+# Removed methods that no longer work (and were never documented anyway).
+# Remove these no-ops after a few releases (added for 0.41).
+
+=begin comment
+
+=head3 aliases
+
+=head3 alias_metadata
+
+=end comment
+
+=cut
+
+sub aliases {
+    require Carp;
+    Carp::cluck( 'aliases() is a deprecated no-op' );
+}
+
+sub alias_metadata {
+    require Carp;
+    Carp::cluck( 'alias_metadata() is a deprecated no-op' );
+}
+
+sub path_for {
+    my $class = shift;
+    my $template = shift;
+    return ($class->imported_into ||'') . '/' . $template;
 }
 
 sub _templates_for {
@@ -845,7 +871,8 @@ sub _import {
 sub _import_code {
     my ($tname, $from, $to, $vars) = @_;
     my $code = $from->_find_template_sub( _template_name_to_sub($tname) );
-    return $to eq $from ? $code : sub { $code->($to, @_) } unless $vars;
+    return $to eq $from ? $code : sub { $code->($to, @_) }
+        unless $vars;
     return sub {
         # XXX This does not seem to be needed.
         # shift @_;  # Get rid of the passed-in "$self" class.
@@ -971,7 +998,7 @@ string as the content instead of 0:
 
 Crawling all over, baby. Be very, very careful. This code is so cutting edge,
 it can only be fashioned from carbon nanotubes. But we're already using this
-thing in production :) Make sure you have read the L<PITFALLS/PITFALLS>
+thing in production :) Make sure you have read the L</PITFALLS>
 section above :)
 
 Some specific bugs and design flaws that we'd love to see fixed.

commit 450670cb2bf9b58539add1f79d149060bc66f19b
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date:   Sat Oct 10 13:42:24 2009 +0000

    shuffle methods in Tags.pm and update docs

diff --git a/lib/Template/Declare/Tags.pm b/lib/Template/Declare/Tags.pm
index acc1a0b..a226e5d 100644
--- a/lib/Template/Declare/Tags.pm
+++ b/lib/Template/Declare/Tags.pm
@@ -116,14 +116,14 @@ Template::Declare::Tags - Build and install XML Tag subroutines for Template::De
 
 Produces:
 
- <link />
- <table>
-  <tr>
-   <td>Hello, world!</td>
-  </tr>
- </table>
- <img src="cat.gif" />
- <img src="dog.gif" />
+    <link />
+    <table>
+     <tr>
+      <td>Hello, world!</td>
+     </tr>
+    </table>
+    <img src="cat.gif" />
+    <img src="dog.gif" />
 
 Using XUL templates with a namespace:
 
@@ -143,13 +143,13 @@ Using XUL templates with a namespace:
 
 Produces:
 
- <groupbox>
-  <caption label="Colors" />
-  <html:div>
-   <html:p>howdy!</html:p>
-  </html:div>
-  <html:br></html:br>
- </groupbox>
+    <groupbox>
+     <caption label="Colors" />
+     <html:div>
+      <html:p>howdy!</html:p>
+     </html:div>
+     <html:br></html:br>
+    </groupbox>
 
 =head1 DESCRIPTION
 
@@ -209,13 +209,13 @@ within XUL using the C<html> namespace:
 
 This will output:
 
- <groupbox>
-  <caption label="Colors" />
-  <html:div>
-   <html:p>howdy!</html:p>
-  </html:div>
-  <html:br></html:br>
- </groupbox>
+    <groupbox>
+     <caption label="Colors" />
+     <html:div>
+      <html:p>howdy!</html:p>
+     </html:div>
+     <html:br></html:br>
+    </groupbox>
 
 Behind the scenes, C<Template::Declare::Tags> generates a Perl package named
 C<html> and installs the HTML tag subroutines into that package. On the other
@@ -245,17 +245,19 @@ them elsewhere:
 
 This code will generate something like the following:
 
- <groupbox>
-  <caption label="Colors" />
-  <htm:div>
-   <htm:p>howdy!</htm:p>
-  </htm:div>
-  <htm:br></htm:br>
- </groupbox>
+    <groupbox>
+     <caption label="Colors" />
+     <htm:div>
+      <htm:p>howdy!</htm:p>
+     </htm:div>
+     <htm:br></htm:br>
+    </groupbox>
 
 =head1 METHODS AND SUBROUTINES
 
-=head2 template TEMPLATENAME => sub { 'Implementation' };
+=head2 Declaring templates
+
+=head3 template TEMPLATENAME => sub { 'Implementation' };
 
     template select_list => sub {
         my $self = shift;
@@ -306,99 +308,94 @@ sub template ($$) {
             $codesub,
         );
     }
-
 }
 
-=head2 create_wrapper WRAPPERNAME => sub { 'Implementation' };
+=head3 private template TEMPLATENAME => sub { 'Implementation' };
 
-    create_wrapper basics => sub {
-        my $code = shift;
-        html {
-            head { title { 'Welcome' } };
-            body { $code->() }
+    private template select_list => sub {
+        my $self = shift;
+        select {
+            option { $_ } for @_;
         }
     };
 
-C<create_wrapper> declares a wrapper subroutine that can be called like a tag
-sub, but can optionally take arguments to be passed to the wrapper sub. For
-example, if you wanted to wrap all of the output of a template in the usual
-HTML headers and footers, you can do something like this:
+Declares that a template isn't available to be called directly from client
+code. The resulting template can instead only be called from the package in
+which it's created.
 
-    package MyApp::Templates;
-    use Template::Declare::Tags;
-    use base 'Template::Declare';
+=cut
 
-    BEGIN {
-        create_wrapper wrap => sub {
-            my $code = shift;
-            my %params = @_;
-            html {
-                head { title { outs "Hello, $params{user}!"} };
-                body {
-                    $code->();
-                    div { outs 'This is the end, my friend' };
-                };
-            }
-        };
-    }
+sub private (@) {
+    my $class   = shift;
+    my $subname = shift;
+    my $code    = shift;
+    Template::Declare::register_private_template( $class, $subname, $code );
+}
 
-    template inner => sub {
-        wrap {
-            h1 { outs "Hello, Jesse, s'up?" };
-        } user => 'Jesse';
-    };
+=head2 Showing templates
 
-Note how the C<wrap> wrapper function is available for calling after it has
-been declared in a C<BEGIN> block. Also note how you can pass arguments to the
-function after the closing brace (you don't need a comma there!).
+=head3 show [$template_name or $template_coderef], args
 
-The output from the "inner" template will look something like this:
+    show( main => { user => 'Bob' } );
 
- <html>
-  <head>
-   <title>Hello, Jesse!</title>
-  </head>
-  <body>
-   <h1>Hello, Jesse, s'up?</h1>
-   <div>This is the end, my friend</div>
-  </body>
- </html>
+Displays templates. The first agument is the name of the template to be
+displayed. Any additional arguments will be passed directly to the template.
+
+C<show> can either be called with a template name or a package/object and a
+template. (It's both functional and OO.)
+
+If called from within a Template::Declare subclass, then private templates are
+accessible and visible. If called from something that isn't a
+Template::Declare, only public templates wil be visible.
+
+From the outside world, users can either call C<< Template::Declare->show() >>,
+C<< show() >> exported from Template::Declare::Tags or
+C<Template::Declare::Tags::show()> directly to render a publicly visible template.
+
+Private templates may only be called from within the C<Template::Declare>
+package.
 
 =cut
 
-sub create_wrapper ($$) {
-    my $wrapper_name   = shift;
-    my $coderef        = shift;
-    my $template_class = caller;
+sub show {
+    my $template = shift;
+
+    # if we're inside a template, we should show private templates
+    if ( caller->isa('Template::Declare') ) {
+        _show_template( $template, 1, \@_ );
+        return Template::Declare->buffer->data;
+    } else {
+        show_page( $template, @_);
+    }
 
-    # Shove the code ref into the calling class.
-    no strict 'refs';
-    *{"$template_class\::$wrapper_name"} = sub (&;@) { goto $coderef };
 }
 
-=head2 private template TEMPLATENAME => sub { 'Implementation' };
+=head3 show_page
 
-    private template select_list => sub {
-        my $self = shift;
-        select {
-            option { $_ } for @_;
-        }
-    };
+    show_page( main => { user => 'Bob' } );
 
-Declares that a template isn't available to be called directly from client
-code. The resulting template can instead only be called from the package in
-which it's created.
+Like C<show()>, but does not dispatch to private templates. It's used
+internally by C<show()> when when that method is called from outside a
+template class.
 
 =cut
 
-sub private (@) {
-    my $class   = shift;
-    my $subname = shift;
-    my $code    = shift;
-    Template::Declare::register_private_template( $class, $subname, $code );
+sub show_page {
+    my $template = shift;
+    my $args = \@_;
+
+    Template::Declare->buffer->push(
+        private => defined wantarray,
+        from => "T::D path $template",
+    );
+    _show_template( $template, 0, $args );
+    %ELEMENT_ID_CACHE = ();
+    return Template::Declare->buffer->pop;
 }
 
-=head2 attr HASH
+=head2 Attributes
+
+=head3 attr HASH
 
     attr { src => 'logo.png' };
 
@@ -413,14 +410,6 @@ add a class and ID to an HTML paragraph:
        'This is a welcoming paragraph';
     }
 
-Attributes can also be specified by using C<is>, as in
-
-    p {
-       class is 'greeting text';
-       id    is 'welcome';
-       'This is a welcoming paragraph';
-    }
-
 =cut
 
 sub attr (&;@) {
@@ -434,36 +423,60 @@ sub attr (&;@) {
     return @_;
 }
 
-=head2 xml_decl HASH
+=head3 ATTR is VALUE
 
-    xml_decl { 'xml', version => '1.0' };
+Attributes can also be specified by using C<is>, as in
 
-Emits an XML declaration. For example:
+    p {
+       class is 'greeting text';
+       id    is 'welcome';
+       'This is a welcoming paragraph';
+    }
 
-    xml_decl { 'xml', version => '1.0' };
-    xml_decl { 'xml-stylesheet',  href => "chrome://global/skin/", type => "text/css" };
+A few tricks work for 'is':
 
-Produces:
+    http_equiv is 'foo'; # => http-equiv="foo"
+    xml__lang is 'foo';  # => xml:lang="foo"
 
- <?xml version="1.0"?>
- <?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
+So double underscore replaced with colon and single underscore with dash.
 
 =cut
 
-sub xml_decl (&;$) {
-    my $code = shift;
-    my @rv   = $code->();
-    my $name = shift @rv;
-    outs_raw("<?$name");
-    while ( my ( $field, $val ) = splice( @rv, 0, 2 ) ) {
-        # only defined whle in a tag context
-        outs_raw(qq/ $field="$val"/);
+# 'is' is declared later, when needed, using 'local *is::AUTOLOAD = sub {};'
+
+=head3 with
+
+    with ( id => 'greeting', class => 'foo' ),
+        p { 'Hello, World wide web' };
+
+An alternative way to specify attributes for a tag, just for variation. The
+standard way to do the same as this example using C<attr> is:
+
+    p { attr { id => 'greeting', class => 'foo' }
+        'Hello, World wide web' };
+
+=cut
+
+sub with (@) {
+    %ATTRIBUTES = ();
+    while ( my ( $key, $val ) = splice( @_, 0, 2 ) ) {
+        no warnings 'uninitialized';
+        $ATTRIBUTES{$key} = $val;
+
+        if ( lc($key) eq 'id' ) {
+            if ( $ELEMENT_ID_CACHE{$val}++ ) {
+                warn
+                    "HTML appears to contain illegal duplicate element id: $val";
+            }
+        }
+
     }
-    outs_raw("?>\n");
-    return @_;
+    wantarray ? () : '';
 }
 
-=head2 outs STUFF
+=head2 Displaying text and raw data
+
+=head3 outs STUFF
 
     p { outs 'Grettings & welcome pyoonie hyoomon.' }
 
@@ -473,7 +486,7 @@ but is occaisionally useful when you need to output a mix of things, as in:
 
     p { outs 'hello'; em { 'world' } }
 
-=head2 outs_raw STUFF
+=head3 outs_raw STUFF
 
    p { outs_raw "That's what <em>I'm</em> talking about!' }
 
@@ -485,40 +498,9 @@ escaping.
 sub outs     { _outs( 0, @_ ); }
 sub outs_raw { _outs( 1, @_ ); }
 
-sub _outs {
-    my $raw     = shift;
-    my @phrases = (@_);
-
-    Template::Declare->buffer->push(
-        private => (defined wantarray and not wantarray), from => "T::D outs"
-    );
+=head2 Installing tags and wrapping stuff
 
-    foreach my $item ( grep {defined} @phrases ) {
-        my $returned = ref($item) eq 'CODE'
-            ? $item->()
-            : $raw
-                ? $item
-                : _postprocess($item);
-        Template::Declare->buffer->append( $returned );
-    }
-    return Template::Declare->buffer->pop;
-}
-
-=begin comment
-
-=head2 get_current_attr
-
-Deprecated.
-
-=end comment
-
-=cut
-
-sub get_current_attr ($) {
-    $ATTRIBUTES{ $_[0] };
-}
-
-=head2 install_tag TAGNAME, TAGSET
+=head3 install_tag TAGNAME, TAGSET
 
     install_tag video => 'Template::Declare::TagSet::HTML';
 
@@ -583,39 +565,9 @@ sub install_tag {
     );
 }
 
-=head2 with
-
-    with ( id => 'greeting', class => 'foo' ),
-        p { 'Hello, World wide web' };
-
-An alternative way to specify attributes for a tag, just for variation. The
-standard way to do the same as this example using C<attr> is:
-
-    p { attr { id => 'greeting', class => 'foo' }
-        'Hello, World wide web' };
-
-=cut
-
-sub with (@) {
-    %ATTRIBUTES = ();
-    while ( my ( $key, $val ) = splice( @_, 0, 2 ) ) {
-        no warnings 'uninitialized';
-        $ATTRIBUTES{$key} = $val;
-
-        if ( lc($key) eq 'id' ) {
-            if ( $ELEMENT_ID_CACHE{$val}++ ) {
-                warn
-                    "HTML appears to contain illegal duplicate element id: $val";
-            }
-        }
-
-    }
-    wantarray ? () : '';
-}
-
-=head2 smart_tag_wrapper
+=head3 smart_tag_wrapper
 
-    # create a tag that has access to the arguments set with with.
+    # create a tag that has access to the arguments set with L</with>.
     sub sample_smart_tag (&) {
         my $code = shift;
 
@@ -633,8 +585,8 @@ sub with (@) {
 
 The output would be
 
- keys: baz, foo
- Hello, World!
+    keys: baz, foo
+    Hello, World!
 
 The smart tag wrapper allows you to create code that has access to the
 attribute arguments specified via C<with>. It passes those arguments in to the
@@ -664,6 +616,147 @@ sub smart_tag_wrapper (&) {
     return '';
 }
 
+=head3 create_wrapper WRAPPERNAME => sub { 'Implementation' };
+
+    create_wrapper basics => sub {
+        my $code = shift;
+        html {
+            head { title { 'Welcome' } };
+            body { $code->() }
+        }
+    };
+
+C<create_wrapper> declares a wrapper subroutine that can be called like a tag
+sub, but can optionally take arguments to be passed to the wrapper sub. For
+example, if you wanted to wrap all of the output of a template in the usual
+HTML headers and footers, you can do something like this:
+
+    package MyApp::Templates;
+    use Template::Declare::Tags;
+    use base 'Template::Declare';
+
+    BEGIN {
+        create_wrapper wrap => sub {
+            my $code = shift;
+            my %params = @_;
+            html {
+                head { title { outs "Hello, $params{user}!"} };
+                body {
+                    $code->();
+                    div { outs 'This is the end, my friend' };
+                };
+            }
+        };
+    }
+
+    template inner => sub {
+        wrap {
+            h1 { outs "Hello, Jesse, s'up?" };
+        } user => 'Jesse';
+    };
+
+Note how the C<wrap> wrapper function is available for calling after it has
+been declared in a C<BEGIN> block. Also note how you can pass arguments to the
+function after the closing brace (you don't need a comma there!).
+
+The output from the "inner" template will look something like this:
+
+    <html>
+     <head>
+      <title>Hello, Jesse!</title>
+     </head>
+     <body>
+      <h1>Hello, Jesse, s'up?</h1>
+      <div>This is the end, my friend</div>
+     </body>
+    </html>
+
+=cut
+
+sub create_wrapper ($$) {
+    my $wrapper_name   = shift;
+    my $coderef        = shift;
+    my $template_class = caller;
+
+    # Shove the code ref into the calling class.
+    no strict 'refs';
+    *{"$template_class\::$wrapper_name"} = sub (&;@) { goto $coderef };
+}
+
+=head2 Helpers
+
+=head3 xml_decl HASH
+
+    xml_decl { 'xml', version => '1.0' };
+
+Emits an XML declaration. For example:
+
+    xml_decl { 'xml', version => '1.0' };
+    xml_decl { 'xml-stylesheet',  href => "chrome://global/skin/", type => "text/css" };
+
+Produces:
+
+    <?xml version="1.0"?>
+    <?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
+
+=cut
+
+sub xml_decl (&;$) {
+    my $code = shift;
+    my @rv   = $code->();
+    my $name = shift @rv;
+    outs_raw("<?$name");
+    while ( my ( $field, $val ) = splice( @rv, 0, 2 ) ) {
+        outs_raw(qq/ $field="$val"/);
+    }
+    outs_raw("?>\n");
+    return @_;
+}
+
+=head3 current_template
+
+    my $path = current_template();
+
+Returns the absolute path of the current template
+
+=cut
+
+sub current_template {
+    return $TEMPLATE_STACK[-1] || '';
+}
+
+=head3 under
+
+C<under> is a helper function providing semantic sugar for the C<mix> method
+of L<Template::Declare|Template::Declare/"mix">.
+
+=cut
+
+sub under ($) { return shift }
+
+=head3 setting
+
+C<setting> is a helper function providing semantic sugar for the C<mix> method
+of L<Template::Declare|Template::Declare/"mix">.
+
+=cut
+
+sub setting ($) { return shift }
+
+=begin comment
+
+=head2 get_current_attr
+
+Deprecated.
+
+=end comment
+
+=cut
+
+sub get_current_attr ($) {
+    $ATTRIBUTES{ $_[0] };
+}
+
 sub _tag {
     my $tagset    = shift;
     my $tag       = shift;
@@ -733,65 +826,6 @@ sub _tag {
         : '';
 }
 
-=head2 show [$template_name or $template_coderef], args
-
-    show( main => { user => 'Bob' } );
-
-Displays templates. The first agument is the name of the template to be
-displayed. Any additional arguments will be passed directly to the template.
-
-C<show> can either be called with a template name or a package/object and a
-template. (It's both functional and OO.)
-
-If called from within a Template::Declare subclass, then private templates are
-accessible and visible. If called from something that isn't a
-Template::Declare, only public templates wil be visible.
-
-From the outside world, users can either call C<< Template::Declare->show() >>,
-C<< show() >> exported from Template::Declare::Tags or
-C<Template::Declare::Tags::show()> directly to render a publicly visible template.
-
-Private templates may only be called from within the C<Template::Declare>
-package.
-
-=cut
-
-sub show {
-    my $template = shift;
-
-    # if we're inside a template, we should show private templates
-    if ( caller->isa('Template::Declare') ) {
-        _show_template( $template, 1, \@_ );
-        return Template::Declare->buffer->data;
-    } else {
-        show_page( $template, @_);
-    }
-
-}
-
-=head2 show_page
-
-    show_page( main => { user => 'Bob' } );
-
-Like C<show()>, but does not dispatch to private templates. It's used
-internally by C<show()> when when that method is called from outside a
-template class.
-
-=cut
-
-sub show_page {
-    my $template = shift;
-    my $args = \@_;
-
-    Template::Declare->buffer->push(
-        private => defined wantarray,
-        from => "T::D path $template",
-    );
-    _show_template( $template, 0, $args );
-    %ELEMENT_ID_CACHE = ();
-    return Template::Declare->buffer->pop;
-}
-
 sub _resolve_template_path {
     my $template = shift;
 
@@ -816,19 +850,6 @@ sub _resolve_template_path {
     return join '/', @parts;
 }
 
-=head2 current_template
-
-  my $path = current_template();
-
-Returns the absolute path of the current template
-
-=cut
-
-sub current_template {
-    return $TEMPLATE_STACK[-1] || '';
-}
-
-
 sub _show_template {
     my $template        = shift;
     my $inside_template = shift;
@@ -864,6 +885,25 @@ sub _show_template {
     return;
 }
 
+sub _outs {
+    my $raw     = shift;
+    my @phrases = (@_);
+
+    Template::Declare->buffer->push(
+        private => (defined wantarray and not wantarray), from => "T::D outs"
+    );
+
+    foreach my $item ( grep {defined} @phrases ) {
+        my $returned = ref($item) eq 'CODE'
+            ? $item->()
+            : $raw
+                ? $item
+                : _postprocess($item);
+        Template::Declare->buffer->append( $returned );
+    }
+    return Template::Declare->buffer->pop;
+}
+
 sub _postprocess {
     my $val = shift;
     my $skip_postprocess = shift;
@@ -888,24 +928,6 @@ sub _postprocess {
     return $val;
 }
 
-=head2 under
-
-C<under> is a helper function providing semantic sugar for the C<mix> method
-of L<Template::Declare|Template::Declare/"mix">.
-
-=cut
-
-sub under ($) { return shift }
-
-=head2 setting
-
-C<setting> is a helper function providing semantic sugar for the C<mix> method
-of L<Template::Declare|Template::Declare/"mix">.
-
-=cut
-
-sub setting ($) { return shift }
-
 =begin comment
 
 =head2 append_attr
@@ -957,11 +979,11 @@ code:
 
 It generates
 
- <body>
-  <pre>
- <script src="foo.js"></script>
-  </pre>
- </body>
+    <body>
+     <pre>
+    <script src="foo.js"></script>
+     </pre>
+    </body>
 
 Note that now the C<script> tag has I<no> indentation and we've got what we
 want. ;)

commit 2829ccc56a6bb2fc0c2547e6f7d03cf9dc5830e9
Author: Ruslan Zakirov <ruz at bestpractical.com>
Date:   Sat Oct 10 13:43:20 2009 +0000

    we don't use Carp directly, use 'our' instead of vars

diff --git a/lib/Template/Declare.pm b/lib/Template/Declare.pm
index 8ff47d3..45ecb30 100644
--- a/lib/Template/Declare.pm
+++ b/lib/Template/Declare.pm
@@ -1,7 +1,6 @@
 use 5.006;
 use warnings;
 use strict;
-use Carp;
 
 package Template::Declare;
 use Template::Declare::Buffer;
@@ -35,7 +34,7 @@ __PACKAGE__->around_template( undef );
     return $ref->buffer;
 };
 
-use vars qw/$TEMPLATE_VARS/;
+our $TEMPLATE_VARS;
 
 # Backwards-compatibility support.
 sub roots {

-----------------------------------------------------------------------



More information about the Bps-public-commit mailing list