[Zope3-dev] documenting for understanding (meta.py)

[R. David Murray]

OK, in order to try to wrap my brain around this code, I'm trying
to document my understanding.  There are currently lots of holes
in that understanding, but I've got something that should be
reasonably correct that documents the structure of the _directives
registry in meta.py.  Please fix my mistakes, and I'll add this as
a docstring above the place where _directives is initialized.

Note that I believe that DirectiveNamespace should have a
__class__implements__ = INonEmptyDirective, and that
there also should be a directive.__implements__ = INonEmptyDirective
in the class body.

--RDM

"""
_directives is a registry that holds information on zcml directives
and subdirectives.  It is filled by the 'directives', 'directive' and
'subdirective' directives that are provided as the bootstrap
directives by the _clear function of this module.

The top level of the registry is a dictionary keyed by two element
tuples.  Each key tuple consists of a namespace designator (such as
http://namespaces.zope.org/zope) and a directive name.  Thus, the
key that accesses the 'directive' directive is::

    (http://namespaces.zope.org/zope', 'directive')

The value of a directive entry is a two element tuple consisting
of a callable and a (possibly empty) subdirective registry.  The
callable is the object to be called to process the directive and
its parameters.  The callable must be either an IEmptyDirective (in
which case the subdirective registry should be empty), or an
INonEmptyDirective (in which case there should be one or more entries
in the subdirective registry).

A subdirective registry is also keyed by (ns, name) tuples.  Handler
methods for subdirectives are looked up on the ISubdirectiveHandler
object that is returned by the INonEmptyDirective that handles
the directive to which the subdirective registry belongs.

The value of an entry in the subdirective registry can be in
one of two forms:

  1) subdirective registry -- in this form, the value is a dictionary
     keyed by (ns, name) tuples that identify sub-subdirectives.
     The name of the subdirective is used to look up the method on
     the ISubdirectiveHandler that will handle the subdirective.

  2) tuple -- in this form, the value is a two element tuple
     consisting of a subdirective registry and a string.  This
     string will be used to look up the method on the
     ISubdirectiveHandler that will handle the subdirective.

The callable that results from the lookup of the handler name on
the directive handler object should implement either IEmtpyDirective
or INonEmptyDirective.  The accompanying sub-subdirective registry
should be empty or not, accordingly.

XXX: If I do XMLConfig('site.zcml')() and then inspect _directives,
I see the actual methods and not the names.  I'm not sure yet where
this transformation happens, but registersub is clearly putting
a name in there.
"""