[Chandler-dev] Feedback request: Trellis API refactoring

[Phillip J. Eby]

Just a quick heads-up for anybody who's done or plans to do any 
Trellis coding; I've just posted to the PEAK mailing list about some 
possible changes to the high-level Trellis API and terminology to 
incorporate some new features including dynamic connection to 
non-Trellis callback-based systems (such as Twisted, wx, and 
SQLAlchemy), and "lazy" rules (so that e.g. menu update calculations 
only need to get done when a menu is actually popped up).  For the 
background on the external connection features, see the thread beginning here:

   http://www.eby-sarna.com/pipermail/peak/2008-March/002896.html

For the "lazy rules" and API terminology discussion, see here:

   http://www.eby-sarna.com/pipermail/peak/2008-March/002903.html

I'm particularly interested in knowing whether the API terminology 
I've laid out in this latter post, consisting of various combinations 
of these 14 terms:

   Basic nouns/verbs: variable, @compute, @maintain, @perform
   Value/state control: initially=, resets_to=, .readonly, optionally.
   External connnection: @.connect, @.disconnect, @.transmit
   Miscellaneous: @task, @todo, attributes(**kw)

Is any clearer than our existing terminology, which uses these 12 
terms (with fewer combinations, but also significantly less descriptive power):

   rule, rules, value, values, optional, todo, todos,
   receiver, receivers, discrete, task, observer

Essentially the translation goes something like:

   rule                    => maintain
   rule+value              => maintain(initially=...)
   rule+discrete           => maintain(resets_to=...)
   rule+value+discrete     => maintain(resets_to=...)

   optional                => optionally.maintain
   optional+discrete       => optionally.maintain(resets_to=...)
   optional+value+discrete => optionally.maintain(resets_to=...)

   observer                => perform
   optional+observer       => optionally.perform

   value(...)     => variable(...)
   receiver(...)  => variable(resets_to=...)

   rules(...)     => rule.attributes(...)
   values(...)    => variable.attributes(...)
   todos(...)     => todo.attributes(...)
   receivers(...) => variable.attributes.resetting_to(...)

And everything else (compute, .connect, .disconnect, .transmit, 
.readonly) provides access to new features that are not in the existing API.

Anyway, if you've done any work with the Trellis, I'd appreciate any 
feedback you have on the proposed API rework.  As a side benefit of 
the change, it will also be cleaning up lots of hairy bits in the 
current API implementation, but the downside is of course that 
porting will be required.  Still, if this has to get done, it's 
better done sooner than later, and we are technically still in 
0.6alpha releases for the Trellis.  :)