#============================================================================
#
# Template Toolkit TODO
#
# DESCRIPTION
#   Outstanding bugs, planned features, improvements, ideas, etc.
#
# AUTHOR
#   Andy Wardley   <abw@cre.canon.co.uk>
#
#----------------------------------------------------------------------------
#
# $Id: TODO,v 1.23 1999/08/04 19:18:07 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.

Planned Features
----------------
  * Add BREAK directive to exit block

  * TAG_STYLE should be switchable on a per-template basis.

  * re-implement FILTER

  * add IMPORT (and EXPORT?) directives

  * TRY to scope CATCH?
 
  * 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.  This 
    suggests an altenate cache will be required and points to the fact 
    that it may be time to develop a more generic broker to handle 
    loading, compiling and caching of resources such as template documents
    (INCLUDE), raw text files (INSERT) and library code (USE)

  * add document information structures as runtime variables (e.g. file.name
    file.mod, template.name, system.time, etc)

Improvements
------------
  * Context constructor should be more intelligent about the PLUGIN_BASE 
    which might have multiple values.

  * Loading of plugins should be more intelligent, setting a local @INC 
    to the PLUGINS_BASE and let Perl find the file.

  * Template/Context redirect() should be able to handle a file name
    and open output for it

  * Change default ERROR handler to be undef (errors retrieved via 
    error()) and have uncaught exceptions call $context->error().

  * Add AUTOLOAD to Template.pm to delegate to Context

  * 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 ]; sort(things) %%
    Notionally, we might be able to add a 'members' operator as a postfix:
      %% things = [ b c a ]; sort(things.*) %%
    The same approach could be used for hashes:
      %% users = { tom => 99, dick => 100, harry => 101 };
         FOREACH name = users.keys 
         FOREACH name = users.values  # or users.* as above
    This needs addressing.

  * 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 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.

  * The parser grammar can be simplified a lot.  I think that the
    re-write between 0.17 and 0.18 was a Good Thing but pitched the
    intermediate code too low down at the opcode level.  It needs to
    be lifted up a little to encompass broader concepts such as
    generic parameter lists rather than opcode sequences.  This will
    hopefully make the programmatical interface less complex, the
    internal code cleaner, the language more flexible and the grammar
    simpler and smaller.  What's more, I think it will run a little 
    faster, too.  Benchmark results between 0.17 and 0.18 suggest that
    there was a little slowdown in going to lower level opcodes for 
    the gain of greater flexibility.  I think it can be re-factored 
    slightly to give a Win-Win.

Other plugins, modules, scripts
-------------------------------
  * tpage - add options, etc, or implement ttree
    also need to handle STDIN since we took it out of file opening code

  * finish Apache::Template

  * extend 'format' to perform date formatting?

  * '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' %]

Documentation
-------------
  * 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.  
    [% FOREACH user = [ foo bar baz ]( order = 'sorted', action = coderef ) %]

  * automatic import of ident-less FOREACH loops that return hashes is not
    documented

  * write more detailed description on extending the template toolkit.

Tests
-----
  * test tokeniser
  * test parser, including line number reporting on errors


