#============================================================================
#
# Template Toolkit TODO
#
# DESCRIPTION
#   Outstanding bugs, planned features, improvements, ideas, etc.
#
# AUTHOR
#   Andy Wardley   <abw@cre.canon.co.uk>
#
#----------------------------------------------------------------------------
#
# $Id: TODO,v 1.50 1999/11/03 01:20:16 abw Exp $
#
#============================================================================

Bugs
----
  * CATCH installs a block which overwrites any previous one.  This then 
    perists until the Context object is destroyed or the handler re-defined.

  * I don't think Tied Hashes get treated as regular hashes, but they 
    should.

  * Cannot create an empty list.

Possible Features
----------------
  * TRY to scope CATCH?

  * General-purpose DEBUG option which can activate *limited* debug operations
    (e.g. for tracing undefined values at runtime) 

  * PERL directive to encapsulate Perl code.  Stash variables could be 
    made available.  This should be delegated to Text::Template, or to 
    Template::Perl which is, or delegates to Text::Template.

  * An option to bind subs in a Perl namespace into a template namespace
    without requiring the specific binding to every function.

  * add INSERT directive to insert a file without processing it.  

  * add document information structures as runtime variables (e.g. file.name
    file.mod, template.name, system.time, etc).  As of 0.28, we do get the
    'filename' variable set, which is a start.

General Improvements
--------------------

  * Should plugins be able to throw exceptions on creation failure
    rather than reporting errors via Template::Plugin::fail() and 
    returning undef?

  * should you be able to break out of an IF block?  At present, if you 
    BREAK outside of a FOREACH, then a STATUS_DONE value is returned to
    the caller.

  * It is currently impossible to create a list and then pass the members 
    of that list to a code ref/method.  The following would pass the list
    reference to the code, not the items in the list.
      [% things = [ b c a ]; do_something(things) %]

  * At some point the 'cache' (really a file loader) should be
    modified to work in a more generic resource brokering role.  This
    could then be re-used for loading and caching code components.

  * The parser could issue warnings

  * The parser could return a Template::Document type encapsulating
    template information (and warnings, etc.) rather than a bare
    block.

  * FOREACH should create a hash iterator to return a structure representing 
    each hash key/value pair.

  * improve runtime debugging if possible to do this without incurring 
    any significant overhead when not using it.  One strategy might be 
    to enable a debugging-aware parser which inserts debugging directives
    into the template context.  These would then be processed at runtime.

Documentation
-------------

  * There's very little documentation describing the available filters.

  * note that object methods get called with the RHS as a parameter when 
    specified as an lvalue of an assignment.  e.g. [% foo.bar = 10 %]
    => $foo_obj->bar(10)

  * iterator options specified through list construct parameters are
    not documented.  This is probably a Good Thing.  :-)=
    [% FOREACH user = [ foo bar baz ]( order = 'sorted', action = coderef ) %]

  * write more detailed description on extending the Template Toolkit.

Other plugins, modules, scripts
-------------------------------

  * finish Apache::Template (after speaking with SAM, I think we reached 
    the conclusion that it's so easy to write your own Apache handler
    that there's no point in trying to create a generic one.  Still, it
    would be nice to have an example that people could work from)

  * extend 'format' to perform date formatting?  (probably better to 
    do this via a 'date' plugin)

  * 'filemap' plugin to map a namespace to an INCLUDE 'file' directive.
    e.g.   [% USE html=filemap('html') %]
           [% html.header(title='Test') %] 
    equivalent to:
	   [% INCLUDE html/header title='Test' %]

ttree
-----
  * Better documentation describing the use of ttree in building document
    systems.  Examples of web sites, using config profiles, defining 
    template variables in 'config' templates that get pre-processed, etc.


