[Templates-cvs] cvs commit: TT3 TODO
cvs@template-toolkit.org
cvs@template-toolkit.org
Mon, 13 Dec 2004 15:47:37 +0000
cvs 04/12/13 15:47:37
Modified: . TODO
Log:
* totally updated the TODO list
Revision Changes Path
1.12 +425 -90 TT3/TODO
Index: TODO
===================================================================
RCS file: /template-toolkit/TT3/TODO,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- TODO 2004/12/13 13:33:32 1.11
+++ TODO 2004/12/13 15:47:36 1.12
@@ -1,88 +1,422 @@
#------------------------------------------------------------------------
-# random notes that I'm adding as I go along...
+# Main TODO list - this list is incomplete
#------------------------------------------------------------------------
-Dec 12
- - need to figure out the right thing to do wrt template source/component
- id parameter. store/cache require a solid id.
-
-Dec 09
- - Template::Context should use parent locations when locating
- - Template::Base raising warnings via warn()
-
-Dec 03
- - it would be nice if static paths (e.g. a double quoted block name that
- doesn't contain any variable references - see parser parse_path())
- could contain references to constant variables.
- - come up with a more elegant solution for nested tags than the current
- hack between Template::Tag::Directive and Template::Parser
-
-Nov 29
- - Fix constructor methods that delete items in config hash (e.g. Tagset)
- to ensure that we don't munge any configurations that need to be reused.
- - need to add argument merging in compiler generator() method, and also
- think about if we need to do it in handler(), too.
-
-Nov 25
- - Think about capturing into variables, e.g. [% x = INCLUDE header %]
- Perhaps new operator? See design/capture
- - have GET and CALL look for lists, as per set. Must update dir/get
- and tag/dir implicit_get
- - how to handle SET/DEFAULT? [assign => x, 10] works for set() (generates
- $stash->set(x, 10)) but needs to be different for default, constants, my
- vars, etc.
-
-Nov 23
- - add index() method to Template::Modules (particularly Directives) and
- other resource providers
- - remove any C<delete $config->{ item }> code in init() methods, where
- modifying the config hash would prevent us from re-using the config
- in a subsequent invocation of the object (e.g. tagset, directives, etc.)
- that are recreated on each template parsed.
-
-Nov 19
- - What about having Tag::Directive check keyword of next directive and call
- $handler->expects() to check it's OK before we proceed into $dir->parse();
- Otherwise we can only detect errors when we submit the directive to expr(),
- by which time we've lost the keyword/line number/etc.
-
-Nov 18
- - change parser tag_end to end in config and methods.... or not?
- - Move Template::Tagset::TT::Interpolate into Template::Tagset::Interpolate
- - Figure out where TT tagset goes (Template::Tagset::TT, Template::TT3::Tagset,
- or just Template::Tagset?)
- - allow [% END_IF %] or [% END-IF %] or [% END(IF) %] or something similar
+Language Issues
+ * namespaces to bind some kind of functionality to a particular
+ prefix. For example:
-#------------------------------------------------------------------------
-# Other misc items in no particular order... most of these are scribbled
-# in my two jumbo notepads and various other books, scraps of paper,
-# etc., so this list is very incomplete.
-#------------------------------------------------------------------------
+ [% NAMESPACE
+ tt = TT
+ user = DBI.Row(table => 'user', key => 'id')
+ %]
+
+ [% tt:template.name %] # current template name
+ [% me = user:abw %] # fetch user 'abw' from DBI
+
+ * reserved variables should be moved into a single TT variable,
+ e.g. TT.template.name, TT.error, TT.loop, and/or defined in a
+ tt: or TT: namespace, e.g. TT:error, TT:loop, etc.
+
+ * foo."key with space" vs "literal string".length
+ First uses string to quote key value, wheras second defines a
+ literal string and then calls a vmethod on it. I think difference
+ is OK, because the first node of a variable is always special.
+
+ * string concatentation operator(s)
+
+ * parsing and handling template paths as terms.
+
+ [% header = /site/header %]
+ [% header.title %]
+
+ * replacing the magical IMPORT variable and magical import()
+ rootop with with hash virtual method hash.import(hash) and
+ use of @variables, e.g.
+
+ [% import(hash) %] => [% SET @hash %]
+
+ [% INCLUDE foo => [% IMPORT foo @hash %]
+ IMPORT=hash
+ %]
+
+ * in addition to FOREACH, maybe also a FOR directive which creates a
+ simple Perl for loop without an iterator
+
+ * allow [% END_IF %] or [% END-IF %] or [% END(IF) %] or something similar
+
+ * would be nice to allow curly brackets for small code blocks,
+ but the dangling else problem makes this very hard.
+
+ [% IF x {
+ INCLUDE y
+ }
+ ELSE {
+ INCLUDE z
+ }
+ %]
+
+ Things get extra tricky if you consider blocks across tags and the
+ fact that there's no END keyword in the above. No, I think not.
+
+ * "here-docs". Thinking about how you sometimes want to define a
+ large chunk of text as a parameter or something similar.
+
+ [% INCLUDE header title=<<EOF %]
+ The long and very boring title...
+ [% EOF %]
+ Hard to parse and construct across tags. Pass on this for now.
+
+ * Think about capturing into variables, e.g. [% x = INCLUDE header %]
+ in TT2 style. We can do this now with nested tags,
+ [% x = [% INCLUDE header %] %], but we may want an explicit
+ CAPTURE directive (think of a better name!),
+
+ e.g.
+ [% CAPTURE x; INCLUDE header; END %]
+ or
+ [% INCLUDE header CAPTURE x %]
+
+ This comes back to the issue of named blocks (which are very
+ similar). If we can access blocks as paths, then perhaps this
+ problem goes away (or at least has a work-around). Or perhaps
+ we have a new operator for this, like << or >>?
+ See design/capture for more rambling on this.
+
+ * have GET and CALL look for lists, as per set. Must update dir/get
+ and tag/dir implicit_get
+
+ * how to handle SET/DEFAULT? [assign => x, 10] works for set()
+ (generates $stash->set(x, 10)) but needs to be different for
+ default, constants, my vars, etc.
+
+
+Provider
+
* provider generating Template::Source with all options passed
- * whole issue of where source/components store options, etc.,
- and what gets passed between cloned components.
+ * more provider-driven options, e.g. file extension used to set
+ compiler option
- * providers returning undef to indicate not found, or subroutines
- that return undef??
+ * general handling for file extensions: e.g. having a set of
+ default extensions to add to the name requested, or doing
+ extension re-writing on the way, and so on
+
+ * namespace/resource/prefix option which defines those prefixes
+ on names passed to fetch() that the provider should accept.
+ Needed to implement TT2-like feature of named providers, and
+ also provide hook-in for other providers...
+
+ * other providers like DBI, HTTP, RSS, etc.
+
+ * provider returning list of templates (e.g. extra header and footer),
+ or a delegate template (e.g. wrapper, or process), or something
+ like Mason's dhandler/autohandler, in addition to or instead of
+ the original template it was asked for. May be better off handling
+ this in the service layer. After all, we don't want every library
+ template prefixed with a 'header' template because there's a 'header'
+ file in the lib directory. However, we might want to drop a 'header'
+ file in amongst our *.html pages to indicate to the provider that
+ (with the right provider options set, of course), it should prefix
+ each page served from this location with the header. But of course
+ the provider doesn't do any of that - it just sends a source object
+ back, so we need some way of sending back a composite source document,
+ containing other source docs or composites, that the calling
+ template resource can handle as appropriate.
+
+ * Consuming providers? Should the provider have a store() method,
+ and should we be calling it a provider at all? I'm leaning
+ heavily towards renaming Template::Provider as Template::Templates
+ and then subclassing as Template::Templates::DBI, etc. Or we
+ use the File/Directory abstraction (note: it's an abstraction
+ of a file/directory, not an implementation issue) and make
+ Template::Directory return Template::File objects, but also have
+ Template::Directory::DBI, for example, to provide a DBI
+ implementation of a directory-like structure.
+
+
+Compiler
+
+ * compiler provision from single Template::Compilers or special
+ Template::Resource::Compiler which discovers a compiler. Must
+ take into account any directives or other compiler-related
+ resources defined in between the point of compiler origin and
+ the current context
+
+ * Template::TT2::Compiler is a quick hack, but working. Could do
+ with proper conversion to Template::Generator and/or
+ Template::Handler for back-end intermediate parse tree
+ construction for later feeding into a generator (e.g. TT2->TT3)
- * think about TT paths (always use '/') vs filesystem specific paths
- * what about loading template but not compiling, e.g. for INSERT?
+Scanner
* clean up dos and mac line endings
s/\r\n?/\n/g;
- * disable interpolate in PERL blocks
+ * XML scanner as proof of concept
+
+ * turn example/htmlt.pl into a proper module (Template::HTMLTemplate?)
+ as a proof of concept, if nothing else.
+
+ * Scanner for HTML::Mason tags, again as proof of concept at this
+ stage
+
+Tags and Tagsets
+
+ * allow tags/tagset to be passed as an option to scanner scan()
+ method?
+
+ * $tagset->tags( name => $newtag ) to update tagset tags.
+
+ * common base class for Tag and Tagset to abstract enable/disable
+ code and other similar features?
+
* have TAGSET option to load/use an entire tagset
[% TAGSET none %] # no tags whatsoever
[% TAGSET tt3 %] # just tt3 tags
[% TAGSET abw %] # custom tagset
+Directives
+
+ * implement a schema-like set of parse rules: Sequence, Repetition,
+ Alternation (or 'all', 'many' and 'any'). Note: already did this
+ to prototype level but gave up because it was obscuring some of
+ the trickier issues in the parser/directive interaction that I
+ needed to sort out first.
+
+ * proper namespaces (like XML namespaces) for directives. The
+ default namespace for TT would be something like
+ http://template-toolkit.org/schema/TT3 so that the [% INCLUDE %]
+ directive would be implicitly http://..blah../TT3/INCLUDE
+ We get to keep the simple front-end syntax, but provide a
+ rigid namespace mechanism underneath for more complex document
+ magic when you need it.
+
+ * What about having Tag::Directive check keyword of next directive
+ and call $handler->expects() to check it's OK before we proceed
+ into $dir->parse(); Otherwise we can only detect errors when we
+ submit the directive to expr(), by which time we've lost the
+ keyword/line number/etc.
+
+
+Parser
+
+ * parsing resources/namespaces
+
+ * parsing unquoted paths as terms
+
+ * it would be nice if static paths (e.g. a double quoted block name that
+ doesn't contain any variable references - see parser parse_path())
+ could contain references to constant variables.
+
+ * come up with a more elegant solution for nested tags than the current
+ hack between Template::Tag::Directive and Template::Parser
+
+
+ * C-style comments /* like this */ should be easy to detect and
+ could possibly be used to comment out entire directives like so
+
+ some text
+ [% /*
+ some code include [% directives %] all of which
+ is ignored.
+ */
+ %]
+ some more text
+
+ * Or we just define a comment tag which can be enabled to allow
+ C-style comments in text.
+
+ some text
+ /*
+ some code include [% directives %] all of which
+ is ignored.
+ */
+
+
+Handler
+
+ * unwinding stack at end of handler - there's some code that
+ should be in end(), and that should tie in with a check in
+ end_expr() for a missing parent.
+
+ * dedicated handler module for outermost template - this could
+ implement special one-off magic for checking sanity of template,
+ etc.
+
+
+Generator
+
+ * Template::Generator::TT3 to re-generate the original template
+ text, or close enough to it, in full TT3 syntax, allowing us to
+ parse a TT2 template and emit it in new TT3 style.
+
+
+Source and Component
+
+ * need to figure out the right thing to do wrt template
+ source/component id parameter. store/cache require a solid id.
+
+
+Cache and Store
+
+ * different examples of cache/stores?
+
+
+Context and Scope
+
+ * context localisation
+
+ * Template::Scope should use parent locations when locating
+
+ * Template::Scope index() method to build an index of a resource.
+
+ * providers returning undef to indicate not found, or subroutines
+ that return undef??
+
+ * visit history for context (todo, doing and done)
+
+ * output buffer
+
+ * stringification of items into output buffer (required to stringify
+ certain objects)
+
+ * pushing non-text items into output buffer
+
+ * pushing a buffer (e.g. table of contents) into an output buffer
+ that will get filled up later, but should be resolved at end
+ of template when output is squished and returned.
+
+
+Stash / Template::Resource::Variable
+
+ * implement stash mechanism for @variable, or check if I haven't
+ done it already.
+
+ * stash throwing exceptions when variables not found or undefined,
+ configurable by options to Template::Resource::Variable (nee Stash)
+
+ * folding list of return value from a sub/method into a reference
+ to a list (as per TT2) or just don't do it?
+
+
+Filters
+
+ * These haven't been implemented at all. We've got the TT2
+ filters and could easily whip them into shape, but the whole thing
+ need a little rethink.
+
+ * First we want to allow filters to be defined in modules, e.g.
+ Template::Filter::Foo so we can load on demand rather than
+ requiring all filters in memory up front.
+
+ * Second we want to unify the concepts of filters and virtual
+ methods, so that we can apply any text virtual method as a
+ filter or vice versa
+
+ * Third, the '|' symbol is going to become a dot-like operator
+ which binds tightly to a variable. We need to parse this,
+ generate the appropriate code and implement the runtime
+ functionality to implement vmethod/filtering.
+
+ * Fourth, we need to figure out how to differentiate between
+ named filters that get loaded on demand (e.g. html), and
+ those which are otherwise defined by a Template::Filters
+ provider or defined in a context filters item, and those which
+ are locally defined subroutines or macros that we want to apply.
+
+ e.g. do we allow this:
+
+ [% MACRO bold(text) GET "<b>$text</b>" %]
+ [% "hello" | bold %]
+
+ And then how do we make all that work behind the scenes in terms
+ of locating the variable but not calling its code sub (need a
+ get_ref()-like method)? And how do we map filters onto vmethods
+ and back again.
+
+ And so on. Filters need some more thinkage.
+
+
+Modules
+
+ * iterator and the whole issue of FOREACH
+
+ * finish moving Template::VObject::* into Template::Object::*,
+ create Template::Objects.
+
+ * Template::Match as a base class for matching functionality
+ shared between tag/keyword matching?
+
+ * Move Template::Tagset::TT::Interpolate into Template::Tagset::Interpolate
+
+ * Figure out where TT tagset goes (Template::Tagset::TT, Template::TT3::Tagset,
+ or just Template::Tagset?)
+
+
+Module Sets
+
+ * Move all DBI related modules from TT2 into new Template-DBI
+ module set. To include current DBI plugin, DBI provider,
+ and some other useful providers for representing a table,
+ fetching a row, etc. Hook these into a namespace for fetching
+ a user, for example:
+
+ [% NAMESPACE user = DBI.Row(table => 'user', key => 'id');
+
+ me = user:abw
+ %]
+
+ * Template-Image to contain current image plugin, but also
+ image resource, image tag and various other bits and pieces
+ to provide image handling support in TT.
+
+ * Template-Latex for all LaTeX plugins, etc.
+
+ * Template-GD for all GD plugins, etc.
+
+ * Any other non-trivial plugins to be moved out into separate
+ modules and/or bundle.
+
+ * Bundle::Template::Plugins::* for other bundles of plugin
+ modules, e.g. for text processing, HTML, CGI, etc.
+
+
+Scripts
+
+ * main 'tt' script for building, compiling, etc., to replace
+ tpage and ttree.
+
+
+Miscellaneous
+
+ * whole issue of where source/components store options, etc.,
+ and what gets passed between cloned components.
+
+ * think about TT paths (always use '/') vs filesystem specific paths
+
+ * what about loading template but not compiling, e.g. for INSERT?
+
+ * disable interpolate in PERL blocks
+
+ * test binmode and utf8 output in t/utils.t
+
+ * Fix constructor methods that delete items in config hash (e.g. Tagset)
+ to ensure that we don't munge any configurations that need to be
+ reused. (may be done but needs checking)
+
+ * need to add argument merging in compiler generator() method, and also
+ think about if we need to do it in handler(), too.
+
+ * Template::Base raising warnings via warn() (and the whole issue
+ of why nothing currently uses warning())
+
+
#-------------------------------------------------------------------------
# TT2 Directives (x marks those that are done)
#------------------------------------------------------------------------
@@ -136,11 +470,10 @@
#------------------------------------------------------------------------
# Modules that are completely finished, tested, documented and listed in
-# in docs/modules.pod. This section is growing.
+# in docs/modules.pod. This section is (very) small, but growing.
#------------------------------------------------------------------------
Template::Base
-Template::Utils
#------------------------------------------------------------------------
@@ -148,6 +481,10 @@
# it's growing.
#------------------------------------------------------------------------
+Template::Utils
+
+ - just needs a binmode/utf8 test or two for save_file()
+
Template::Cache
- code is complete and working. There's a comment in the source to
@@ -161,11 +498,11 @@
Template::Compilers
- - Working implementation, but should subclass from Template::Modules.
+ - Mostly Working.
Template::Component
- - Still in active development.
+ - Still in active development but mostly working
Template::Constants
@@ -189,14 +526,13 @@
Template::Directive::*
- - TODO: haven't reviewed these yet
+ - TODO: haven't reviewed these yet, most are still under active
+ development - see earlier lists
Template::Directives
- - Code is functional, although the call to load_all() from directives()
- is a quick hack to get it working as required. I think this functionality
- should be built into the Template::Modules base and enabled via a package
- variable or configuration option.
+ - Code is working, although I want to re-address the issue of leading
+ all directives up front (a quick hack to get it working as required).
- Docs need writing.
@@ -227,7 +563,7 @@
- Docs need writing
- - t/generator.t tests need writing
+ - more t/generator.t tests need writing
Template::Generator::*
@@ -241,31 +577,29 @@
for building multi-faceted template content rather simply constructing
structured expressions.
- - t/module.t tests the basic text(), next_text(), prev_text() and expr()
+ - t/handler.t tests the basic text(), next_text(), prev_text() and expr()
methods, and also the pending(), commit(), rollback() methods for
handling side-effect directives. However, all the tests for start_expr(),
next_expr() and end_expr() are missing. There are some old tests
(commented out) for start_block(), etc., that can possibly be modified
or re-written.
-Template::Modules
+Template::Factory
- - code is all done and documented. Could perhaps do with a few more
- tests in t/modules.t, particularly to test subclasses. However, there
- are other modules that subclass from Template::Modules (e.g.
- Template::Plugins) so if something does get broken, we'll know about
- it from t/plugins.t, etc.
+ - the factory and related modules (Template::Factory::Modules,
+ Template::Factory::Singletons and Template::Factory::Objects) seem
+ to be working well. Need documenting.
Template::Parser
- - Most, if not all of the code is working, but the module is still
- under active development and changing in minor ways here and there.
+ - Most, if not all of what is implemented is working well and documented.
+ There are some more methods to add and a few to tweak here and there,
+ but it's well on the way to being finished.
- - Docs need writing
+ - Docs are mostly done.
- There are oodles of tests in t/parser/*, but I haven't yet checked that
- they cover all of the parser code base. Ongoing work required as
- parser changes.
+ they cover all of the parser code base, but it's certainly very thorough.
Template::Plugin
@@ -359,10 +693,10 @@
Template::Test
- - TODO: haven't reviewed this yet
+ - Mostly done, although a few of the test_xxxx() method might need
+ tidying up.
- - Need to add code to handle 'tests' load argument.
- use Template::Tests tests => 33;
+ - Documentation needs work.
Template::TT2
@@ -390,8 +724,9 @@
Template::VObject
- - TODO: haven't reviewed this yet
+ - TODO: haven't reviewed this yet, planning to move them into
+ Template::Object.
Template::VObject::*
- - TODO: haven't reviewed these yet
+ - TODO: haven't reviewed these yet, ditto about moving them.