[Templates-cvs] cvs commit: Template2/docs/src/Release Changes.html HACKING.html INSTALL.html README.html TODO.html
cvs@template-toolkit.org
cvs@template-toolkit.org
cvs 06/05/26 13:44:58
Modified: docs/src/Release Changes.html HACKING.html INSTALL.html
README.html TODO.html
Log:
Version 2.15
Revision Changes Path
1.64 +130 -42 Template2/docs/src/Release/Changes.html
Index: Changes.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Release/Changes.html,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -r1.63 -r1.64
--- Changes.html 2006/01/30 20:03:54 1.63
+++ Changes.html 2006/05/26 13:44:57 1.64
@@ -23,20 +23,77 @@
# Any changes you make here may be lost!
#
#------------------------------------------------------------------------
-# $Id: Changes.html,v 1.63 2006/01/30 20:03:54 abw Exp $
+# $Id: Changes.html,v 1.64 2006/05/26 13:44:57 abw Exp $
#========================================================================
#------------------------------------------------------------------------
-# Version 2.15
+# Version 2.15 - 26th May 2006
#------------------------------------------------------------------------
+Chomping Options
+----------------
+
+* Added the CHOMP_GREEDY option and '~' chomping flag. Changed
+ CHOMP_COLLAPSE to greedily chomp all whitespace (including multiple
+ newlines) and replace it with a single space. Previously it only
+ chomped one line. Renamed the CHOMP_ALL option to CHOMP_ONE which
+ makes more sense. CHOMP_ALL is still provided as an alias for
+ CHOMP_ONE for backwards compatibility. Thanks to Paul Seamons for
+ doing all the hard work on this.
+
+ http://tt2.org/pipermail/templates/2006-February/thread.html#8354
+
+* Added code to the replace text virtual method to use a faster and
+ simpler implementation if the replacement text doesn't contain any
+ back references. Thanks to Josh Rosenbaum for all his efforts on
+ this.
+
+ http://tt2.org/pipermail/templates/2006-February/008344.html
+
Stash
-----
+* Changed various tests for private/hidden variables (starting '_'
+ or '.') to use a regex defined in the $PRIVATE package variable in
+ Template::Stash. This can be redefined or undefined. Note that
+ the XS Stash only looks to see if $PRIVATE is defined or not, and
+ currently hard-codes the regex.
+
+Plugins
+-------
+
+* Changed the Image plugin tag() method to call the name() method
+ instead of accessing the name directly, making it easier for
+ subclasses to provide an alternate name. Thanks to Cees Hek for
+ his patch.
+
+ http://tt2.org/pipermail/templates/2006-February/008423.html
+
+* Change the AUTOLOAD regex in the Table plugin to be more robust.
+
+ http://tt2.org/pipermail/templates/2006-May/008602.html
+
+Documentation
+-------------
+
+* Added the Template::Toolkit documentation pointing people to
+ the right place.
+
+* Updated the Template::Stash::XS documentation to remove the
+ "experimental" description and tidy things up a bit.
+
+
+#------------------------------------------------------------------------
+# Version 2.14a - 2nd February 2006 ## DEVELOPER RELEASE ##
+#------------------------------------------------------------------------
+
+Stash
+-----
+
* Activated a patch in Template::Stash from Stephen Howard which adds
- code for the full set of fallbacks for dot ops called against objects
- which don't implement the specific method. For example
- [% tt_start_tag %] hashobj.vmethod [% tt_end_tag %] [% tt_start_tag %] listobj.2 [% tt_end_tag %] and [% tt_start_tag %] listobj.vmethod [% tt_end_tag %] now
+ code for the full set of fallbacks for dot ops called against
+ objects which don't implement the specific method. For example
+ [% tt_start_tag %] hashobj.vmethod [% tt_end_tag %] [% tt_start_tag %] listobj.2 [% tt_end_tag %] and [% tt_start_tag %] listobj.vmethod [% tt_end_tag %] now
all work with the Perl Template::Stash. Added code to the XS Stash
to do the same and updated tests.
@@ -47,76 +104,91 @@
http://tt2.org/pipermail/templates/2006-January/008266.html
-* Applied path from Slaven Rezic to Template::Stash::XS to check return
- code in tt_fetch_item() in a way which plays nicely with tied hashes.
+* Applied path from Slaven Rezic to Template::Stash::XS to check
+ return code in tt_fetch_item() in a way which plays nicely with tied
+ hashes.
http://rt.cpan.org/Ticket/Display.html?id=7830
-* Changed Template::Stash and Template::Stash::XS to evaluate list
+* Changed Template::Stash and Template::Stash::XS to evaluate list
vmethods in lvalues.
http://tt2.org/pipermail/templates/2006-January/008198.html
* Changed Template::Stash to be a little more strict about what it
- considers a failed method call. This allows exception thrown
- within called methods to be propagated correctly rather than
- being ignored as undefined method. Thanks to Dave Howorth for
- reporting the problem and providing a fix. Also ported to the
- Template::Stash::XS module.
+ considers a failed method call. This allows exception thrown within
+ called methods to be propagated correctly rather than being ignored
+ as undefined method. Thanks to Dave Howorth, Tom Insam and Stig
+ Brautaset for reporting the problem and providing fixes.
http://tt2.org/pipermail/templates/2005-April/007375.html
+ http://tt2.org/pipermail/templates/2006-February/008367.html
+
+* Removed redundant performance profiling code from
+ Template::Stash::XS. Must check with Doug that this is OK and he's
+ not still using it...
-* Removed redundant performance profiling code from Template::Stash::XS.
- Must check with Doug that this is OK and he's not still using it...
Virtual Methods
---------------
+
+* Added the scalar.remove, scalar.substr, hash.delete, hash.items,
+ hash.pairs, list.import and list.hash virtual methods.
+
+* Changed the scalar.replace method to work properly with back
+ references ($1, $2, etc) by incorporating ideas, code and tests from
+ Nik Clayton, Paul Seamon, Sergey Martynoff, Josh Rosenbaum and
+ others.
+
+ http://tt2.org/pipermail/templates/2006-February/008306.html
+ http://tt2.org/pipermail/templates/2006-February/008326.html
-* Changed list.hash and hash.list vmethods to Do The Right Thing instead
- of some crack fuelled nonsense. hash.list now returns [ %$hash ]
- and list.hash now returns [ @$list ]
-
- http://template-toolkit.org/pipermail/templates/2006-January/008256.html
-
-* Fixed the split scalar virtual method which wasn't accepting the second
- argument (limit) correctly. Thanks to Josh Rosenbaum for pointing
- out the problem, although the solution turned out to be a little more
- complicated.
+* Changed list.push and list.unshift to accept multiple arguments,
+ thanks to Bill Moseley.
+ http://tt2.org/pipermail/templates/2006-January/008294.html
+
+* Fixed the split scalar virtual method which wasn't accepting the
+ second argument (limit) correctly. Thanks to Josh Rosenbaum for
+ pointing out the problem.
+
http://tt2.org/pipermail/templates/2005-October/007982.html
-* Added the 'delete' hash virtual method and the 'remove' scalar virtual
- method.
+* Documented the fact that hash.list is going to change in the future,
+ recommending people switch to hash.pairs.
-* Changed $element to $component in Template::Context to fix callers bug,
- thanks to Andy Maas who identified the problem and found the solution:
+ http://tt2.org/pipermail/templates/2006-January/008256.html
+ http://tt2.org/pipermail/templates/2006-February/008312.html
- http://tt2.org/pipermail/templates/2004-December/007020.html
+* Added the global option to the 'match' scalar virtual method.
-* Fixed the regex matching relative paths in Template::Provider, thanks
- to Josh Rosenbaum
+* Changed $element to $component in Template::Context to fix callers
+ bug, thanks to Andy Maas who identified the problem and found the
+ solution:
- http://tt2.org/pipermail/templates/2005-January/007141.html
+ http://tt2.org/pipermail/templates/2004-December/007020.html
-* Changed the sort and nsort list virtual methods to always return
+* Changed the sort and nsort list virtual methods to always return
references to lists, avoiding any ambiguity in return results.
-* Changed the hash.defined method to do the same thing as scalar.defined
- when called without arguments. Added list.defined to do the same thing
- as hash.defined.
+* Changed the hash.defined method to do the same thing as
+ scalar.defined when called without arguments. Added list.defined to
+ do the same thing as hash.defined.
http://rt.cpan.org/Ticket/Display.html?id=9094
+* Moved all the tests into t/vmethods/*
+
Plugins
-------
* Added the $Template::Plugins::PLUGIN_BASE package variable to define
- the default 'Template::Plugin' value for the PLUGIN_BASE option.
- By clearing this value before calling the Template new() constructor,
- you can avoid having Template::Plugin added to the PLUGIN_BASE by
+ the default 'Template::Plugin' value for the PLUGIN_BASE option. By
+ clearing this value before calling the Template new() constructor,
+ you can avoid having Template::Plugin added to the PLUGIN_BASE by
default. Also changed PLUGINS search to look for lower case plugin
- name as well as case-specific name. Thanks yet again Josh for
+ name as well as case-specific name. Thanks yet again Josh for
addressing this issue.
http://tt2.org/pipermail/templates/2006-January/008225.html
@@ -176,7 +248,7 @@
http://rt.cpan.org/Ticket/Display.html?id=5695
* Updated documentation to reflect the fact that the html filter also
- escapes " as " Thanks to Geoff Richards for reporting it.
+ escapes " as " Thanks to Geoff Richards for reporting it.
* Moved Latex filters into Template-Latex distribution.
@@ -205,6 +277,11 @@
http://rt.cpan.org/Ticket/Display.html?id=4180
+* added AppConfig EXPAND => EXPAND_ALL option to perl5lib,
+ template_plugin_base, template_compile_dir and depend_file
+ configuration options to allow them to contain ~ to indicate
+ the user's home directory, or $WHATEVER for environment variables,
+ as per the other path-specific options like src, lib, etc.
Miscellaneous
-------------
@@ -223,6 +300,17 @@
Template::Parser line counting when using chomp flags.
http://tt2.org/pipermail/templates/2005-December/008157.html
+
+* Applied a patch from Jess Robinson to move the Template::Provider
+ check for file freshness into a separate method, in order to
+ play nicely with his Template::Provider::DBI module.
+
+ http://tt2.org/pipermail/templates/2005-December/008143.html
+
+* Fixed the regex matching relative paths in Template::Provider, thanks
+ to Josh Rosenbaum
+
+ http://tt2.org/pipermail/templates/2005-January/007141.html
* Applied a patch to Template::Provider to prevent a misleading error
message, thanks to Slaven Rezic.
1.34 +3 -3 Template2/docs/src/Release/HACKING.html
Index: HACKING.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Release/HACKING.html,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- HACKING.html 2006/01/30 20:03:55 1.33
+++ HACKING.html 2006/05/26 13:44:58 1.34
@@ -7,9 +7,9 @@
Version 2.15
- 30 January 2006
+ 26 May 2006
- Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved
+ Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This is free software; you can redistribute it and/or
@@ -64,7 +64,7 @@
COPYRIGHT
---------
-Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This is free software; you can redistribute it and/or modify it under
1.35 +6 -14 Template2/docs/src/Release/INSTALL.html
Index: INSTALL.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Release/INSTALL.html,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -r1.34 -r1.35
--- INSTALL.html 2006/01/30 20:03:55 1.34
+++ INSTALL.html 2006/05/26 13:44:58 1.35
@@ -7,9 +7,9 @@
Version 2.15
- 30 January 2006
+ 26 May 2006
- Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved
+ Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This is free software; you can redistribute it and/or
@@ -57,9 +57,9 @@
-------------
The Template Toolkit is written entirely in Perl and should run on any
-platform on which Perl is available. It requires Perl 5.005 or later.
+platform on which Perl is available. It requires Perl 5.006 or later.
-The 'ttree' utility uses the AppConfig module (version 1.55 or above)
+The 'ttree' utility uses the AppConfig module (version 1.56 or above)
for parsing command line options and configuration files. It is
available from CPAN:
@@ -117,11 +117,6 @@
number of configuration items. The following CONFIGURATION section
covers this in greater detail.
-There are known to be a few minor issues with the test suite, with
-some tests failing in certain conditions. None of these are thought
-to be serious problems. The BUILDING AND TESTING section provides
-more detail on this.
-
If you choose to install the optional components then you may need to
perform some post-installation steps to ensure that the template
libraries, HTML documentation and examples can be correctly viewed via
@@ -330,11 +325,8 @@
make
The 'make test' command runs the test scripts in the 't' subdirectory.
-There is known to be at least one failures under certain conditions:
- * The Text::Autoformat plugin may fail on tests 23 and 25 with
- versions of Perl prior to 5.6.0 when using a locale which has a
- decimal separator other than '.'.
+ make test
You can set the TEST_VERBOSE flag when running 'make test' to see the
results of the individual tests:
@@ -490,7 +482,7 @@
COPYRIGHT
---------
-Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This is free software; you can redistribute it and/or modify it under
1.55 +23 -6 Template2/docs/src/Release/README.html
Index: README.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Release/README.html,v
retrieving revision 1.54
retrieving revision 1.55
diff -u -r1.54 -r1.55
--- README.html 2006/01/30 20:03:55 1.54
+++ README.html 2006/05/26 13:44:58 1.55
@@ -7,9 +7,9 @@
Version 2.15
- 30 January 2006
+ 26 May 2006
- Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved
+ Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This is free software; you can redistribute it and/or
@@ -73,10 +73,27 @@
WHAT'S NEW?
-----------
-Version 2.15 features a number of enhancements to the XS Stash that
-includes support for tied hashes and arrays. There are numerous other
-bug fixes and enhancements, described in detail in the Changes file.
+Version 2.15 is a major maintenance release. It applies all outstanding
+patches and closes all open bugs listed on http://rt.cpan.org/ It
+includes:
+
+ * XS Stash: enhancements include support for tied hashes/arrays
+ and "fallback" methods on objects (e.g. accessing hash and
+ list items and calling virtual methods)
+
+ * Virtual Methods: added the scalar.remove, scalar.substr,
+ hash.delete, hash.items, hash.pairs, list.import and list.hash
+ virtual methods. Added support for backreferences to
+ scalar.replace and other improvements to list.push, list.unshift,
+ list.hash, hash.list
+
+ * Plugins: Added Math plugin, Bug fixes and enhancements to File,
+ Image, URL and String plugins. Moved DBI, XML and GD plugins
+ into separate distributions.
+ * Numerous other bug fixes, enhancements, documentation updates, all
+ described in detail in the Changes file.
+
More significant is what's not in version 2.15. The DBI plugin has
been moved into a separate Template-DBI distribution, the GD plugins
into Template-GD, the XML plugins into Template-XML, and the Latex
@@ -295,7 +312,7 @@
COPYRIGHT
---------
-Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
This is free software; you can redistribute it and/or modify it under
1.64 +13 -381 Template2/docs/src/Release/TODO.html
Index: TODO.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Release/TODO.html,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -r1.63 -r1.64
--- TODO.html 2006/01/30 20:03:55 1.63
+++ TODO.html 2006/05/26 13:44:58 1.64
@@ -12,16 +12,19 @@
# and a few whacky ideas.
#
# AUTHOR
-# Andy Wardley <abw@wardley.org>
+# Andy Wardley <abw@cpan.org>
#
#------------------------------------------------------------------------
-# $Id: TODO.html,v 1.63 2006/01/30 20:03:55 abw Exp $
+# $Id: TODO.html,v 1.64 2006/05/26 13:44:58 abw Exp $
#========================================================================
#------------------------------------------------------------------------
# Miscellaneous
#------------------------------------------------------------------------
+* The ENCODING options needs testing and documenting. Bill Moseley said
+ he may be able to do this.
+
* The 'eval' filter leaks memory, as reported by Colin Johnson. The
filter subroutine created contains a reference to the context and then
gets cached in the FILTER_CACHE item of the context. Hey presto -
@@ -55,34 +58,8 @@
between sessions and the same files in different INCLUDE_PATH dirs
maps to the samed compiled version) but is convenient for those times
when you know that's not going to be a problem.
-
-* Richard Tietjen's patch for stash replace. Allows back references
- (e.g. $1) but it would be nice to find a rock-solid way to implement
- it without relying on unusual ^A delimiter character.
-
-* Further to the above, Craig Barratt has this solution which will be
- going into the next verion (2.05b) unless anyone has any further
- suggestions to make before then.
-
- It would be great if replace handled backreferences. I don't like
- the ^A solution since the string could contain ^A, plus it is a
- security hole. The attempt I posted only works for up to 9
- backreferences and doesn't handle an escaped '\$' and uses nested
- evals:
-
- $str =~ s{$search}{
- my $r = $replace;
- my @d = (0, $1, $2, $3, $4, $5, $6, $7, $8, $9);
- $r =~ s/\$(\d+)/$d[$1]/eg;
- $r;
- }eg;
-
- I wish there was a perl predefined variable array containing all
- the backreferences (is there one?). You can avoid the hard-coded
- limit of 9 with extra evals, and a bit of work on the re could
- handle the escaped '\$' case, so maybe that would be good enough.
-* Craig also notes, in fixing the problem with NEXT not working
+* Craig Barratt notes, in fixing the problem with NEXT not working
inside SWITCH (see Changes v2.04):
By the way, I came across another arcane bug:
@@ -139,30 +116,6 @@
#------------------------------------------------------------------------
-# Stash
-#------------------------------------------------------------------------
-
-* The XS Stash does not work with tied hashes (e.g. DBI.tie). Also note
- that enabling the XS Stash cause all the Template::* modules to be
- installed in an architecture-dependant directory. For info, see
- http://www.tt2.org/pipermail/templates/2001-September/001568.html
-
-* Jonas Liljegren reports a segfault when using the XS Stash under
- Apache/mod_perl with certain undefined variables. At the time of
- writing detail is scarce. Check the mailing list for further
- details.
-
-* Stas Bekman raised the issue of the Stash not being able to correctly
- differentiate between scalar/list context and in particular, the
- cgi.param examples not working as expected. This is fixed in v3 and
- in Craig's Stash/Context.pm which does the right lookahead to allow
- 'scalar' and 'list' postfix operators. e.g. cgi.param.list
-
-* Have stash, etc., add current template name/line when reporting errors.
- (may be tricky under the current implementation)
-
-
-#------------------------------------------------------------------------
# Parser
#------------------------------------------------------------------------
@@ -181,64 +134,6 @@
# foo <- this gets printed
[% tt_end_tag %]
-* Allow { and } as block delimiters, replacing for the ugly ';' and
- big, chunky [% tt_start_tag %] END [% tt_end_tag %] approach.
-
- e.g. something like:
-
- [% tt_start_tag %] FOREACH a = [ 1 2 3 ] [% tt_end_tag %]
- [% tt_start_tag %] IF b == a [% tt_end_tag %]
- [% tt_start_tag %] INCLUDE foo [% tt_end_tag %]
- [% tt_start_tag %] ELSE [% tt_end_tag %]
- [% tt_start_tag %] INCLUDE bar [% tt_end_tag %]
- [% tt_start_tag %] END [% tt_end_tag %]
- [% tt_start_tag %] END [% tt_end_tag %]
-
- could be written as:
-
- [% tt_start_tag %] FOREACH a = [ 1 2 3 ] {
- IF b == a {
- INCLUDE foo
- }
- ELSE {
- INCLUDE bar
- }
- }
- [% tt_end_tag %]
-
-* Ability to set different parser options for BLOCK definitions, etc.
-
- [% tt_start_tag %] BLOCK header
- eval_perl = 0
- pre_chomp = 1
- [% tt_end_tag %]
- ...
- [% tt_start_tag %] END [% tt_end_tag %]
-
- Anonymous BLOCK can then be used to set a parser scope
-
- [% tt_start_tag %] BLOCK trim=1 [% tt_end_tag %]
- ...
- [% tt_start_tag %] END [% tt_end_tag %]
-
- [% tt_start_tag %] BLOCK trim=0 [% tt_end_tag %]
- ...
- [% tt_start_tag %] END [% tt_end_tag %]
-
- And/or set different tag styles, etc.
-
- [% tt_start_tag %] BLOCK tags='star' [% tt_end_tag %]
- [* INCLUDE this_is_a_directive *]
- [% tt_start_tag %] INCLUDE this_is_not [% tt_end_tag %]
- [* END *]
-
- [% tt_start_tag %] INCLUDE back_to_normal [% tt_end_tag %]
-
- This is likely to be a TT3 feature and I've already got the basic
- parser for this up and running. It might get back-pactched into
- version 2, otherwise you might have to wait for the first alpha
- release of verion 3.
-
* Craig Barratt reports the following:
I looked at Parse.yp to see how hard it would be to push FILTER
@@ -336,26 +231,16 @@
* We need a way to easily enable/disable certain plugins. This should
be addressed by facility provision. Probably something for v3.
-* The Text::Autoformat module has some problems with versions of Perl
- prior to 5.6.0 when using a locale which has a decimal separator
- other than '.' (e.g. Swedish, which uses ','). Damian has been made
- aware of the problem (and I note he now has a new version out which
- I need to check). For now, the Makefile.PL issues a warning but
- continues regardless.
-
* The Template::Plugin DBI iterator first/last() methods don't behave
the same as list first/last(). Randal also reports that get_all()
- doesn't work as it should - may be a conflict in code/docs?
+ doesn't work as it should - may be a conflict in code/docs? Again,
+ this is a problem to solve in TT3.
* PLUGINS could accept a reference to an object which is used as a
singleton factory for a plugin. (NOTE: 2.01 includes PLUGIN_FACTORY
to implement this, but currently undocumented because it's likely to
change).
-* Add Leo & Leon's Page plugin, or try to find some way of implementing
- it in terms of the Table plugin. I think the jury is still out on the
- matter of whether it counts as duplicated functionality.
-
* A more general solution for XML (e.g. DOM, XPath, etc) would be for
TT to support a PerlSAX handler which generates the appropriate
callbacks to the view. This should make it possible to easily
@@ -418,6 +303,11 @@
# Splash!
#------------------------------------------------------------------------
+The Splash! library will be extracted into a separate distribution at
+some point (probably when TT3 is released, possibly before). At that
+point it will deprecated (read: not supported by me any more) in favour
+of something better.
+
The current implementation is a fairly ugly hack to get something up
and running that's good enough to use. It's mainly template driven
and doesn't scale very well, particularly with global variables
@@ -468,263 +358,5 @@
a chance to fix a couple of minor bugs relating to '/' vs '\' file
separators.
-
-#------------------------------------------------------------------------
-# Facilities
-#------------------------------------------------------------------------
-
-Core facilities currently implemented by Template::Context should be
-moved out into separate facilities. These currently fall into the
-categories of things like stash, view, plugins, filters, parser and
-maybe some others. (NOTE: this might tie in very closely with Camelot
-and the resource/presenter/actor breakdown, aka model/view/controller).
-
-* 'view' would handle template fetching and processing. It is the view
- that talks to a provider, possibly adding special prefixes, suffixes,
- doing default templates, special dispatch logic, etc.
-
-* 'stash' is responsible for storing variables, as it currently is.
-
-* 'plugins' is responsible for fetching plugins.
-
-* 'filters' is responsible for fetching filters.
-
-* maybe both the above would get bundled into something like 'logic'?
-
-* 'parser' would make parts of the parser accessible
-
-* 'output' could be used to generate output
-
-There would be some facility to install, customise and remove facilities
-to modify TT behaviour as required. This would allow us to disable
-certain plugins, or remove the plugin facility altogether, for example.
-Or we could install a new stash facility which generated a different kind
-of code (e.g. less magic, more speed). Or install a new custom facility
-to do some application or domain specific task.
-
-Facilities should be accessible via the context:
-
- my $stash = $context->stash(); # currently works
- my $view = $context->view(); # not yet
-
-General form:
-
- my $xyz = $context->facility('xyz');
-
-Multiple form:
-
- my ($a, $b, $c) = $context->facility(qw[ a b c ]);
-
-This can then be written into generated code pretty much as the stash
-currently is. The facilities would define the code generators that
-currently clutter up Template::Directives. They would ensure that the
-facility is scheduled to be requested from the context at the start of
-the sub:
-
- sub {
- my $context = shift;
- my ($stash, $view) = $context->faciity(qw( stash view ));
-
-and then transform the various directives into appropriate callbacks
-into the facility:
-
- $output .= $stash->get('x');
- $output .= $view->process('header');
-
-The context becomes a switching centre for the Template Toolkit, with
-most, if not all of its existing functionality moved out to
-facilities. The context should acquire all facilities at the start of
-a process lifecycle, run the template, and then release them all
-again. This should all be done according to the process contract
-which specifies which facilities should be installed, which can be
-modified, what can and can't be be loaded, and so on. The
-contract would also define things like PRE_PROCESS templates, error
-handling, etc.
-
-Thus the role of Template::Service is to undertake a contract with the
-client and attempt to fulfill it. A Template::Contract defines the
-terms of the contract and the Template::Context becomes an embodiment
-(runtime instance) of a contract.
-
-The current context would be available as the 'tt2' template variable,
-with facilities available as object methods. Thus, the following become
-possible:
-
- [% tt_start_tag %] tt2.stash.get('foo') [% tt_end_tag %] # [% tt_start_tag %] foo [% tt_end_tag %]
- [% tt_start_tag %] tt2.view.process('header') [% tt_end_tag %] # [% tt_start_tag %] PROCESS header [% tt_end_tag %]
- [% tt_start_tag %] tt2.parser.start_tag [% tt_end_tag %] # can't do this currently
-
-Directives would be re-written into code like that above. You can
-use the 'tt2.facility.whatever' form when directive syntax would
-otherwise get in the way:
-
- [% tt_start_tag %] mycode( header = tt2.view.process('my/fancy/header'),
- footer = tt2.view.process('your/dull/footer') ) [% tt_end_tag %]
-
-Or to explicitly disambiguate:
-
- [% tt_start_tag %] tt2.stash.get('foo.size') [% tt_end_tag %] # object method
- [% tt_start_tag %] tt2.stash.list.size(foo) [% tt_end_tag %] # virtual method
- [% tt_start_tag %] foo.size [% tt_end_tag %] # lucky dip :-)
-
-Facility management would itself be a facility. Thus, to disable runtime
-facility loading, you would simply unload (or not load) the facility
-management facility.
-
- [% tt_start_tag %] tt2.facility.install(module='my_facility', name='foo') [% tt_end_tag %]
- [% tt_start_tag %] tt2.foo.bar(123) [% tt_end_tag %]
-
-Note that there are some issues relating to cross-cutting facilities,
-otherwise known as "aspects" (see Aspect Oriented Programming). For
-example, variable localisation cross cuts views and data management
-(i.e. tt2.view.include('header', title='my title') must first localise
-the stash and delocalise it again afterwards). It may be appropriate
-to install aspects as separate entities (e.g. 'localisation') which
-can be invoked to apply cross cutting concerns in a generic way.
-Perhaps aspects are implemented as their own facility?
-
- [% tt_start_tag %] tt2.aspect.localise [% tt_end_tag %] ... [% tt_start_tag %] tt2.aspect.delocalise [% tt_end_tag %]
-or
- [% tt_start_tag %] aspect = tt2.aspect.localise [% tt_end_tag %] # cloned & specialised context
- [% tt_start_tag %] aspect.view.process('header', title='my title') [% tt_end_tag %]
-or
- ...
-
-Another example would be debugging:
-
- [% tt_start_tag %] tt2dbg = tt2.aspect.debug(...params...) [% tt_end_tag %]
- [% tt_start_tag %] tt2dbg.view.process('header') [% tt_end_tag %]
-or:
- [% tt_start_tag %] tt2 = tt2.aspect.debug(...) [% tt_end_tag %]
- ...
- [% tt_start_tag %] tt2 = tt2.release [% tt_end_tag %]
-
-
-#------------------------------------------------------------------------
-# Output
-#------------------------------------------------------------------------
-
-It should be possible to stack output buffers. In other words, you
-stop writing to the current output buffer and open a new buffer and
-start writing to that. The final output is simply the concatenation
-of all output buffers.
-
-The clever part of all this is that is should be possible to keep a
-handle on an earlier buffer and go back and append to it at some point
-in the future. A typical use is for generating tables of contents at
-the start of a document when you don't know in advance what the document
-contains. Simply push a new output buffer at the point of the TOC,
-generate the rest of the document (keeping track of all the section
-titles, etc) and at the end of the document, go back and generate the
-TOC onto the end of the first buffer.
-
-Haven't decided on any syntax yet, but it will almost certainly be
-implemented as a facility. At the lowest level, something like
-this perhaps:
-
- [% tt_start_tag %] INCLUDE header [% tt_end_tag %] # write content to first buffer
-
- [% tt_start_tag %] toc = tt2.output.push [% tt_end_tag %] # save current buffer as toc
-
- Blah blah blah # write content to second buffer
-
- [% tt_start_tag %] INCLUDE footer [% tt_end_tag %]
-
- [% tt_start_tag %] tt2.output.buffer = toc [% tt_end_tag %] # re-instate first buffer
-
- This is the TOC # append to first buffer
-
-The output stack would look something like this:
-
- +-----------------+
- | <header> |
- | This is the TOC |
- +-----------------+
- |
- V
- +-----------------+
- | Blah blah blah |
- | <footer> |
- +-----------------+
-
-Which to the end user, would silently be concatenated into:
-
- <header>
- This is the TOC
- Blah blah blah
- <footer>
-
-Another use is to ensure dependencies on other templates get resolved.
-For example, many of the PostScript library templates rely on other
-templates. At present, each template sets a global variable to
-say "I've been loaded" while also inspecting these variables for any
-templates that it relies on, loading them via INCLUDE/PROCESS if not
-set. e.g. ps/cross:
-
- [% tt_start_tag %] # this works, but it's a bit clunky
- DEFAULT radius = '5 mm';
- PROCESS ps/mm UNLESS global.ps.loaded.mm;
- global.ps.loaded.cross = 1;
- -[% tt_end_tag %]
- /cross {
- ...
- }
-
-Better would be to have each template simply activate the flags for
-those templates that it relies on. The header file pushes a new output
-buffer and the footer file goes back to the header buffer and INCLUDEs
-the dependant templates.
-
- [% tt_start_tag %] PROCESS ps/header + ps/complex [% tt_end_tag %]
-
- 10 mm 10 mm complex
-
- [% tt_start_tag %] PROCESS ps/footer [% tt_end_tag %]
-
-ps/complex:
-
- [% tt_start_tag %] global.ps.require.simple = 1 [% tt_end_tag %]
- /complex {
- ...
- simple
- ...
- }
-
-ps/simple:
-
- [% tt_start_tag %] global.ps.require.mm = 1 [% tt_end_tag %]
- /simple {
- ...
- 31 mm 41 mm moveto
- ...
- }
-
-ps/header:
-
- %%!PS-Adobe-3.0
- ...
- %%EndComments
-
- [% tt_start_tag %] global.ps.header = tt2.output.push [% tt_end_tag %]
-
-ps/footer:
-
- [% tt_start_tag %] FOREACH file = ['mm','simple',...];
- INCLUDE $file IF global.ps.require.$file;
- END;
- [% tt_end_tag %]
-
-Ultimately, the whole ps library would become a facility. The
-acquire() method (called by the Template::Service to acquire the
-facility at the start of processing a template) would do the 'header'
-part (i.e. push the output buffer), and the release() method (called
-at the tail end to release the facility) would do the dependency
-checks. The dependency registrations would be facility features,
-e.g.
-
-gs/complex:
-
- [% tt_start_tag %] tt2.ps.require.mm = 1 [% tt_end_tag %] # either
- [% tt_start_tag %] tt2.ps.require('mm', 'simple') [% tt_end_tag %] # or
</pre>