[Templates-announce] (Fwd) CPAN Upload: A/AB/ABW/Template-Toolkit-2.01.tar.gz

[Andy Wardley]

--
--PART-BOUNDARY=.11010330152319.ZM19807.bandanna
Content-Type: text/plain; charset=us-ascii

Wait for it..... wait for it.... HERE IT IS!

  The uploaded file

      Template-Toolkit-2.01.tar.gz

  has entered CPAN as

    file: $CPAN/authors/id/A/AB/ABW/Template-Toolkit-2.01.tar.gz
    size: 589429 bytes
     md5: f9fb969f3c987080e66cbbd57677b7bc

The long awaited version 2.01 of the Template Toolkit is, or will
shortly be available from CPAN.  You can also fetch it from:

    http://www.template-toolkit.org/

This is the biggest, baddest and phattest version yet.  The overstuffed
section of the Changes file follows.

Apologies for the ongoing delays in getting this one of the door and
thank you for you patience (that excludes you, Piers :-).  Reworking
the documentation set was a mammoth effort but hopefully it has been
worth it - the docs are now distributed in both POD format and as HTML
templates which you can process into your own fancy styles.  You can
browse the documentation online at the web site.  There's a whole bunch
of goodies in the form of template libraries, examples, new features,
and lots of bugs fixed.

Big thanks to all the people who have contributed patches to this
release (that includes you, Piers, so you're forgiven :-).  Hopefully
it will be worth the wait.

Enjoy
A


#------------------------------------------------------------------------
# Version 2.01 - 30th March 2001
#------------------------------------------------------------------------

* Added the various template libraries in the 'templates' directory.
  The 'html' library implements some generally useful HTML elements.
  The 'pod/html' libraray contains some templates for converting POD to
  HTML, used in building the TT2 HTML documentation, for example.  The
  'ps' library contains templates defining a few useful marks and other
  procedures for generating PostScript pages.  The 'splash' directory
  contains templates for the "Splash!" library which implements a
  widget set for building stylish HTML user interfaces.

* Added a host of example pages in the 'examples' directory which
  demonstrate use of the above libraries.

* Added an 'images' directory to contain the small images used to build
  up the Splash! interface components.

* Added the 'docs' directory containing templates and library elements
  for building the TT2 documentation as HTML pages.

* Updated Makefile.PL to now offer to install optional libraries,
  images, build HTML docs, examples, etc.  Adds 'tt2_install',
  'tt2_html_docs' and 'tt2_examples' as Makefile targets if requested.
  These then get run as part of "make install".

* Totally re-organised the documentation, splitting the long user manual
  into separate Template::Manual::* pages, adding the Template::FAQ,
  Template::Internals, and various other changes.  All POD and HTML
  documentation is built from the same sources in the form of another
  set of templates, POD files, XML files, scripts, etc., distributed
  separately as the 'docsrc' bundle, and available from the web site.
  The POD documentation now gets glued onto the end of the .pm
  modules and only creates separate .pod files for those manual pages
  that don't have equivalent modules (e.g. Template::FAQ, etc.)
  NOTE: this might mean that existing .pod files from earlier versions
  of TT might mask documentation in newer .pm files...

* Added the Template::View module, the VIEW directive and the View
  plugin which can be used collectively to create dynamic views.  This
  is a very powerful tool which fulfills a number of requirements and
  makes possible a number of things that have previously been messy,
  difficult or not possible.  Views are primarily collections of
  templates.  You can define BLOCKs within a view and they remain
  local to it, but can be called from outside the view.  This is still
  very experimental.  Things are likely to change.  See
  Template::Views for (incomplete) documentation and take a look at
  t/view.t for examples.

    [% VIEW fancy_html
	    prefix = 'splash/'		# template prefix/suffix
	    suffix = '.tt2'
	    bgcol  = '#ffffff'		# and any other variables you
	    style  = 'Fancy HTML'       # care to define as view metadata,
	    items  = [ foo, bar.baz ]	# including complex data and
	    foo    = bar ? baz : x.y.z  # expressions
    %]

	[% BLOCK header %]		# define "private" view blocks
	   Title: [% title %]
	[% END %]

    [% END %]				# end of VIEW definition

    [% v = fancy_html %]		# view is a regular object ref, re-
    [% mycode(v) %]			# assign it, pass it around, etc.

    [% v.title %]			# access view metadata

    [% v.header(title = 'Foo!') %]	# view "methods" process blocks or
    [% v.footer %]			# templates with prefix/suffix added
					# => [% INCLUDE splash/footer.tt2 %]

* Added the facility to specify multiple templates within a PROCESS,
  INCLUDE, INSERT or WRAPPER directive.  For all but WRAPPER, the
  templates are processed in the order specified.

    [% PROCESS config + header + menu %]
    [% INCLUDE section/break + html/titlebar
         title='A New Section'
    %]
    [% WRAPPER edge + box + titlebar %]
       ...
    [% END %]

  Multiple WRAPPER templates get processed in reverse order to create
  the correct nesting effect.  In the example above, the enclosed block
  is processed and passed to 'titlebar' which wraps it and passes the
  output to 'header' which wraps it and passes the output to 'box', which
  wraps it and passes the output to 'edge' which wraps it and returns the
  output.  Thus the specification order is outermost to innermost, but
  they are actually processed from the inside out.

* Templates specified to INCLUDE, PROCESS, WRAPPER and INSERT can now
  be given a prefix (delimited by ':', as in "file:blahblah.txt" or
  "http://www.tt2.org/index.html", for example) which maps them to a
  particular template provider or providers.  A PREFIX_MAP
  configuration option can be specified as a hash array mapping prefix
  names to a reference to a list of providers.  For convenience, you
  can also specify the argument as a string of integers, delimited by
  any non-numerical sequence, to indicate indices into the LOAD_TEMPLATES
  provider list.  e.g.

    my $template = Template->new({
	LOAD_TEMPLATES => [ $foo, $bar, $baz, $wiz ],
	PREFIX_MAP => {
	    src => '0, 2',	# $foo and $baz
	    lib => '1, 2',	# $bar and $baz
	    all => '0, 1, 2',	# $foo, $bar and $baz
	}
    });

  Thus [% INCLUDE src:hello.tt2 %] indicates the 'hello.tt2' template
  to be provided by $foo or $baz, [% INCLUDE lib:hello.tt2 %] is mapped
  to $bar and $baz, [% INCLUDE all:hello.tt2 %] can be provided by
  $foo, $bar or $baz, and the default [% INCLUDE hello.tt2 %] is
  mapped to the entire LOAD_TEMPLATES list: $foo, $bar, $baz and $wiz.
  This is initially useful for things like ttree which would like a way
  to differentiate between templates in one place and templates in
  another.  It can also be used, of course, to provider special providers
  for certain file type, as in http://fetch.some.file.com/blah/blah/...

* Fixed the parser to accept expressions on the right hand side of
  parameter definitions for INCLUDE, etc.  e.g.

    [% INCLUDE header
         title = my_title or your_title or default_title
         bgcol = (style == 'dark' ? '#000000' : '#ffffff')
    %]

* Added the PLUGIN_FACTORY configuration option to Template::Plugins
  to allow class names or object prototypes to be specified for plugins.
  No module loading is attempted, unlike the existing PLUGINS which
  assumes entries are module names which it tries to load.  This may
  change in a future release (ideally by integration with PLUGINS) so
  it remains undocumented for now.

    package My::Plugin;
    ...

    package main;

    my $tt = Template->new({
	PLUGIN_FACTORY => {
	    plugin1 => 'My::Plugin',         # class name
	    plugin2 =>  My::Plugin->new(),   # prototype obj
	},
    });

* Added the File and Directory plugins which blossomed from the
  Directory plugin written by Michael Stevens and posted to the
  mailing list.  These give you access to files and directories on
  your filesystem and also allow you to create representations of
  abstract files/dirs.

  WARNING: recognise that this gives the author of any templates you
  run access to information about your filesystem.  We assume that the
  author of your templates is you or someone you trust to have access
  to that kind of information.  If you're running "untrusted"
  templates (we assume you know what you're doing) then you'll very
  probably want to disable these plugins.  Alas there is no easy way
  to disable plugins at the moment other than deleting them or writing
  null or error throwing plugins to mask them.  Making this easier is
  a TODO.

* Added the Pod plugin which uses the Pod::POM module to parse a Pod
  file or text string and build an object model.  You can then walk
  it and present it in different ways using templates.  Great for
  building HTML documentation from Pod and unsurprisingly used to
  build the new TT2 docs.

* Applied a patch from Chris Nandor to add a new feature to the
  PRE_CHOMP and POST_CHOMP options.  When set to 1, they continue to
  act as before.  When set to 2, all whitespace is collapsed into a
  single space.  CHOMP_NONE, CHOMP_ALL and CHOMP_COLLAPSE are
  defined in Template::Constants and can be imported as the :chomp
  tagset, for those who want them.

* Applied a patch from Doug Steinwand to fix a problem in
  Template::Provider which would server stale templates if the
  modification time of the files went backwards.  In addition, it now
  uses the $Template::Provider::STAT_TTL (time to live) variable
  (default: 1) to determine how often to stat the files to check for
  changes.  TT2 now supports time running backwards!  :-)

* Applied a patch from Vivek Khera which fixes a memory leak in the
  MACRO directive, prevalent when using TT under mod_perl.  Also added
  t/leak.t to test that memory is properly freed and circular references
  broken by the delocalisation of the stash.  All seems to work as expected
  including plugins that contain context references, MACRO definitions,
  and so on (but note that this is the test suite run from the command
  line, and doesn't explicitly test under mod_perl...)

* Applied a patch from Axel Gerstmair to fix a bug in PERL blocks
  and filters which caused references to the context and stash to be
  kept in global package variables.  This meant they stayed alive for
  far too long.  Added a couple of tests to t/leak.t to check this now
  works OK.

* Fixed a bug in the parser triggered by [% CATCH DEFAULT %].  Thanks
  to Vivek Khera for reporting the problem.  This also fixes a problem
  reported by Thierry-Michel Barral which was causing bare 'CATCH'
  blocks to not catch errors and instead pollute STDERR.

* Fixed another bug in the parser preventing double quoted META attributes
  from containing single quotes, e.g. [% META title="C'est un test" %].
  Thanks to Philippe Bruhat for reporting the problem.

* Added the 'indent' filter to indent a block by prefixing each line with
  a specified string, or a number of spaces when the argument is numerical.

* Added the 'trim' filter to remove leading/trailing whitespace and
  'collapse' filter to additionally collapse multiple whitespace characters
  to a single space.

* Added escapes for ' (') and " (") to the html filter, thanks
  to Lyle Brooks and Vivek Khera.  Then, having done that, I removed
  the ' escape because my browser didn't recognise ' as a
  valid entity.  What's going on here?  Need to check the HTML spec...

* Added tag style 'star' of the form [* ... *]

* Changed the Template::Stash get() and set() methods to accept a
  compound variables as a single parameter and automatically convert
  it to an array.  Note that it doesn't correctly handle arguments
  to dotted elements (e.g. foo(10).bar(20), but does mean that you can
  now write $stash->get('foo.bar.baz') instead of the more laborious
  $stash->get(['foo', 0, 'bar', 0, 'baz', 0]).

* Fixed a bug in Template::Stash which was raising an error when an
  element on the left hand side of a '.' evaluated to a defined, but
  empty value.

* Fixed an obscure bug in Template::Stash which occurred when calling
  a scalar method on a value which contained a valid and visible object
  package name.  e.g. [% name = 'Foo::Bar'; name.baz() %] called
  Foo::Bar->baz().

* Fixed a bug in the Template::Stash 'replace' virtual method which
  returned the original string when the replace string was specified
  empty.   [% var = 'foo99'; var.replace('foo', '') %] now correctly
  returns '99' instead of the original string 'foo99'.  Thanks to
  Tryggve Johannesson and Jeremy Wadsack for reporting the problem.

* Added magical handling of the 'import' variable to stash clone() and
  update methods.  This implements the V1 functionality whereby you can
  write [% INCLUDE foo import=myhash %].  Note that 'import' is lower case,
  (V1 was upper case IMPORT) as in V2 it is in keeping with the virtual
  hash method (e.g. same as myhash.import(another.hash)).  Thanks to
  Brian Cooper for raising the issue.

* Yet another change to Template::Stash.  Objects which are blessed
  arrays will now honour virtual array methods if the object doesn't
  otherwise implement a particular method.  For example, you can now
  write [% USE Datafile(...) %] and then [% Datafile.size %].  The
  '.size' now works as virtual method on the blessed ARRAY which
  consitutes the Datafile object.  Thanks to Keith Murphy for
  identifying the problem.

* Fixed another obscure bug, this time in Template::Parser which wasn't
  chomping the final newline in the input string.  Thanks to Paul
  Makepeace for reporting the problem.

* Finally identified the cause of an error occasionally being reported
  by Template::Service when is thrown a non-reference exception.  It
  appears to be a problem interacting with CGI::Carp.  For now, it's
  fixed and tolerated in Template::Service (but could possibly do with
  a better long term solution?).  Thanks to Jo Walsh, Trond Michelson,
  and I'm sure several others who reported this and helped to track
  the problem down (and also fixing the confess() bug I introduced
  when I added the tracer code.  D'Oh!)

* Removed some old "delegate-to-another-object" code from Template::Plugin,
  including a nasty AUTOLOAD method which prevented derived objects from
  acting as transparent hashes.  If delegative functionality is required
  then it should be implemented as Template::Plugin::Delegate (and may
  well be in the fullness of time).

* Fixed a whole bunch of typos and spellos thanks to patches from Leon,
  Paul Sharpe and Robert McArthur.




-- 
Andy Wardley <abw@kfs.org>   Signature regenerating.  Please remain seated.
     <abw@cre.canon.co.uk>   For a good time: http://www.kfs.org/~abw/

--PART-BOUNDARY=.11010330152319.ZM19807.bandanna
Content-Description: Transferred from mail from cpan-testers@perl.org: plain text
Content-Type: text/plain ; charset=UTF-8
Content-Disposition: attachment

The uploaded file

    Template-Toolkit-2.01.tar.gz

has entered CPAN as

  file: $CPAN/authors/id/A/AB/ABW/Template-Toolkit-2.01.tar.gz
  size: 589429 bytes
   md5: f9fb969f3c987080e66cbbd57677b7bc

No action is required on your part
Request entered by: ABW (Andy Wardley)
Request entered on: Fri, 30 Mar 2001 14:09:44 GMT
Request completed:  Fri, 30 Mar 2001 14:10:35 GMT

	Virtually Yours,
	Id: paused,v 1.72 2000/12/26 15:12:53 k Exp k 


--PART-BOUNDARY=.11010330152319.ZM19807.bandanna--