Permalink
Browse files

Added documentation for some methods that were lacking it

  • Loading branch information...
abw committed Jan 25, 2012
1 parent 871a0cd commit b82875e235c7ff88f23bcb880134c2ef4837df1d
Showing with 230 additions and 57 deletions.
  1. +6 −0 lib/Template.pm
  2. +104 −31 lib/Template/Context.pm
  3. +48 −11 lib/Template/Document.pm
  4. +5 −0 lib/Template/Provider.pm
  5. +53 −2 lib/Template/Stash.pm
  6. +10 −9 t/zz-pod-coverage.t
  7. +4 −4 t/zz-pod-kwalitee.t
View
@@ -464,6 +464,12 @@ The L<Template::Service> module uses a core L<Template::Context> object for
runtime processing of templates. This method returns a reference to
that object and is equivalent to C<< $template-E<gt>service-E<gt>context() >>.
+=head2 template($name)
+
+This method is a simple wrapper around the L<Template::Context> method of the
+same name. It returns a compiled template for the source provided as an
+argument.
+
=head1 CONFIGURATION SUMMARY
The following list gives a short summary of each Template Toolkit
View
@@ -647,6 +647,25 @@ sub define_filter {
"FILTER providers declined to store filter $name");
}
+
+#------------------------------------------------------------------------
+# define_vmethod($type, $name, \&sub)
+#
+# Passes $type, $name, and &sub on to stash->define_vmethod().
+#------------------------------------------------------------------------
+
+sub define_vmethod {
+ my $self = shift;
+ $self->stash->define_vmethod(@_);
+}
+
+
+#------------------------------------------------------------------------
+# define_view($name, $params)
+#
+# Defines a new view.
+#------------------------------------------------------------------------
+
sub define_view {
my ($self, $name, $params) = @_;
my $base;
@@ -671,6 +690,13 @@ sub define_view {
$self->{ STASH }->set($name, $view);
}
+
+#------------------------------------------------------------------------
+# define_views($views)
+#
+# Defines multiple new views.
+#------------------------------------------------------------------------
+
sub define_views {
my ($self, $views) = @_;
@@ -719,17 +745,6 @@ sub stash {
}
-#------------------------------------------------------------------------
-# define_vmethod($type, $name, \&sub)
-#
-# Passes $type, $name, and &sub on to stash->define_vmethod().
-#------------------------------------------------------------------------
-sub define_vmethod {
- my $self = shift;
- $self->stash->define_vmethod(@_);
-}
-
-
#------------------------------------------------------------------------
# debugging($command, @args, \%params)
#
@@ -745,30 +760,29 @@ sub debugging {
my $hash = ref $_[-1] eq 'HASH' ? pop : { };
my @args = @_;
-# print "*** debug(@args)\n";
if (@args) {
- if ($args[0] =~ /^on|1$/i) {
- $self->{ DEBUG_DIRS } = 1;
- shift(@args);
- }
- elsif ($args[0] =~ /^off|0$/i) {
- $self->{ DEBUG_DIRS } = 0;
- shift(@args);
- }
+ if ($args[0] =~ /^on|1$/i) {
+ $self->{ DEBUG_DIRS } = 1;
+ shift(@args);
+ }
+ elsif ($args[0] =~ /^off|0$/i) {
+ $self->{ DEBUG_DIRS } = 0;
+ shift(@args);
+ }
}
if (@args) {
- if ($args[0] =~ /^msg$/i) {
+ if ($args[0] =~ /^msg$/i) {
return unless $self->{ DEBUG_DIRS };
- my $format = $self->{ DEBUG_FORMAT };
- $format = $DEBUG_FORMAT unless defined $format;
- $format =~ s/\$(\w+)/$hash->{ $1 }/ge;
- return $format;
- }
- elsif ($args[0] =~ /^format$/i) {
- $self->{ DEBUG_FORMAT } = $args[1];
- }
- # else ignore
+ my $format = $self->{ DEBUG_FORMAT };
+ $format = $DEBUG_FORMAT unless defined $format;
+ $format =~ s/\$(\w+)/$hash->{ $1 }/ge;
+ return $format;
+ }
+ elsif ($args[0] =~ /^format$/i) {
+ $self->{ DEBUG_FORMAT } = $args[1];
+ }
+ # else ignore
}
return '';
@@ -1302,6 +1316,11 @@ any variables will only persist until the C<include()> method completes.
$output = $context->include('header', { title => 'Hello World' });
+=head2 insert($template)
+
+This method returns the source content of a template file without performing
+any evaluation. It is used to implement the C<INSERT> directive.
+
=head2 throw($error_type, $error_message, \$output)
Raises an exception in the form of a L<Template::Exception> object by calling
@@ -1358,6 +1377,20 @@ indicate that the subroutine is a dynamic filter factory.
Returns a true value or throws a 'C<filter>' exception on error.
+=head2 define_vmethod($type, $name, $code)
+
+This method is a wrapper around the L<Template::Stash>
+L<define_vmethod()|Template::Stash#define_vmethod()> method. It can be used
+to define new virtual methods.
+
+ # define a new scalar (item) virtual method
+ $context->define_vmethod(
+ item => ucfirst => sub {
+ my $text = shift;
+ return ucfirst $text;
+ }
+ )
+
=head2 define_view($name, \%params)
This method allows you to define a named L<view|Template::View>.
@@ -1409,6 +1442,11 @@ The views are then accessible as template variables.
See also the L<VIEWS> option.
+=head2 stash()
+
+This method returns the L<Template::Stash> object used internally to manage
+template variables.
+
=head2 localise(\%vars)
Clones the stash to create a context with localised variables. Returns a
@@ -1435,11 +1473,46 @@ delivered on request.
Compliment to the L<visit()> method. Called by L<Template::Document> objects
immediately after they process their content.
+=head2 view()
+
+This method creates a L<Template::View> object bound to the context.
+
=head2 reset()
Clears the local L<BLOCKS> cache of any C<BLOCK> definitions. Any initial set of
L<BLOCKS> specified as a configuration item to the constructor will be reinstated.
+=head2 debugging($flag, @args)
+
+This method is used to control debugging output. It is used to implement
+the L<DEBUG|Template::Manual::Directives#DEBUG> directive.
+
+The first argument can be C<on> or C<off> to enable or disable debugging
+respectively. The numerical values C<0> and C<1> can also be used if you
+prefer.
+
+ $context->debugging('on');
+
+Alternately, the first argument can be C<format> to define a new debug message
+format. The second argument should be the format string which can contain
+any of the C<$file>, C<$line> or C<$text> symbols to indicate where the
+relevant values should be inserted.
+
+ # note single quotes to prevent interpolated of variables
+ $context->debugging( format => '## $file line $line: $text' );
+
+The final use of this method is to generate debugging messages themselves.
+The first argument should be C<msg>, followed by a reference to a hash array
+of value to insert into the debugging format string.
+
+ $context->debugging(
+ msg => {
+ line => 20,
+ file => 'example.tt',
+ text => 'Trampoline! Trampoline!',
+ }
+ );
+
=head2 AUTOLOAD
An C<AUTOLOAD> method provides access to context configuration items.
@@ -1455,7 +1528,7 @@ Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
=head1 COPYRIGHT
-Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
View
@@ -456,33 +456,70 @@ Returns a reference to the main C<BLOCK> subroutine.
Returns a reference to the hash array of named C<DEFBLOCKS> subroutines.
+=head2 variables()
+
+Returns a reference to a hash of variables used in the template.
+This requires the L<TRACE_VARS|Template::Manual::Config#TRACE_VARS>
+option to be enabled.
+
=head2 AUTOLOAD
An autoload method returns C<METADATA> items.
print $doc->author();
-=head1 PACKAGE SUB-ROUTINES
+=head1 CLASS METHODS
+
+These methods are used internally.
+
+=head2 as_perl($content)
+
+This method generate a Perl representation of the template.
+
+ my $perl = Template::Document->as_perl({
+ BLOCK => $main_block,
+ DEFBLOCKS => {
+ foo => $foo_block,
+ bar => $bar_block,
+ },
+ METADATA => {
+ name => 'my_template',
+ }
+ });
=head2 write_perl_file(\%config)
-This package subroutine is provided to effect persistence of compiled
-templates. If the C<COMPILE_EXT> option (to indicate a file extension
-for saving compiled templates) then the L<Template::Parser> module calls
-this subroutine before calling the L<new()> constructor. At this stage,
-the parser has a representation of the template as text strings
-containing Perl code. We can write that to a file, enclosed in a
-small wrapper which will allow us to susequently C<require()> the file
-and have Perl parse and compile it into a C<Template::Document>. Thus we
-have persistence of compiled templates.
+This method is used to write compiled Perl templates to disk. If the
+C<COMPILE_EXT> option (to indicate a file extension for saving compiled
+templates) then the L<Template::Parser> module calls this subroutine before
+calling the L<new()> constructor. At this stage, the parser has a
+representation of the template as text strings containing Perl code. We can
+write that to a file, enclosed in a small wrapper which will allow us to
+susequently C<require()> the file and have Perl parse and compile it into a
+C<Template::Document>. Thus we have persistence of compiled templates.
+
+=head1 INTERNAL FUNCTIONS
+
+=head2 catch_warnings()
+
+This is a simple handler used to catch any errors that arise when the
+compiled Perl template is first evaluated (that is, evaluated by Perl to
+create a template subroutine at compile, rather than the template being
+processed at runtime).
+
+=head2 is_utf8()
+
+This is mapped to C<utf8::is_utf8> for versions of Perl that have it (> 5.008)
+or to C<Encode::is_utf8> for Perl 5.008. Earlier versions of Perl are not
+supported.
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
=head1 COPYRIGHT
-Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
View
@@ -1162,6 +1162,11 @@ read error, parse error) then C<($error, STATUS_ERROR)> is returned, where
C<$error> is the error message generated. If the L<TOLERANT> option is set the
the method returns C<(undef, STATUS_DECLINED)> instead of returning an error.
+=head2 load($name)
+
+Loads a template without parsing or compiling it. This is used by the
+the L<INSERT|Template::Manual::Directives#INSERT> directive.
+
=head2 store($name, $template)
Stores the compiled template, C<$template>, in the cache under the name,
View
@@ -290,7 +290,6 @@ sub set {
#
# Returns a "reference" to a particular item. This is represented as a
# closure which will return the actual stash item when called.
-# WARNING: still experimental!
#------------------------------------------------------------------------
sub getref {
@@ -790,6 +789,24 @@ copied (i.e. imported) into the current namespace.
# import 'foo' into main namespace: bar = baz, wiz = waz
$stash->set('IMPORT', $stash->get('foo'));
+=head2 update($variables)
+
+This method can be used to set or update several variables in one go.
+
+ $stash->update({
+ foo => 10,
+ bar => 20,
+ });
+
+=head2 getref($variable)
+
+This undocumented feature returns a closure which can be called to get the
+value of a variable. It is used to implement variable references which are
+evlauted lazily.
+
+ [% x = \foo.bar.baz %] # x is a reference to foo.bar.baz
+ [% x %] # evalautes foo.bar.baz
+
=head2 clone(\%params)
The C<clone()> method creates and returns a new C<Template::Stash> object
@@ -813,13 +830,47 @@ from in its C<_PARENT> member.
The C<declone()> method returns the C<_PARENT> reference and can be used to
restore the state of a stash as described above.
+=head2 define_vmethod($type, $name, $code)
+
+This method can be used to define new virtual methods. The first argument
+should be either C<scalar> or C<item> to define scalar virtual method, C<hash>
+to define hash virtual methods, or either C<array> or C<list> for list virtual
+methods. The second argument should be the name of the new method. The third
+argument should be a reference to a subroutine implementing the method. The
+data item on which the virtual method is called is passed to the subroutine as
+the first argument.
+
+ $stash->define_vmethod(
+ item => ucfirst => sub {
+ my $text = shift;
+ return ucfirst $text
+ }
+ );
+
+=head1 INTERNAL METHODS
+
+=head2 dotop($root, $item, \@args, $lvalue)
+
+This is the core C<dot> operation method which evaluates elements of
+variables against their root.
+
+=head2 undefined($ident, $args)
+
+This method is called when L<get()> encounters an undefined value. If the
+C<STRICT|Template::Manual::Config#STRICT> option is in effect then it will
+throw an exception indicating the use of an undefined value. Otherwise it
+will silently return an empty string.
+
+The method can be redefined in a subclass to implement alternate handling
+of undefined values.
+
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
=head1 COPYRIGHT
-Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
Oops, something went wrong.

0 comments on commit b82875e

Please sign in to comment.