=head1 NAME
Text::MicroMason::Docs::ToDo - Development Plans for the MicroMason Distribution
=head1 DESCRIPTION
This document outlines various development plans and ideas for Text::MicroMason.
The TO DO section describes plans which are likely to happen.
The WISH LIST section describes a variety of ideas which are likely to
be accepted as patches, but which will most likely not be developed with
any priority any time soon.
If you are interested in a specific feature, whether it is listed here
or not, please contact the current maintainer as described in
L<Text::MicroMason::Docs::ReadMe>.
=head1 TO DO
=head2 Fix all known bugs
So, please report them.
=head2 Distribution
=over 4
=item *
Move the module files into a lib/ directory as expected in modern CPAN
distributions.
=back
=head2 New Mixins
=over 4
=item *
AutoLoad mixin. Using this mixin adds an AUTOLOADER to the mason object,
which interprets all unknown method calls as template names.
=back
=head2 New Features
=over 4
=item *
Support the previously supported but now unsupported
compile(lines => ...) source type. This was documented but non-
functional, and so the pod was removed.
=back
=head1 WISH LIST
=head2 Distribution
=over 4
=item *
Use Module::Build instead of ExtUtils::MakeMaker.
=item *
Consider reorganizing the Text::MicroMason::* modules into a number of
subdirectories. There are currently over two dozen of them, and it's
bound to get worse as time goes on. Perhaps separate them by intent:
Cache::*, Errors::*, Syntax::*, Features::*, etc.
=item *
Finish and test the ParseInfo module to facilitate template
introspection.
=item *
Rewrite the MOTIVATION section of the ReadMe pod to reflect the shift
from an HTML::Mason clone to a more general templating engine that has
at least partial compatibilty with quite a few other modules.
=back
=head2 Interfaces
=over 4
=item *
Test and improve the ApacheHandler interface.
Map user-friendly Apache config directives to mixin and initialization
options. Review HTML::Mason::ApacheHandler, HTML::Mason::Params, and
HTML::Mason::Admin.
Headers need to be constructed as per
http://modperlbook.org/html/ch06_11.html and not sent until our first
print statement; see PLP::Tie::Print.
=item *
Review integration with Inline::Mason. Facilitate use of mixins so this
can also do inline ServerPages and other syntaxes.
=back
=head2 Core Syntax
=over 4
=item *
Determine how to best stack lex_token() method so that multiple syntax
plugins can work together.
=item *
Extract named blocks parsing from HTMLMason to form a separate mixin.
=item *
Extract variable interpolation syntax to allow it to be stacked with
other lexers.
=back
=head2 Syntax Emulations
=over 4
=item *
Add TemplateToolkit module with support for the basic TT syntax. The key
syntax definition is in Parser.yp, which is used to build
Template::Grammar. (L<http://search.cpan.org/src/ABW/Template-Toolkit-
2.14/parser/Parser.yp>) The Template::Stash dot notation can be handled
by Data::DRef.
=item *
Extend HTMLTemplate module with a hash mapping options that could be
passed to HTML::Template's new() into the equivalent behavior, or croak
if they're unsupported.
=item *
Consider extending Embperl module to support dynamic HTML tags.
=item *
Consider extending ServerPages module to support dynamic XML tags.
=back
=head2 Template Sources
=over 4
=item *
Provide a mixin to search for all files matching a given regex to
facilitate tree searches and cache pre-fetching.
=item *
Ensure template inclusion is always handled correctly. Possibly provide
the current template's location in %ENV.
=item *
Add a DHandlers mixin that supports default files. On file requests, if
file not found, look for default file. (Attribute dhandler_name controls
name of file to look for.)
=item *
Add an AutoHandlers mixin that supports wrapper files. On file
requests, also search hierarchy for autohandler files. (Attribute
autohandler_name controls name of file to look for.) Build a stack of
autohandlers and store it in a mason attribute. Support ->call_next()
to work through the chain.
(I've also gotten a user request for "decorator files" which turns out
to be roughly equivalent to the AutoHandler system.)
=item *
Add a TemplateDB mixin which shows how to retrieve templates from a
database table. Provides a read_db() method. Accept a DBI connection as
an attribute -- or a reference to a function which will return rows from
a sql statement.
Consider how to support caching for templates drawn from a TemplateDB.
Perhaps in addition to the source_file there can be some kind of opaque
cache key returned by the prepare method?
Maybe cache values for db templates can be abstracted into closures
which are run to retrieve the cached value.
=back
=head2 Caching
=over 4
=item *
Add a DataCache mixin that provides a pre-configured cache object for
use within template code. Requires cache() method and configuration
attributes. Cache namespace should be based on source file name or
arbitrary instance for text compilation.
Alan says: I believe this is intended for use to cache contextual data
across template runs? Is this intended to be persistent across multiple
templates (in memory/singleton), or across multiple process invocations
(in a file)? I use mod_perl, and this sounds at best not useful and at
worst, dangerous.
=item *
Add an InterpretCache mixin that allows caching of the parsed and
assembled Perl code for a template file, akin to Mason's var/obj/
directory. (This would also allow visual review when debugging the
converted code.)
=item *
The InterpretCache and CompileCache benefit from using a cache object
that checks the keys as filenames to see if the source file has been
updated and forces cache expiration; find a way to extract and reuse
this capability from Text::MicroMason::Cache::File.
=back
=head2 Blessing Templates
=over 4
=item *
Add a BlessSub mixin that blesses the compiled subroutine. This would
let us add support for template-specific behaviors and attributes.
Override eval_sub() to bless sub before returning. Attribute
bless_sub controls initializer arguments passed to BlessedSub class.
BlessedSub class is base class for blessed template objects. Provides
execute() method.
BlessedSub classes may need their own mixin factory... To avoid having
to define separate mixins for both packages, perhaps the methods should
be delegated from the coderef to the Mason instance? (This becomes
particularly attractive if each sub is automatically getting its own
cloned mason instance anyway.)
=item *
Add an AttrBlock mixin, using BlessedSub. Override lexer methods to
parse <%attr> blocks. Stores attribute definitions in a %once block.
Provides attr() method.
=item *
Add a MethodBlock mixin, using BlessedSub. Override lexer methods to
parse <%method> blocks. Stores method definitions in a %once block.
Hooks AUTOLOAD to catch method calls.
=back
=head2 Internals
=over 4
=item *
Consider moving output_sub to a new OutputHandle mixin which accepts a
handle as an attribute, then prints output to it rather than returning
the results as a string.
=item *
Clarify and document the clone-on-change behavior of prepare() and its
effects when making changes to a mason object after compiling a
template. Perhaps we should ensure that we clone every time, or at least
every time that it matters?
=back
=head2 Testing
=over 4
=item *
Set up a benchmarking tool to compare subclasses with other templating
solutions. Take an example from ApacheBench but execute templates
directly rather than via Apache. Store the expected output in a text
file for comparison.
Other links to consider when benchmarking:
http://www.chamas.com/bench/
http://use.perl.org/~hctif/journal/25211
http://www.gtchat.de/templateengines/templateengines_en.html
=item *
Set up a compliance test tool that compares the output of the various
MicroMason mixins with the other modules they emulate. This should be
able to use many of the same data files as the benchmarking tool.
=item *
Add more templates to samples directory and test them.
=back
=head1 SEE ALSO
For distribution, installation, support, copyright and license
information, see L<Text::MicroMason::Docs::ReadMe>.
=cut