path: root/TODO

Cheetah TODO list
-----------------
* If you are working on a task please put your initials at the end of the
  description
* When a task is completed please remember to note it in the CHANGES file
* Unresolved bugs are listed in the BUGS file.  Resolved bugs are be listed
  in the CHANGES file if the bug is considered significant enough and it
  affected a released version of Cheetah.


Requirements for 1.0
=========================================================================
- Python 2.3(b1) causes 16 failures in SyntaxAndOutput.py because the result
  of boolean expressions is now True and False instead of 1 and 0 (or 'True'
  and 'False' instead of '1' and '0' when used as placeholders).  The same
  thing happens with $True and $False.  Do we need a set of parallel tests
  for Python >= 2.3?  
- There's a kludge in CheetahWrapper.py to abort with a helpful error message
  if the user runs 'cheetah test' but doesn't have write permission in the
  current directory.  The tests should instead put their temporary files
  under the system tmp directory.
- Simplify NameMapper.py while maintaining new behavior (ignore dictionary
  attributes/methods when searching for match of first chunk in searchList
  lookup).  Modify _namemapper.c to conform.  Make valueForKey error
  messages more meaningful: for $placeholder.html it raises "NotFound: html";
  it should raise "NotFound: 'html' in $placeholder.html". Consider passing
  the entire unparsed placeholder tag to all NameMapper functions for use in
  a potential error message, the same way we're passing it to the output
  filter.  Also consider passing it to the errorCatcher.  (TR)
- update User's Guide about changes to SkeletonPage (no more #settings,
  etc) (TR)
- Decide on Cheetah's 1.0 license and update the Users' Guide.  Cheetah
  will remain open source, and derived works (open or closed source) will be
  allowed.  The issue is how to make the second part more explicit. (TR)
- Add an example in the distribution of a simplified SkeletonPage
  that used #block but does not have fancy esoteric methods like
  style stuff. (MO)
- Eliminate obsolete #settings directive from 
  examples/webware_examples/cheetahSite/siteTemplate.tmpl  (TR)
- Recognize the exception value as a local variable inside the
  '#except Exception, ex' clause.  Currently $ex raises NotFound.


Other TODO Items
================================================================================

- CheetahWrapper stuff: (MO)
  * "cheetah compile --shbang '#!/usr/bin/python2.2'"
  * "cheetah preview [options] [FILES]"  print template-specific portion of main
    method(s) to stdout, with line numbers based on the .py template module.  
    Make a Template method to do the same thing, a la .generatedModuleCode().
  * Refactor, make compile/fill/code routines callbacks using a bundle arg.
  * If an input file ends in a dot, intelligently add the input extension if
    not found.

- Debugging tools.  See section below.

- Add --error option to compiled templates and "cheetah fill".  It would
  activate the Echo error catcher for debugging.  (Maybe --list-errors to
  suppress output and instead list the not found placeholders?  Less
  important.)

- Provide a utility to list the names of all placeholders in the template.
  Requested by Tracy Ruggles on Feb 21, 2003.

- implement some better error handling for misformed #for, #if, #try directives,
  etc.  At the moment these errors are not caught until Python executes the
  code.

- create better error message for bad code such as:
  ##cache
  This is a cached region.  $voom
  #end cache

- create a better error message for invalid syntax when a $var inside a 
  directive is enclosed in ${} or $(). E.g.:
     #include raw source=${x}
   
- Delete whitespace before a comment on the same line.  The methods are
  Parser.eatComment() and Parser.eatMultiLineComment().  It's already
  working if the line contains 'STUFF#slurp   ## comment'.  Need to make
  it work for 'STUFF    ## comment' (but retain the EOL newline).  

- 'python setup.py uninstall'.  This may require hacking an uninstall feature
  into distutils.

- 'errorCatcher None' to stop catching errors in the middle of a template.

- Utils.WebInputMixin: factor out Cheetah-specific code so it can be used in
  non-Cheetah applications.  Don't modify the searchList: have a Template
  wrapper method do that.  Consider turning it into a function that does not
  require 'self'.  Consider making Webware-specific code into plugins so that,
  e.g., other cookie-handling methods can be grafted in.  Maybe use callback
  classes like the planned rewrite for CheetahWrapper.  Low priority.  (MO)

- Look through Zope Page Templates (TAL) for ideas to borrow.
  http://www.zope.org/Documentation/Books/ZopeBook/current/AppendixC.stx
  http://www.owlfish.com/software/simpleTAL/index.html

Debugging Tools (Dump Tools)
============================
It would be nice to provide debugging tools for users who can't figure
out why a certain placeholder value isn't found or is being overridden.  
My idea is to define $dumpSearchList() and $dumpSearchListFlat() in
Template, which would print a stanza in the output showing all searchList
variables and their values.  $dumpSearchList would group by searchList
element; $dumpSearchListFlat would combine all into a single
alphabetical listing.
        I made an experimental version but it printed only instance variables,
not methods and not inherited attributes.  Also, it wouldn't print right
using the usual pattern of write-to-custom-StringIO-object-and-return-
the-.getvalue() and I couldn't figure out why.
        The stanza should be set apart by a row of stars with the words
"BEGIN/END SEARCH LIST DUMP".  Then for $dumpSearchList, precede each
group with "*** searchList[i], type <element type>, 142 variables ***".
        Because some elements like 'self' may have hundreds of inherited
methods that would create a forest-through-trees situation for the user,
we may need an option to supress the variable listing for elements with
> 20 variables (just print the summary line instead). ?
        The final version should be in Template so it has implicit
access to the searchList and perhaps later to other variables (locals,
globals, "#set global"s, builtins) too.  This is such a central
debugging tool that you should not have to monopolize an #extends
(the template's only #extends) to use it.  You could import it, however,
if you pass in the searchList explicitly as an argument.  In that case,
perhaps we can base it on a generic module for dumping variables/values.
        Note that we cannot simply depend on str() and pprint, because
we need to show instances as dictionaries.  Likewise, dir() and vars()
may get us part of the distance, but only if they show methods and
inherited attributes too.  
        These functions should print only top-level variables, not
the subelements of collections.  I.e, if the first searchList element
is a dictionary, show its keys/values, but do not expand any 
subvalues if they are dictionaries too, unless the display tool happens
to default to that.


Rewrite the caching framework
=============================
- add #cache varyBy= (tied to Tavis' proposed caching framework for Webware)

- #cache test= with a one-variable test produces invalid Python (an empty
  if-block).  Example in Cheetah Developers' Guide, section
  "#cache with test: expression and method conditions".

- #cache id= seems to be ignoring the ID and generating a random numeric
  ID instead.  Is it working?  Do cache IDs have to be numeric?

- Other ideas in Tavis' head.

- Have an option to refresh the cache whenever an external
  file is updated.  This would allow a data structure to be kept in
  sync whenever its text configuration file is changed.

#entry $func($arg1, $arg2="default", $**kw)
===============================================================================
Make a wrapper function in the .py template module that builds a searchList
from its positional arguments, then instantiates and fills a template and
returns the result.  The preceding example would create a function thus:
        def func(arg1, arg2="default", searchList=None, **kw):
                """Function docstring."""
                sl = {'arg1': arg1, 'arg2': arg2}
                if searchList is None:
                        searchList = [sl]
                elif type(searchList) == types.ListType:
                        searchList.insert(0, sl)
                else:
                        raise TypeError("arg 'searchList'")
                t = TheTemplate(searchList=searchList, **kw)
                return str(t)
##doc-entry: and #*doc-entry: comments are appended to the function docstring.
        Finally, make this function accessible directly from the shell.
If there are any non-option arguments on the command line, call the function
instead of filling the template the normal way.  
        This would perhaps make more sense as arguments to .respond().  But
.respond() has that pesky 'trans' argument that mustn't be interfered with,
and other programs may assume .respond() takes only one argument.  Also, 
when called via str(), str() cannot take arguments.
        
#indent
========================================================================
The current indenter (which exists but is undocumented) is a kludge that has an
indentation object, with implicit placeholder calls added at each line to
generate the indentation, and #silent calls to adjust the object.  It should be
reimplemented to generate code to call the indentation object directly.  Also,
the user interface should be cleaned up, the implementation and Users' Guide
synchronized, and test cases built.

The desired implementation revolves around self._indenter, which knows the
current indentation level (a non-negative integer), chars (the string output
per level, default four spaces), and stack (the previous indentation levels).
The .indent() method returns the indentation string currently appropriate.
The desired interface for phase 1 (subject to change):
  #indent strip    ; strip leading whitespace from input lines
  #indent add      ; add indentation to output lines as appropriate
  #indent on       ; do both
  #indent off      ; do neither
  #indent reset    ; set level to 0 and clear stack
  #indent ++       ; increment level
  #indent --       ; decrement level
  #indent pop [EXPR]   ; revert to Nth previous level (default 1)
                   ; if pop past end of stack, set level to 0 and
                   ; clear stack.  All +/-/= operations push the old level
                   ; onto the stack.
  #indent debug    ; dump level, chars and stack to template output

Possible extensions:
  #indent =EXPR    ; set level to N  (likely to be added to phase 1)
  #indent +EXPR    ; add N to level (not very necessary)
  #indent -EXPR    ; subtract N from level (not very necessary)
  #indent balance BOOL ; require all indent changes in a #def/#block to be
                       ; popped before exiting the method.  (difficult to
		       ; implement)
  #indent implicitPop BOOL ; automatically pop indent changes within a 
                       ; #def/block when that method exits.  (difficult to
		       ; implement)
  #indent ??       ; a 3-way switch that combines unbalanced, balanced and
                   ; implicit pop.  (difficult to implement)
  #indent ??       ; smart stripping: strip input indentation according to
                   ; nested directive level; e.g., 
                   ; 01: #if foo=1
                   ; 02:     public int foo()
                   ; 03:     {
                   ; 04:       return FOO;
                   ; 05:     }
                   ; 06: #end if
                   ; With smart stripping, line 4 would be indented and the
                   ; others not.  With "on" or "strip" stripping, all lines
                   ; 2-5 would be unindented.  With "off" stripping, 
                   ; lines 2-5 would not be stripped.

There should be one indentation object per Template instance, shared by
methods and include files.


Upload File
========================================================================
A mixin method in Cheetah.Utils (for Template) that handles file uploads --
these are too complicated for .webInput().  The method should do a "safe"
file upload; e.g., http://us3.php.net/manual/en/features.file-upload.php ,
within the limitations of Python's cgi module.  The user has the choice of
three destinations for the file contents: (A) copied to a local
path you specify, (B) placed in a namespace variable like .cgiImport()
does, or (C) returned.  (B) parallels .webInput, but (A) will certainly be
desirable situations where we just want to save the file, not read it into
memory.  Reject files larger than a user-specified size or not in a list of
user-approved MIME types.  Define appropriate exceptions for typical
file-upload errors.  Method name .webUploadFileAsString?
        One situation to support is when  form has a text(area) field
related to a file-upload control on the same form, and the user has the choice
of typing into the field or uploading a text file.  We need a method that
updates the text field's value if there is an uploaded file, but not if there
isn't.  This may be handled by the regular method(s) or may require a separate
method.

User-defined directives
=======================================================================
IF we decide to support user-defined directives someday, consider Spyce's
interface.  Spyce uses a base class which provides generic services to
custom "active tags".
http://spyce.sourceforge.net/doc-tag.html
http://spyce.sourceforge.net/doc-tag_new.html


Test Suite
================================================================================
- test cases for the SkeletonPage framework
- add cases that test the cheetah-compile script
- add cases that test the integration with WebKit.  Since these must be called
  from a running WebKit server, make a servlet that runs the tests and outputs
  diagnostics to the browser.

Website
================================================================================
- automate the documentation update 
- See if we can get WebKit working on Sourceforge...

Examples
================================================================================
- create some non-html code generation examples
  - SQL
  - LaTeX
  - form email
- Template definitions in a database.  .py template modules in a 
  database?  Caching template classes and/or instances extracted from
  a database.
- Pickled templates?