[Email-SIG] More API thoughts (policy objects)

[R. David Murray]

I've been mulling on policy objects since talking with Barry about them at
the sprint.  Today I sat down and started on the "real" API documentation
(ie: in Sphinx, fully written out not just sketched).  So far I have
the stub of the main email doc copied from the current package, with the
intro turned into an XXX, and the new changes sections marked with an XXX,
and a cut down table of contents listing only the new docs I've written.

There are two doc sections currently, Policy Objects, and Headers.
Headers is somewhat revised from both my original proposal and from the
code actually implemented in the bzr branch.  This is because I realized
as I was writing the docs that I'd failed to think through how header
subclasses were going to get created.  Creating the correct subclass
requires knowing the field name of the header for which an object is
being instantiated, which means that the parser can't just gather header
lines and pass them to the header class to parse the way I'd originally
visualized.  Instead we need a factory function that will look up the
field name in the registry and instantiate the correct class, passing it
the name and value.

Since the registry is going to be in the policy object, that led me
to write the policy object docs.  After several iterations over both
documents, I have something that I think at least hangs together, and
which I think is fairly decent from a usability standpoint (I hope...that
opinion is based on thought experiments, not real code, after all!).
I'm not sure yet about the higher levels (the parser...or is the
Message object the parser?), but I've got a vision of how the Message
objects, the Header objects, and Message sub-objects plug together.
The plugging-together isn't documented yet, although the existing docs
give some good glimpses.

One potentially controversial bit of this design is that I'm planning
to have the header factory pull together three independent classes
and dynamically build a composite class out of them to instantiate an
object from.  This is not something I've ever done before in code, so I'm
not sure it will even work.  But it seems to make sense as a design,
so I've speced it that way.  I'll be curious if anyone has any insights,
opinions, or better ways of accomplishing the same goal.

This design arose from the fact that in my overall design the Bytes and
String classes share a common base class and that most of the code is
common between the two.  When thinking about the registry of structured
headers, it felt rather yucky to have either two registries (bytes and
string) or a registry with (bytes class, string class) tuples.  Add to
this the fact that it would be really nice for an application to have a
way to substitute in its own base class without having to build a whole
new subclass tree, and I decided to give dynamic class building a try.
So the design I've speced has a header factory method looking up the
base class, the string or byte class, and the specific header class in
the registry, and then composing the three of them in order to return
a header instance.

Am I crazy?

Anyway, if you want to look over the docs (most of which are probably
valid even if I end up having to give up on my composition-based
registry), they are up on my web site here:

http://www.bitdance.com/projects/email6/doc/email/

--David

PS: it's not clear to me that policy objects make thread safety natural,
although they do make it *possible*.