fixed bug in compiler where it lost $+[0] during recursion
[urisagit/Template-Simple.git] / lib / Template / Simple.pm
1 package Template::Simple;
2
3 use warnings;
4 use strict;
5
6 use Carp ;
7 use Data::Dumper ;
8 use Scalar::Util qw( reftype ) ;
9 use File::Slurp ;
10
11
12 our $VERSION = '0.03';
13
14 my %opt_defaults = (
15
16         pre_delim       => qr/\[%/,
17         post_delim      => qr/%\]/,
18         greedy_chunk    => 0,
19 #       upper_case      => 0,
20 #       lower_case      => 0,
21         include_paths   => [ qw( templates ) ],
22 ) ;
23
24 sub new {
25
26         my( $class, %opts ) = @_ ;
27
28         my $self = bless {}, $class ;
29
30 # get all the options or defaults into the object
31
32         while( my( $name, $default ) = each %opt_defaults ) {
33
34                 $self->{$name} = defined( $opts{$name} ) ? 
35                                 $opts{$name} : $default ;
36         }
37
38 # make up the regexes to parse the markup from templates
39
40 # this matches scalar markups and grabs the name
41
42         $self->{scalar_re} = qr{
43                 $self->{pre_delim}
44                 \s*                     # optional leading whitespace
45                 (\w+?)                  # grab scalar name
46                 \s*                     # optional trailing whitespace
47                 $self->{post_delim}
48         }xi ;                           # case insensitive
49
50 #print "RE <$self->{scalar_re}>\n" ;
51
52 # this grabs the body of a chunk in either greedy or non-greedy modes
53
54         my $chunk_body = $self->{greedy_chunk} ? qr/.+/s : qr/.+?/s ;
55
56 # this matches a marked chunk and grabs its name and text body
57
58         $self->{chunk_re} = qr{
59                 $self->{pre_delim}
60                 \s*                     # optional leading whitespace
61                 START                   # required START token
62                 \s+                     # required whitespace
63                 (\w+?)                  # grab the chunk name
64                 \s*                     # optional trailing whitespace
65                 $self->{post_delim}
66                 ($chunk_body)           # grab the chunk body
67                 $self->{pre_delim}
68                 \s*                     # optional leading whitespace
69                 END                     # required END token
70                 \s+                     # required whitespace
71                 \1                      # match the grabbed chunk name
72                 \s*                     # optional trailing whitespace
73                 $self->{post_delim}
74         }xi ;                           # case insensitive
75
76 #print "RE <$self->{chunk_re}>\n" ;
77
78 # this matches a include markup and grabs its template name
79
80         $self->{include_re} = qr{
81                 $self->{pre_delim}
82                 \s*                     # optional leading whitespace
83                 INCLUDE                 # required INCLUDE token
84                 \s+                     # required whitespace
85                 (\w+?)                  # grab the included template name
86                 \s*                     # optional trailing whitespace
87                 $self->{post_delim}
88         }xi ;                           # case insensitive
89
90 # load in any templates
91
92         $self->add_templates( $opts{templates} ) ;
93
94         return $self ;
95 }
96
97 sub compile {
98
99         my( $self, $template_name ) = @_ ;
100
101         my $tmpl_ref = eval {
102                  $self->_get_template( $template_name ) ;
103         } ;
104
105         croak "Template::Simple $@" if $@ ;
106
107 # compile a copy of the template as it will be destroyed
108
109         my $code_body = $self->_compile_chunk( '', "${$tmpl_ref}", "\t" ) ;
110
111         my $source = <<CODE ;
112 no warnings ;
113
114 sub {
115         my( \$data ) = \@_ ;
116
117         my \$out ;
118
119 $code_body
120         return \\\$out ;
121 }
122 CODE
123
124 #print $source ;
125
126         my $code_ref = eval $source ;
127
128 print $@ if $@ ;
129
130         $self->{compiled_cache}{$template_name} = $code_ref ;
131         $self->{source_cache}{$template_name} = $source ;
132 }
133
134 sub _compile_chunk {
135
136         my( $self, $chunk_name, $template, $indent ) = @_ ;
137
138         return '' unless length $template ;
139
140 # generate a lookup in data for this chunk name (unless it is the top
141 # level). this descends down the data tree during rendering
142
143         my $data_init = $chunk_name ? "\$data->{$chunk_name}" : '$data' ;
144
145         my $code = <<CODE ;
146 ${indent}my \@data = $data_init ;
147 ${indent}while( \@data ) {
148
149 ${indent}       my \$data = shift \@data ;
150 ${indent}       if ( ref \$data eq 'ARRAY' ) {
151 ${indent}               push \@data, \@{\$data} ;
152 ${indent}               next ;
153 ${indent}       }
154
155 CODE
156
157         $indent .= "\t" ;
158
159 # loop all nested chunks and the text separating them
160
161         while( my( $parsed_name, $parsed_body ) =
162                 $template =~ m{$self->{chunk_re}} ) {
163
164                 my $chunk_left_index = $-[0] ;
165                 my $chunk_right_index = $+[0] ;
166
167 # get the pre-match text and compile its scalars and text. append to the code
168
169                 $code .= $self->_compile_scalars(
170                         substr( $template, 0, $chunk_left_index ), $indent ) ;
171
172 # print "CHUNK: [$1] BODY [$2]\n\n" ;
173 # print "TRUNC: [", substr( $template, 0, $chunk_right_index ), "]\n\n" ;
174 # print "PRE: [", substr( $template, 0, $chunk_left_index ), "]\n\n" ;
175
176 # chop off the pre-match and the chunk
177
178                 substr( $template, 0, $chunk_right_index, '' ) ;
179
180 # print "REMAIN: [$template]\n\n" ;
181
182 # compile the nested chunk and append to the code
183
184                 $code .= $self->_compile_chunk(
185                                 $parsed_name, $parsed_body, $indent
186                 ) ;
187         }
188
189 # compile trailing text for scalars and append to the code
190
191         $code .= $self->_compile_scalars( $template, $indent ) ;
192
193         chop $indent ;
194
195 # now we end the loop for this chunk
196         $code .= <<CODE ;
197 $indent}
198 CODE
199
200         return $code ;
201 }
202
203 sub _compile_scalars {
204
205         my( $self, $template, $indent ) = @_ ;
206
207 # if the template is empty return no parts
208
209         return '' unless length $template ;
210
211         my @parts ;
212
213         while( $template =~ m{$self->{scalar_re}}g ) {
214
215 # get the pre-match text before the scalar markup and generate code to
216 # access the scalar
217
218                 push( @parts,
219                         dump_text( substr( $template, 0, $-[0] ) ),
220                         "\$data->{$1}"
221                 ) ;
222
223 # truncate the matched text so the next match starts at begining of string
224
225                 substr( $template, 0, $+[0], '' ) ;
226         }
227
228 # keep any trailing text part
229
230         push @parts, dump_text( $template ) ;
231
232         my $parts_code = join( "\n$indent.\n$indent", @parts ) ;
233
234         return <<CODE ;
235
236 ${indent}\$out .= ref \$data ne 'HASH' ? \$data :
237 ${indent}$parts_code ;
238
239 CODE
240 }
241
242
243 sub dump_text {
244
245         my( $text ) = @_ ;
246
247         return unless length $text ;
248
249         local( $Data::Dumper::Useqq ) = 1 ;
250
251         my $dumped = Dumper $text ;
252
253         $dumped =~ s/^[^"]+// ;
254         $dumped =~ s/;\n$// ;
255
256         return $dumped ;
257 }
258
259 sub get_source {
260
261         my( $self, $template_name ) = @_ ;
262
263         return $self->{source_cache}{$template_name} ;
264 }
265
266 sub render {
267
268         my( $self, $template_name, $data ) = @_ ;
269
270         my $tmpl_ref = ref $template_name eq 'SCALAR' ? $template_name : '' ;
271
272         unless( $tmpl_ref ) {
273
274 # render with cached code and return if we precompiled this template
275
276                 if ( my $compiled = $self->{compiled_cache}{$template_name} ) {
277
278                         return $compiled->($data) ;
279                 }
280
281 # not compiled so try to get this template by name or
282 # assume the template name are is the actual template
283
284                 $tmpl_ref =
285                         eval{ $self->_get_template($template_name) } ||
286                         \$template_name ;
287         }
288
289         my $rendered = $self->_render_includes( $tmpl_ref ) ;
290
291 #print "INC EXP <$rendered>\n" ;
292
293         $rendered = eval {
294                  $self->_render_chunk( $rendered, $data ) ;
295         } ;
296
297         croak "Template::Simple $@" if $@ ;
298
299         return $rendered ;
300 }
301
302 sub _render_includes {
303
304         my( $self, $tmpl_ref ) = @_ ;
305
306 # make a copy of the initial template so we can render it.
307
308         my $rendered = ${$tmpl_ref} ;
309
310 # loop until we can render no more include markups
311
312         1 while $rendered =~
313                  s{$self->{include_re}}
314                     { ${ $self->_get_template($1) }
315                   }e ;
316
317         return \$rendered ;
318 }
319
320 my %renderers = (
321
322         HASH    => \&_render_hash,
323         ARRAY   => \&_render_array,
324         CODE    => \&_render_code,
325 # if no ref then data is a scalar so replace the template with just the data
326         ''      => sub { \$_[2] },
327 ) ;
328
329
330 sub _render_chunk {
331
332         my( $self, $tmpl_ref, $data ) = @_ ;
333
334 #print "T ref [$tmpl_ref] [$$tmpl_ref]\n" ;
335 #print "CHUNK ref [$tmpl_ref] TMPL\n<$$tmpl_ref>\n" ;
336
337 #print Dumper $data ;
338
339         return \'' unless defined $data ;
340
341 # now render this chunk based on the type of data
342
343         my $renderer = $renderers{reftype $data || ''} ;
344
345 #print "EXP $renderer\nREF ", reftype $data, "\n" ;
346
347         die "unknown template data type '$data'\n" unless defined $renderer ;
348
349         return $self->$renderer( $tmpl_ref, $data ) ;
350 }
351
352 sub _render_hash {
353
354         my( $self, $tmpl_ref, $href ) = @_ ;
355
356         return $tmpl_ref unless keys %{$href} ;
357
358 # we need a local copy of the template to render
359
360         my $rendered = ${$tmpl_ref}      ;
361
362
363 # recursively render all top level chunks in this chunk
364
365         $rendered =~ s{$self->{chunk_re}}
366                       {
367                         # print "CHUNK $1\nBODY\n----\n<$2>\n\n------\n" ;
368 #                       print "CHUNK $1\nBODY\n----\n<$2>\n\n------\n" ;
369 #                       print "pre CHUNK [$`]\n" ;
370                         ${ $self->_render_chunk( \"$2", $href->{$1} ) }
371                       }gex ;
372
373 # now render scalars
374
375 #print "HREF: ", Dumper $href ;
376
377         $rendered =~ s{$self->{scalar_re}}
378                       {
379                          # print "SCALAR $1 VAL $href->{$1}\n" ;
380                          defined $href->{$1} ? $href->{$1} : ''
381                       }ge ;
382
383 #print "HASH REND3\n<$rendered>\n" ;
384
385         return \$rendered ;
386 }
387
388 sub _render_array {
389
390         my( $self, $tmpl_ref, $aref ) = @_ ;
391
392 # render this $tmpl_ref for each element of the aref and join them
393
394         my $rendered ;
395
396 #print "AREF: ", Dumper $aref ;
397
398         $rendered .= ${$self->_render_chunk( $tmpl_ref, $_ )} for @{$aref} ;
399
400         return \$rendered ;
401 }
402
403 sub _render_code {
404
405         my( $self, $tmpl_ref, $cref ) = @_ ;
406
407         my $rendered = $cref->( $tmpl_ref ) ;
408
409         die <<DIE if ref $rendered ne 'SCALAR' ;
410 data callback to code didn't return a scalar or scalar reference
411 DIE
412
413         return $rendered ;
414 }
415
416 sub add_templates {
417
418         my( $self, $tmpls ) = @_ ;
419
420 #print Dumper $tmpls ;
421         return unless defined $tmpls ;
422
423         ref $tmpls eq 'HASH' or croak "templates argument is not a hash ref" ;
424
425 # copy all the templates from the arg hash and force the values to be
426 # scalar refs
427         
428         @{ $self->{tmpl_cache}}{ keys %{$tmpls} } =
429                 map ref $_ eq 'SCALAR' ? \"${$_}" : \"$_", values %{$tmpls} ;
430
431 #print Dumper $self->{tmpl_cache} ;
432
433         return ;
434 }
435
436 sub delete_templates {
437
438         my( $self, @names ) = @_ ;
439
440 # delete all the cached stuff or just the names passed in
441
442         @names = keys %{$self->{tmpl_cache}} unless @names ;
443
444 # clear out all the caches
445 # TODO: reorg these into a hash per name
446
447         delete @{$self->{tmpl_cache}}{ @names } ;
448         delete @{$self->{compiled_cache}}{ @names } ;
449         delete @{$self->{source_cache}}{ @names } ;
450
451 # also remove where we found it to force a fresh search
452
453         delete @{$self->{template_paths}}{ @names } ;
454
455         return ;
456 }
457
458 sub _get_template {
459
460         my( $self, $tmpl_name ) = @_ ;
461
462 #print "INC $tmpl_name\n" ;
463
464         my $tmpls = $self->{tmpl_cache} ;
465
466 # get the template from the cache and send it back if it was found there
467
468         my $template = $tmpls->{ $tmpl_name } ;
469         return $template if $template ;
470
471 # not found, so find, slurp in and cache the template
472
473         $template = $self->_find_template( $tmpl_name ) ;
474         $tmpls->{ $tmpl_name } = $template ;
475
476         return $template ;
477 }
478
479 sub _find_template {
480
481         my( $self, $tmpl_name ) = @_ ;
482
483         foreach my $dir ( @{$self->{include_paths}} ) {
484
485                 my $tmpl_path = "$dir/$tmpl_name.tmpl" ;
486
487 #print "PATH: $tmpl_path\n" ;
488                 next unless -r $tmpl_path ;
489
490 # cache the path to this template
491
492                 $self->{template_paths}{$tmpl_name} = $tmpl_path ;
493
494 # slurp in the template file and return it as a scalar ref
495
496                 return scalar read_file( $tmpl_path, scalar_ref => 1 ) ;
497         }
498
499         die <<DIE ;
500 can't find template '$tmpl_name' in '@{$self->{include_paths}}'
501 DIE
502
503 }
504
505 1; # End of Template::Simple
506
507 __END__
508
509 =head1 NAME
510
511 Template::Simple - A simple and fast template module
512
513 =head1 VERSION
514
515 Version 0.03
516
517 =head1 SYNOPSIS
518
519     use Template::Simple;
520
521     my $tmpl = Template::Simple->new();
522
523     my $template = <<TMPL ;
524 [%INCLUDE header%]
525 [%START row%]
526         [%first%] - [%second%]
527 [%END row%]
528 [%INCLUDE footer%]
529 TMPL
530
531     my $data = {
532         header  => {
533                 date    => 'Jan 1, 2008',
534                 author  => 'Me, myself and I',
535         },
536         row     => [
537                 {
538                         first   => 'row 1 value 1',
539                         second  => 'row 1 value 2',
540                 },
541                 {
542                         first   => 'row 2 value 1',
543                         second  => 'row 2 value 2',
544                 },
545         ],
546         footer  => {
547                 modified        => 'Aug 31, 2006',
548         },
549     } ;
550
551     my $rendered = $tmpl->render( $template, $data ) ;
552
553 =head1 DESCRIPTION
554
555 Template::Simple has these goals:
556
557 =over 4
558
559 =item * Support most common template operations
560
561 It can recursively include other templates, replace tokens (scalars),
562 recursively render nested chunks of text and render lists. By using
563 simple idioms you can get conditional renderings.
564
565 =item * Complete isolation of template from program code
566
567 This is very important as template design can be done by different
568 people than the program logic. It is rare that one person is well
569 skilled in both template design and also programming.
570
571 =item * Very simple template markup (only 4 markups)
572
573 The only markups are C<INCLUDE>, C<START>, C<END> and C<token>. See
574 MARKUP for more.
575
576 =item * Easy to follow rendering rules
577
578 Rendering of templates and chunks is driven from a data tree. The type
579 of the data element used in an rendering controls how the rendering
580 happens.  The data element can be a scalar or scalar reference or an
581 array, hash or code reference.
582
583 =item * Efficient template rendering
584
585 Rendering is very simple and uses Perl's regular expressions
586 efficiently. Because the markup is so simple less processing is needed
587 than many other templaters. Precompiling templates is not supported
588 yet but that optimization is on the TODO list.
589
590 =item * Easy user extensions
591
592 User code can be called during an rendering so you can do custom
593 renderings and plugins. Closures can be used so the code can have its
594 own private data for use in rendering its template chunk.
595
596 =back
597
598 =head2 new()
599
600 You create a Template::Simple by calling the class method new:
601
602         my $tmpl = Template::Simple->new() ;
603
604 All the arguments to C<new()> are key/value options that change how
605 the object will do renderings.
606
607 =over 4
608
609 =item   pre_delim
610
611 This option sets the string or regex that is the starting delimiter
612 for all markups. You can use a plain string or a qr// but you need to
613 escape (with \Q or \) any regex metachars if you want them to be plain
614 chars. The default is qr/\[%/.
615
616         my $tmpl = Template::Simple->new(
617                 pre_delim => '<%',
618         );
619
620         my $rendered = $tmpl->render( '<%FOO%]', 'bar' ) ;
621
622 =item   post_delim
623
624 This option sets the string or regex that is the ending delimiter
625 for all markups. You can use a plain string or a qr// but you need to
626 escape (with \Q or \) any regex metachars if you want them to be plain
627 chars. The default is qr/%]/.
628
629         my $tmpl = Template::Simple->new(
630                 post_delim => '%>',
631         );
632
633         my $rendered = $tmpl->render( '[%FOO%>', 'bar' ) ;
634
635 =item   greedy_chunk
636
637 This boolean option will cause the regex that grabs a chunk of text
638 between the C<START/END> markups to become greedy (.+). The default is
639 a not-greedy grab of the chunk text. (UNTESTED)
640
641 =item   templates
642
643 This option lets you load templates directly into the cache of the
644 Template::Simple object. This cache will be searched by the C<INCLUDE>
645 markup which will be replaced by the template if found. The option
646 value is a hash reference which has template names (the name in the
647 C<INCLUDE> markup) for keys and their template text as their
648 values. You can delete or clear templates from the object cache with
649 the C<delete_template> method.
650
651
652         my $tmpl = Template::Simple->new(
653                 templates       => {
654
655                         foo     => <<FOO,
656 [%baz%] is a [%quux%]
657 FOO
658                         bar     => <<BAR,
659 [%user%] is not a [%fool%]
660 BAR
661                 },
662         );
663
664         my $template = <<TMPL ;
665 [%INCLUDE foo %]
666 TMPL
667
668         my $rendered = $tmpl->render(
669                 $template,
670                 {
671                         baz => 'blue',
672                         quux => 'color,
673                 }
674         ) ;
675
676 =item   include_paths
677
678 Template::Simple can also load C<INCLUDE> templates from files. This
679 option lets you set the directory paths to search for those
680 files. Note that the template name in the C<INCLUDE> markup has the
681 .tmpl suffix appended to it when searched for in one of these
682 paths. The loaded file is cached inside the Template::Simple object
683 along with any loaded by the C<templates> option.
684
685 =back
686
687 =head1 METHODS
688
689 =head2 render
690
691 This method is passed a template and a data tree and it renders it and
692 returns a reference to the resulting string. The template argument can
693 be a scalar or a scalar reference. The data tree argument can be any
694 value allowed by Template::Simple when rendering a template. It can
695 also be a blessed reference (Perl object) since
696 C<Scalar::Util::reftype> is used instead of C<ref> to determine the
697 data type.
698
699 Note that the author recommends against passing in an object as this
700 breaks encapsulation and forces your object to be (most likely) a
701 hash. It would be better to create a simple method that copies the
702 object contents to a hash reference and pass that. But current
703 templaters allow passing in objects so that is supported here as well.
704
705     my $rendered = $tmpl->render( $template, $data ) ;
706
707 =head2 add_templates
708
709 This method adds templates to the object cache. It takes a list of template names and texts just like the C<templates> constructor option.
710
711         $tmpl->add_templates( 
712                 {
713                         foo     => \$foo_template,
714                         bar     => '[%include bar%]',
715                 }
716         ) ;
717
718 =head2 delete_templates
719
720 This method takes a list of template names and will delete them from
721 the template cache in the object. If you pass in an empty list then
722 all the templates will be deleted. This can be used when you know a
723 template file has been updated and you want to get it loaded back into
724 the cache. Note that you can delete templates that were loaded
725 directly (via the C<templates> constructor option or the
726 C<add_templates> method) or loaded from a file.
727
728     # this deletes only the foo and bar templates from the object cache
729
730         $tmpl->delete_templates( qw( foo bar ) ;
731
732     # this deletes all of templates from the object cache
733
734         $tmpl->delete_templates() ;
735
736 =head2 get_dependencies
737
738 This method render the only C<INCLUDE> markups of a template and it
739 returns a list of the file paths that were found and loaded. It is
740 meant to be used to build up a dependency list of included templates
741 for a main template. Typically this can be called from a script (see
742 TODO) that will do this for a set of main templates and will generate
743 Makefile dependencies for them. Then you can regenerate rendered
744 templates only when any of their included templates have changed. It
745 takes a single argument of a template.
746
747 UNKNOWN: will this require a clearing of the cache or will it do the
748 right thing on its own? or will it use the file path cache?
749
750         my @dependencies =
751                 $tmpl->get_dependencies( '[%INCLUDE top_level%]' );
752
753 =head1 MARKUP
754
755 All the markups in Template::Simple use the same delimiters which are
756 C<[%> and C<%]>. You can change the delimiters with the C<pre_delim>
757 and C<post_delim> options in the C<new()> constructor.
758
759 =head2 Tokens
760
761 A token is a single markup with a C<\w+> Perl word inside. The token
762 can have optional whitespace before and after it. A token is replaced
763 by a value looked up in a hash with the token as the key. The hash
764 lookup keeps the same case as parsed from the token markup.
765
766     [% foo %] [%BAR%]
767
768 Those will be replaced by C<$href->{foo}> and C<$href->{BAR}> assuming
769 C<$href> is the current data for this rendering. Tokens are only
770 parsed out during hash data rendering so see Hash Data for more.
771
772 =head2 Chunks
773
774 Chunks are regions of text in a template that are marked off with a
775 start and end markers with the same name. A chunk start marker is
776 C<[%START name%]> and the end marker for that chunk is C<[%END
777 name%]>. C<name> is a C<\w+> Perl word which is the name of this
778 chunk. The whitespace between C<START/END> and C<name> is required and
779 there is optional whitespace before C<START/END> and after the
780 C<name>. C<START/END> are case insensitive but the C<name>'s case is
781 kept. C<name> must match in the C<START/END> pair and it used as a key
782 in a hash data rendering. Chunks are the primary way to markup
783 templates for structures (sets of tokens), nesting (hashes of hashes),
784 repeats (array references) and callbacks to user code. Chunks are only
785 parsed out during hash data rendering so see Hash Data for more.
786
787 The body of text between the C<START/END> markups is grabbed with a
788 C<.+?> regular expression with the /s option enabled so it will match
789 all characters. By default it will be a non-greedy grab but you can
790 change that in the constructor by enabling the C<greedy_chunk> option.
791
792     [%Start FOO%]
793         [% START bar %]
794                 [% field %]
795         [% end bar %]
796     [%End FOO%]
797
798 =head2 Includes
799
800 =head1 RENDERING RULES
801
802 Template::Simple has a short list of rendering rules and they are easy
803 to understand. There are two types of renderings, include rendering
804 and chunk rendering. In the C<render> method, the template is an
805 unnamed top level chunk of text and it first gets its C<INCLUDE>
806 markups rendered. The text then undergoes a chunk rendering and a
807 scalar reference to that rendered template is returned to the caller.
808
809 =head2 Include Rendering
810
811 Include rendering is performed one time on a top level template. When
812 it is done the template is ready for chunk rendering.  Any markup of
813 the form C<[%INCLUDE name]%> will be replaced by the text found in the
814 template C<name>. The template name is looked up in the object's
815 template cache and if it is found there its text is used as the
816 replacement.
817
818 If a template is not found in the cache, it will be searched for in
819 the list of directories in the C<include_paths> option. The file name
820 will be a directory in that list appended with the template name and
821 the C<.tmpl> suffix. The first template file found will be read in and
822 stored in the cache. Its path is also saved and those will be returned
823 in the C<get_dependencies> method. See the C<add_templates> and
824 C<delete_templates> methods and the C<include_paths> option.
825
826 Rendered include text can contain more C<INCLUDE> markups and they
827 will also be rendered. The include rendering phase ends where there
828 are no more C<INCLUDE> found.
829
830 =head2 Chunk Rendering
831
832 A chunk is the text found between C<START> and C<END> markups and it
833 gets its named from the C<START> markup. The top level template is
834 considered an unamed chunk and also gets chunk rendered.
835
836 The data for a chunk determines how it will be rendered. The data can
837 be a scalar or scalar reference or an array, hash or code
838 reference. Since chunks can contain nested chunks, rendering will
839 recurse down the data tree as it renders the chunks.  Each of these
840 renderings are explained below. Also see the IDIOMS and BEST PRACTICES
841 section for examples and used of these renderings.
842
843 =head2 Scalar Data Rendering
844
845 If the current data for a chunk is a scalar or scalar reference, the
846 chunk's text in the templated is replaced by the scalar's value. This
847 can be used to overwrite one default section of text with from the
848 data tree.
849
850 =head2 Code Data Rendering
851
852 If the current data for a chunk is a code reference (also called
853 anonymous sub) then the code reference is called and it is passed a
854 scalar reference to the that chunk's text. The code must return a
855 scalar or a scalar reference and its value replaces the chunk's text
856 in the template. If the code returns any other type of data it is a
857 fatal error. Code rendering is how you can do custom renderings and
858 plugins. A key idiom is to use closures as the data in code renderings
859 and keep the required outside data in the closure.
860
861 =head2 Array Data Rendering
862
863 If the current data for a chunk is an array reference do a full chunk
864 rendering for each value in the array. It will replace the original
865 chunk text with the joined list of rendered chunks. This is how you do
866 repeated sections in Template::Simple and why there is no need for any
867 loop markups. Note that this means that rendering a chunk with $data
868 and [ $data ] will do the exact same thing. A value of an empty array
869 C<[]> will cause the chunk to be replaced by the empty string.
870
871 =head2 Hash Data Rendering
872
873 If the current data for a chunk is a hash reference then two phases of
874 rendering happen, nested chunk rendering and token rendering. First
875 nested chunks are parsed of of this chunk along with their names. Each
876 parsed out chunk is rendered based on the value in the current hash
877 with the nested chunk's name as the key.
878
879 If a value is not found (undefined), then the nested chunk is replaced
880 by the empty string. Otherwise the nested chunk is rendered according
881 to the type of its data (see chunk rendering) and it is replaced by
882 the rendered text.
883
884 Chunk name and token lookup in the hash data is case sensitive (see
885 the TODO for cased lookups).
886
887 Note that to keep a plain text chunk or to just have the all of its
888 markups (chunks and tokens) be deleted just pass in an empty hash
889 reference C<{}> as the data for the chunk. It will be rendered but all
890 markups will be replaced by the empty string.
891
892 =head2 Token Rendering
893
894 The second phase is token rendering. Markups of the form [%token%] are
895 replaced by the value of the hash element with the token as the
896 key. If a token's value is not defined it is replaced by the empty
897 string. This means if a token key is missing in the hash or its value
898 is undefined or its value is the empty string, the [%token%] markup
899 will be deleted in the rendering.
900
901 =head1 IDIOMS and BEST PRACTICES
902
903 With all template systems there are better ways to do things and
904 Template::Simple is no different. This section will show some ways to
905 handle typical template needs while using only the 4 markups in this
906 module. 
907
908 =head2 Conditionals
909
910 This conditional idiom can be when building a fresh data tree or
911 modifying an existing one.
912
913         $href->{$chunk_name} = $keep_chunk ? {} : '' ;
914
915 If you are building a fresh data tree you can use this idiom to do a
916 conditional chunk:
917
918         $href->{$chunk_name} = {} if $keep_chunk ;
919
920 To handle an if/else conditional use two chunks, with the else chunk's
921 name prefixed with NOT_ (or use any name munging you want). Then you
922 set the data for either the true chunk (just the plain name) or the
923 false trunk with the NOT_ name. You can use a different name for the
924 else chunk if you want but keeping the names of the if/else chunks
925 related is a good idea. Here are two ways to set the if/else data. The
926 first one uses the same data for both the if and else chunks and the
927 second one uses different data so the it uses the full if/else code
928 for that.
929
930         $href->{ ($boolean ? '' : 'NOT_') . $chunk_name} = $data
931
932         if ( $boolean ) {
933                 $href->{ $chunk_name} = $true_data ;
934         else {
935                 $href->{ "NOT_$chunk_name" } = $false_data ;
936         }
937
938 NOTE TO ALPHA USERS: i am also thinking that a non-existing key or
939 undefined hash value should leave the chunk as is. then you would need
940 to explicitly replace a chunk with the empty string if you wanted it
941 deleted.  It does affect the list of styles idiom. Any thoughts on
942 this change of behavior? Since this hasn't been released it is the
943 time to decide this.
944
945 =head2 Chunked Includes
946
947 One of the benefits of using include templates is the ability to share
948 and reuse existing work. But if an included template has a top level
949 named chunk, then that name would also be the same everywhere where
950 this template is included. If a template included another template in
951 multiple places, its data tree would use the same name for each and
952 not allow unique data to be rendered for each include. A better way is
953 to have the current template wrap an include markup in a named chunk
954 markup. Then the data tree could use unique names for each included
955 template. Here is how it would look:
956
957         [%START foo_prime%][%INCLUDE foo%][%START foo_prime%]
958         random noise
959         [%START foo_second%][%INCLUDE foo%][%START foo_second%]
960
961 See the TODO section for some ideas on how to make this even more high level.
962
963 =head2 Repeated Sections
964
965 If you looked at the markup of Template::Simple you have noticed that
966 there is no loop or repeat construct. That is because there is no need
967 for one. Any chunk can be rendered in a loop just by having its
968 rendering data be an anonymous array. The renderer will loop over each
969 element of the array and do a fresh rendering of the chunk with this
970 data. A join (on '') of the list of renderings replaces the original
971 chunk and you have a repeated chunk.
972
973 =head2 A List of Mixed Styles
974
975 One formating style is to have a list of sections each which can have
976 its own style or content. Template::Simple can do this very easily
977 with just a 2 level nested chunk and an array of data for
978 rendering. The outer chunk includes (or contains) each of the desired
979 styles in any order. It looks like this:
980
981         [%START para_styles%]
982                 [%START main_style%]
983                         [%INCLUDE para_style_main%]
984                 [%END main_style%]
985                 [%START sub_style%]
986                         [%INCLUDE para_style_sub%]
987                 [%END sub_style%]
988                 [%START footer_style%]
989                         [%INCLUDE para_style_footer%]
990                 [%END footer_style%]
991         [%END para_styles%]
992
993 The other part to make this work is in the data tree. The data for
994 para_styles should be a list of hashes. Each hash contains the data
995 for one pargraph style which is keyed by the style's chunk name. Since
996 the other styles's chunk names are not hash they are deleted. Only the
997 style which has its name as a key in the hash is rendered. The data
998 tree would look something like this:
999
1000         [
1001                 {
1002                         main_style => $main_data,
1003                 },
1004                 {
1005                         sub_style => $sub_data,
1006                 },
1007                 {
1008                         sub_style => $other_sub_data,
1009                 },
1010                 {
1011                         footer_style => $footer_data,
1012                 },
1013         ]
1014
1015 =head1 TESTS
1016
1017 The test scripts use a common test driver module in t/common.pl. It is
1018 passed a list of hashes, each of which has the data for one test. A
1019 test can create a ne Template::Simple object or use the one from the
1020 previous test. The template source, the data tree and the expected
1021 results are also important keys. See the test scripts for examples of
1022 how to write tests using this common driver.
1023
1024 =over 4
1025
1026 =item name
1027
1028 This is the name of the test and is used by Test::More
1029
1030 =item opts
1031
1032 This is a hash ref of the options passed to the Template::Simple
1033 constructor.  The object is not built if the C<keep_obj> key is set.
1034
1035 =item keep_obj
1036
1037 If set, this will make this test keep the Template::Simple object from
1038 the previous test and not build a new one.
1039
1040 =item template
1041
1042 This is the template to render for this test. If not set, the test
1043 driver will use the template from the previous test. This is useful to
1044 run a series of test variants with the same template.
1045
1046 =item data
1047
1048 This is the data tree for the rendering of the template.
1049
1050 =item expected
1051
1052 This is the text that is expected after the rendering.
1053
1054 =item skip
1055
1056 If set, this test is skipped.
1057
1058 =back
1059
1060 =head1 TODO
1061
1062 Even though this template system is simple, that doesn't mean it can't
1063 be extended in many ways. Here are some features and designs that
1064 would be good extensions which add useful functionality without adding
1065 too much complexity.
1066
1067 =head2 Compiled Templates
1068
1069 A commonly performed optimization in template modules is to precompile
1070 (really preparse) templates into a internal form that will render
1071 faster.  Precompiling is slower than rendering from the original
1072 template which means you won't want to do it for each rendering. This
1073 means it has a downside that you lose out when you want to render
1074 using templates which change often. Template::Simple makes it very
1075 easy to precompile as it already has the regexes to parse out the
1076 markup. So instead of calling subs to do actual rendering, a
1077 precompiler would call subs to generate a compiled rendering tree.
1078 The rendering tree can then be run or processes with rendering data
1079 passed to it. You can think of a precompiled template as having all
1080 the nested chunks be replaced by nested code that does the same
1081 rendering. It can still do the dynamic rendering of the data but it
1082 saves the time of parsing the template souice. There are three
1083 possible internal formats for the precompiled template:
1084
1085 =over 4
1086
1087 =item Source code
1088
1089 This precompiler will generate source code that can be stored and/or
1090 eval'ed.  The eval'ed top level sub can then be called and passed the
1091 rendering data.
1092
1093 =item Closure call tree
1094
1095 The internal format can be a nested set of closures. Each closure would contain
1096 private data such as fixed text parts of the original template, lists
1097 of other closures to run, etc. It is trivial to write a basic closure
1098 generator which will make build this tree a simple task. 
1099
1100 =item Code ref call tree
1101
1102 This format is a Perl data tree where the nodes have a code reference
1103 and its args (which can be nested instances of the same
1104 nodes). Instead of executing this directly, you will need a small
1105 interpreter to execute all the code refs as it runs through the tree.
1106
1107 This would make for a challenging project to any intermediate Perl
1108 hacker. It just involves knowing recursion, data trees and code refs.
1109 Contact me if you are interested in doing this.
1110
1111 =back
1112
1113 =head2 Cased Hash Lookups
1114
1115 One possible option is to allow hash renderings to always use upper or
1116 lower cased keys in their lookups.
1117
1118 =head2 Render tokens before includes and chunks
1119
1120 Currently tokens are rendered after includes and chunks. If tokens
1121 were rendered in a pass before the others, the include and chunk names
1122 could be dynamically set. This would make it harder to precompile
1123 templates as too much would be dynamic, i.e. you won't know what the
1124 fixed text to parse out is since anything can be included at render
1125 time. But the extra flexibility of changing the include and chunk
1126 names would be interesting. It could be done easily and enabled by an
1127 option.
1128
1129 =head2 Plugins
1130
1131 There are two different potential areas in Template::Simple that could
1132 use plugins. The first is with the rendering of chunkas and
1133 dispatching based on the data type. This dispatch table can easily be
1134 replaced by loaded modules which offer a different way to
1135 render. These include the precompiled renderers mentioned above. The
1136 other area is with code references as the data type. By defining a
1137 closure (or a closure making) API you can create different code refs
1138 for the rendering data. The range of plugins is endless some of the
1139 major template modules have noticed. One idea is to make a closure
1140 which contains a different Template::Simple object than the current
1141 one. This will allow rendering of a nested chunk with different rules
1142 than the current chunk being rendered.
1143
1144 =head2 Data Escaping
1145
1146 Some templaters have options to properly escape data for some types of
1147 text files such as html. this can be done with some variant of the
1148 _render_hash routine which also does the scalar rendering (which is
1149 where data is rendered). The rendering scalars code could be factored
1150 out into a set of subs one of which is used based on any escaping
1151 needs.
1152
1153 =head2 Data Tree is an Object
1154
1155 This is a concept I don't like but it was requested so it goes into
1156 the TODO file. Currently C<render> can only be passed a regular
1157 (unblessed) ref (or a scalar) for its data tree. Passing in an object
1158 would break encapsulation and force the object layout to be a hash
1159 tree that matches the layout of the template. I doubt that most
1160 objects will want to be organized to match a template. I have two
1161 ideas, one is that you add a method to that object that builds up a
1162 proper (unblessed) data tree to pass to C<render>. The other is by
1163 subclassing C<Template::Simple> and overriding C<render> with a sub
1164 that does take an object hash and it can unbless it or build a proper
1165 data tree and then call C<render> in SUPER::. A quick solution is to
1166 use C<reftype> (from Scalar::Utils) instead of C<ref> to allow object
1167 hashes to be passed in.
1168
1169 =head2 Includes and Closure Synergy
1170
1171 By pairing up an include template along with code that can generate
1172 the appropriate data tree for its rendering, you can create a higher
1173 level template framework (the synergy). Additional code can be
1174 associated with them that will handle input processing and
1175 verification for the templates (e.g. web forms) that need it. A key to
1176 this will be making all the closures for the data tree. This can be
1177 greatly simplified by using a closure maker sub that can create all
1178 the required closures.
1179
1180 =head2 Metafields and UI Generation
1181
1182 Taking the synergy up to a much higher level is the concept of meta
1183 knowledge of fields which can generate templates, output processing
1184 (data tree generation), input processing, DB backing and more. If you
1185 want to discuss such grandiose wacky application schemes in a long
1186 rambling mind bending conversation, please contact me.
1187
1188 =head2 More Examples and Idioms
1189
1190 As I convert several scripts over to this module (they all used the
1191 hack version), I will add them to an examples section or possibly put
1192 them in another (pod only) module. Similarly the Idioms section needs
1193 rendering and could be also put into a pod module. One goal requested
1194 by an early alpha tester is to keep the primary docs as simple as the
1195 markup itself. This means moving all the extra stuff (and plenty of
1196 that) into other pod modules. All the pod modules would be in the same
1197 cpan tarball so you get all the docs and examples when you install
1198 this.
1199
1200 =head1 AUTHOR
1201
1202 Uri Guttman, C<< <uri at sysarch.com> >>
1203
1204 =head1 BUGS
1205
1206 Please report any bugs or feature requests to
1207 C<bug-template-simple at rt.cpan.org>, or through the web interface at
1208 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Simple>.
1209 I will be notified, and then you'll automatically be notified of progress on
1210 your bug as I make changes.
1211
1212 =head1 SUPPORT
1213
1214 You can find documentation for this module with the perldoc command.
1215
1216     perldoc Template::Simple
1217
1218 You can also look for information at:
1219
1220 =over 4
1221
1222 =item * RT: CPAN's request tracker
1223
1224 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Template-Simple>
1225
1226 =item * Search CPAN
1227
1228 L<http://search.cpan.org/dist/Template-Simple>
1229
1230 =back
1231
1232 =head1 ACKNOWLEDGEMENTS
1233
1234 I wish to thank Turbo10 for their support in developing this module.
1235
1236 =head1 COPYRIGHT & LICENSE
1237
1238 Copyright 2006 Uri Guttman, all rights reserved.
1239
1240 This program is free software; you can redistribute it and/or modify it
1241 under the same terms as Perl itself.
1242
1243 =cut
1244
1245
1246 find templates and tests
1247
1248 deep nesting tests
1249
1250 greedy tests
1251
1252 methods pod
1253
1254 delete_templates test
1255
1256 pod cleanup
1257
1258 fine edit
1259
1260 more tests
1261
1262 slurp dependency in makefile.pl
1263