[Templates] Known bugs / current fixes

[Andy Wardley]

I'm planning to release another beta version early next week.  Here's 
the current list of things that have been changed since beta 2, and
outstanding bugs that I know about.

If there's anything that isn't on this list, then let me know.  
Documentation is still uncertified (i.e. I make no claims that
it's correct or complete at this point) but any problems should
be raised as bugs/feature requests/etc.


A


#------------------------------------------------------------------------
# Known bugs / planned fixes
#------------------------------------------------------------------------

* Change docs to note that 'e' is no longer an alias for 'error', or 
  ensure 'e' is set.

* Apply patch from Perrin to fix Template::Provider bug which doesn't 
  report errors when reloading persistant templates.

* Change handling of EVAL_PERL option to throw out all PERL/RAWPERL
  blocks, rather than try to ignore them at runtime.  As Randal pointed
  out, a rogue BEGIN { } block can do a lot of damage.

* Apply fix from Chris Dean for single item array sorting bug.

* Support 'next' in loops, as suggested by Jo Ellen Wisnosky 

* Check exception names.  Note that we cannot catch 'perl' exceptions 
  because PERL is a reserved word.  Arse!  THROW and CATCH should accept
  quoted strings, or jiggle around with e types to make things work
  "better".


#------------------------------------------------------------------------
# current changes from beta 2 (as of 11.00 am 3rd Aug 2000)
#------------------------------------------------------------------------

* Reorganised the Template::Filters modules and changed the calling 
  convention for requesting filters via the fetch() method.  This now
  expects a reference to the calling Template::Context object as the
  third parameter (after filter name and reference to a list of arguments).
  Static filter sub-routines are returned as before and the context has
  no effect.  Dynamic filter factories (denoted by a $is_dynamic flag
  in the FILTER_FACTORY table) are called to create a filter sub-routine
  (closure) for each request.  The context is now passed as the first
  parameter, followed by the expansion of any arguments.  Filter 
  factories should return a sub-routine or (undef, $error) on error.

* Added several new filters:
  - 'stderr' prints the output to STDERR (i.e. for generating output 
    in the Apache logfile, for example).  e.g. [% message | stderr %]

  - 'file' is the equivalent of the version 1 redirect() filter which 
    writes the output to a new file, relative to OUTPUT_PATH.  Throws
    a 'file' exception if OUTPUT_PATH is not set.  There should perhaps 
    be some other way to disable this without relying on OUTPUT_PATH.

  - 'eval' evaluates the input as a template and processes it.  Proposed
    by Simon Matthews for times when you might be returning templates 
    fragments from a database, for example.  e.g. [% dirtext | eval %]

  - 'evalperl' evaluate the input as Perl code, as suggested by Jonas
    Liligren. Requires the EVAL_PERL option to be set and will throw a 
    'perl' error if not (see next item).  e.g. [% perlcode | evalperl %]

* Fixed a bug in Template::Provider which was mangling the metadata items
  for the template name and modification time.  The [% template.name %] 
  and [% template.modtime %] variables now work as expected.

* Fixed the Template::Context to recognise the RECURSION option once more,
  thanks to a patch from Rafael Kitover.  Added some tests to t/include.t

* Overloaded "" stringification of Template::Exception to call as_string(),
  again thanks to Rafael.

* Fixed a bug preventing literal newlines from being used in strings.
  Thanks to Simon Matthews for bringing it to my attention by calling 
  my hotel room at the Perl Conference and saying "Hello?  Is that the 
  Template Toolkit Helpdesk?  I have a bug to report..."  :-) 
  (I fixed it on his laptop a few minutes later - good service, eh?)

* Changed PERL blocks to throw a 'perl' error if EVAL_PERL is not set.
  Any other errors thrown in a Perl blocks are left intact.  Previously,
  these were converted to 'perl' exceptions which prevented exceptions 
  of other kinds being throw from within Perl code.

* Changed Template::Stash set() method to append the assigned value to
  the end of any arguments specified, rather than prepending it to the 
  front.  e.g. The foo() method called by [% myobj.foo(x, y) = z %] now
  received arguments as (x, y, z) instead of (z, x, y).

* Changed Template::Base::error() to accept a reference (e.g. exception)
  as the first parameter.  In this case, no attempt is made to 
  concatenate (and thereby stringify) the arguments.

* Added a direct stash() accessor method to Template::Context rather 
  than relying on the slower AUTOLOAD method.

* Added an iterator() method to Template::Config to require 
  Template::Iterator and instantiate an iterator, and changed 
  generated code for FOREACH to call this factory method.  This 
  fixes a bug with persistant templates which were failing if
  Template::Iterator wasn't already loaded.  Thanks to Doug Steinwand,
  Rafael Kitover and Jonas Lilegren who all identified the problem 
  and hounded me until I fixed it.  :-)
 
* Fixed a problem with persistant templates not being reloaded due to 
  the %INC hash.  This caused 1 to be returned from require() instead 
  of the compiled template.

* Applied various documentation and test patches from Leon Brocard.
  Fixed docs to quote dotted exception types to prevent string 
  concatenation, as noted by Randal Schwartz.