=============================
README: Cellulose
=============================

:Author: Matthew Marshall
:Contact: matthew@matthewmarshall.org

Cheesy summary written up for the Cheeseshop
--------------------------------------------

Cellulose provides a mechanism for maintaining consistency between
inter-dependant values with caching and lazy evaluation.

You can think of it like a spreadsheet program --  Many cells are are calculated
from the values of other cells.  When one cell changes, all of the dependant
cells get updated with new values.

However, cellulose goes quite a ways beyond this.  It guarantees that when a
value is read, it is consistant with all the values it depends on.  It also is
lazy (read: efficient.)  Calculating a value is put off till the very last
possible moment, and only recalculated when absolutely needed.

Dependency discovery and cache invalidation are fully transparent and automatic.
This greatly reduces a major source of bugs in software.

A goal of the project is to be as simple as possible, (but no simpler,) so that
anyone wanting to seriously use it could easily understand the internals.

Cellulose is similar in purpose to PyCells, but is in a way 'lower level'.  It
tries real hard to stay out of your way, but, as a result, lacks some of the
helpers that PyCells provides.  The most essential algorithmic difference is
probably that Cellulose desperatly wants to be lazy, while in PyCells everything
is calculated immediately (by default.)  (On the flipside of this, observers in
PyCells are quite a bit easier to work with.)


Documentation
-------------

In the docs directory there is an attempt at a tutorial that should explain
usage.  There is also a document giving a high level explanation of how the
algorithm works.  I highly recommend reading (and understanding) this if you
decide to use cellulose.

Please let me know if you find any of it confusing.  I've reworked the entire
thing in my thoughts enough times that I might have made up some terminology :-)


Future directions
-----------------

 *  I *really* want a way to have network support.  It should be possible to do
    it elegantly without modifying any current modules, just by using the
    ``deep_dependencies`` feature in the DependantCell class.  I have some basic
    ideas on how it would work, I just need to get around to trying it.

 *  A general use way of observing for changes needs to be made.  What is
    currently in observers.py is more or less in the direction I want to go, but
    it at least needs more 'syntactical sugar.'

 *  A somewhat common use case I have been seeing is maintaining a list that is
    a filtered copy of another list.  Having efficient helpers to make this easy
    would be really nice.

 *  Perhaps prevent cells from being modified while a cell is being calculated.
    (ie, no side effects.)  (and naturally, this should be optional)

 *  A good way to introspect restrictions would probably be needed.
    (restrictions in general might need to be rethought.)

 *  I'd like to experiment with ways to vectorize computed cells, but that's
    further down the line.


Notes on the 0.1 release and stability
--------------------------------------

Right now, I feel that the stuff in cells.py, descriptors.py, and celltypes.py,
(just about everything mentioned in the docs,) is pretty stable.  The two other
modules, restrictions.py and observers.py, will probably need some major
changes.  They work well with everything I have done so far, but are hardly
flexable enough.  (There is not really anything in them, anyway.)

Contributions are welcome!

