The following lists detail pending items, known bugs and possible future
enhancements planned for the Template Toolkit.


#------------------------------------------------------------------------
# PENDING
# 
# The following items are planned for an imminent release.  Most of 
# these are current works-in-progress.
#------------------------------------------------------------------------

* Apache::Template.  It is currently fairly easy to use the Template
  Toolkit from within an Apache/mod_perl handler (see Template::Tutorial), 
  but in many cases it would be nicer not to have to write any handler 
  at all and just use a standard module.

* Documentation.  The current Template document is large (100+ pages)
  and rather unwieldy.  Stas Beckman <stas@stason.org> has sent me
  some code which uses Pod::HtmlPsPdf to build build all the
  documentation into an HTML, PostScript or PDF book.  This just
  requires a little debugging and some configuration before it's ready
  to roll.

* Pod::Template and 'ttpod' utility.  Further to the above, I'm
  working on a POD to Template translator that will allow you to
  convert any POD documents (include the TT docs, of course) into TT
  templates that can then be processed into virtually any other format
  or style.

* Template Toolkit FAQ.

* Template::Internals.  A document about the internals describing how,
  where and why to hack on them.

* "Camelot!", "Camelot!", "Camelot!"  (It's only a model).  See 
   http://www.template-toolkit.org/camelot/ for further info.


#------------------------------------------------------------------------
# KNOWN BUGS AND/OR LIMITATIONS
#
# These are minor bugs or limitations that may need attention at some
# point in the future.
#------------------------------------------------------------------------

* The Text::Autoformat module has some problems with versions of Perl
  prior to 5.6.0 when using a locale which has a decimal separator
  other than '.' (e.g. Swedish, which uses ',').  Damian has been made
  aware of the problem.  For now, the Makefile.PL issues a warning but
  continues regardless.

* The childrenTotemplate() and allChildrenToTemplate() methods of the 
  XML::DOM can send Perl into a deep recursive loop.  This will be 
  fixed RSN, but first requires a little rethink.  The XML::DOM module
  itself seems to be a little unstable in general.  I've had to disable 
  one of the tests in t/dom.t which tests the parser creation failing,
  as it seems to be causing a segfault core dump during global cleanup
  a the end of the script.

* Filters and plugins cache may bloat.  Perhaps reset() should accept
  flags to clear BLOCKS, PLUGINS, FILTERS, etc?  I need to check this.

* If you use 'ttree' with a COMPILE_EXT or COMPILE_DIR option then
  templates in the 'lib' directories will be compiled, but those in
  the src directories will not.  This is because ttree does a chdir()
  to the src directory and processes files as './myfile'.  TT doesn't
  compile RELATIVE files by default.

* No recursion checking is performed for BLOCKs, only
  Template::Document instances.  This is probably the way it will stay
  (unless anyone shouts loudly enough) but it should be documented
  anyway.  STOP PRESS: I had an idea that bare BLOCK subs should be
  blessed into Template::Document class to allow $template->process()
  to be called regardless.  Template::Document methods would need to
  test $self for CODE/HASH and Do The Right Thing.  This would then
  allow recursion testing for BLOCKs as well as Template::Document
  objects.

* The parser isn't as intelligent as it could be about blocks of template
  code commented out en masse.  The pre-scanner find the first terminating 
  '%]' (or END_TAG) after an opening tag, regardless of it being on a 
  commented line or not.
  e.g.
    [%#
      # 
      #  [% INCLUDE blah %] <- directive ends here
      #  foo                <- this gets printed
    %]

#------------------------------------------------------------------------
# FUTURE ENHANCEMENTS
#
# Things that might get added to a future release.
#------------------------------------------------------------------------

* PLUGINS could accept a reference to an object which is used as a 
  singleton factory for a plugin.

* A ':preload' use option to Template.pm to preload all modules?  Or
  should it be ':noload' and have them preloaded by default? 

* A 'FOR', like 'FOREACH' but without using an iterator.  You wouldn't get 
  the 'loop' reference to test 'first', 'last', etc., against, but it would
  be faster for those cases when you didn't need it.

* It should be possible to access template BLOCK definitions via the 
  'template' variable.  This would be particularly useful in conjunction
  with the PRE_PROCESS, PROCESS and/or POST_PROCESS options, e.g.

    <table>
    <tr>
      <td>[% INCLUDE $template.blocks.sidebar %]</td>
      <td>[% INCLUDE $template %]
    </tr>
    </table>

  Currently you *can* access these blocks, but the stash automatically
  calls these unblessed subs, generating an error due to the fact that 
  no context reference is passed to the sub to allow it to act as a 
  template.

* It would be useful if template components had some notion of inheritance
  so that a 'derived' component could call on the 'super' component.  
  This can probably best be acheived by means of a Template::Component
  object, derived from Template::Document, which has a super() method
  (and maybe many other magical methods).  The super() method would 
  return a reference to another "parent" template which could be processed
  by a directive of the form [% INCLUDE $component.super %]

* I've written a version of Template::Stash in XS which should give a 
  significant speedup to the runtime processing.  It's 95% complete and 
  just needs some minor debugging and testing.  The new Template::Stash
  will automatically load the existing Perl version if you don't have
  a C compiler on your platform (shame on you!)

* The core parser FSM loop could also be implemented in XS to bring
  some speeds-ups there.  Better still would be to rewrite the entire
  parser in C/YACC.  This is entirely feasible now that we only have
  to transform the input text (template) to output text (Perl) and
  don't have to build any significant Perl structure.  It's not
  entirely trivial - the scanner in particular has to handle CHOMP
  options and user-definable TAGS, but it's certainly possible.

* Merge Directive.pm into Parse.yp via template process.

* An alternate parser back end could generate code which bypasses the
  stash altogether, based on Doug Steinwand's strategy.  The V2
  generated Perl code is much faster than V1 but still falls short of
  what Doug has shown is possible.  His parser gets the massive
  speed-up by bypassing the stash altogether (which in V1 was
  particularly hideous) and directly generating code to walk the stash
  structure and do the right thing.  A little magic was lost, so for
  this version I've stuck with the full-blown stash approach which
  provides all the magic for backwards compatibility, albeit at some
  trade-off in speed.  Nevertheless, compiled V2 templates should
  easily run twice as fast as under V1.  My current idea is to
  hack the parser to generate more explicit stash navigation code
  which uses direct access where the type can be grokked in advanced
  (i.e. a NUMBER implies the parent is an ARRAY).  I'm also wondering
  if we could add the '->' operator as a clue to the parser to do
  direct access rather than stash access.  e.g.  
  
    [% something->first %] => $stash->{'something'}->{'first'} 
    [% something.first %]  => $stash->get('something', 0, 'first', 0)
  
  The second example is as per the current V2 beta and allows
  'something' to be either a hash with a 'first' member (which may be
  a sub-routine which is then called), or an object with a 'first'
  method, or a list from which the first item is returned, etc., etc.
  All magic is intact.  The first example runs much faster and in
  those cases when you know you haven't got any magical variables,
  this is a Good Thing.  Doug used a combination of -> and () to give
  enough clues to Do The Right Thing most of the time, so I'm hoping
  that we will be able to incorporate some of those ideas some time
  soon.


