#============================================================================
#
# Template Toolkit TODO
#
# DESCRIPTION
#   Outstanding bugs, planned features, improvements, ideas, etc.
#
# AUTHOR
#   Andy Wardley   <abw@cre.canon.co.uk>
#
#----------------------------------------------------------------------------
#
# $Id: TODO,v 1.26 1999/08/10 11:08:56 abw Exp $
#
#============================================================================

Pending
-------
  * cvs add MANIFEST.SKIP
  * cvs add t/filter.t
  * cvs add t/break.t
  * cvs add lib/Template/Plugin/Filter.pm  
  * cvs add t/process.t
  * cvs add t/while.t
  * cvs add t/import.t
  * cvs add t/literal.t 
  * cvs add t/os.t
  * cvs remove t/export.t

  * Document WHILE
  * Document PROCESS
  * Document BREAK
  * Document OS option and change PATH_SEP/DIR_SEP 
  * Document FILTER

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
----------------
  * TRY to scope CATCH?

  * PERL directive to encapsulate Perl code.  Stash variables could be 
    made available.

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

  * general purpose methods (e.g. 'size' on a list, 'keys' on a hash)

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

Improvements
------------
  * user-defined filters can be provided in the FILTERS hash, but there
    is no way to dynamically load filters from the template unless they
    are "standard library" filters, defined in Template::Plugin::Filter.

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

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

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

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

  * IMPORT documentation is wrong - you can't import to another package.
    Aloso need to document for IMPORT directive.

  * WHILE is not documented

  * PROCESS is not documented

  * FILTER is not documented

  * TAGS directive is not documented

  * OS, PATH_SEP and PATH_SPLIT options are not documented.

  * write more detailed description on extending the template toolkit.

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


