Masterview devel - Sep 2006 - Comments on directive framework implementation

I don''t necessarily want to clean this up quite yet, but let''s
be aware that
the structuring and dependencies between DirectiveBase, DirectiveDSL, and
DirectiveHelpers is a bit muddled up at the moment as code has been pushed
around into different arrangements.

DirectiveDSL is used as base class for DirectiveBase itself, yet relies on
services that come from DirectiveBase (notably attr_value, attrs).  To be
proper, DirectiveDSL ought to be a mixin with a clear statement of
dependencies that it needs to have satisfied ("mix this into your directive
impl/base class and provide the following services...) or it should be
constructed as an abstract class with unimplemented placeholder methods
which are required to be implemented by concrete subclass.

And let me float this for your reaction: I''d *really* like to add some
namespace structure to partition the internal implementation components of
the DirectiveDSL mechanism from the main class.  Ditto the Parser area (and
perhaps even MIO and Analyzer).  When I read rdoc or work with the code,
it''s getting confusing to have the top-level MasterView name space
containing such a mix of major mechanisms along with all their internal
pieces.

[tools note: the ruby plugin I use in eclipse has a very useful Outline view
of code files - similar to how java code is presented, the Outline view
alongside a ruby code file shows you the nesting structure of modules and
classes as a tree, down to the method level, so the implementation and name
space structuring of our code is very "tangible" in the
representations that
I work with alongside the actual code files]

I did a prototype of this in my own working copy, introducting
MasterView::DirectiveDefinition into directive_dsl.rb to partition
AttrArgDef, EventDef, DirectiveClassDef, and DirectiveDSLClassMethods into
an internal namespace that''s essentially "the stuff
that''s the internals of
DirectiveDSL".

Similarly for parser.rb, though this one was a bit less clear what to call
and where to split: I put in MasterView::TemplateProcessing to collect the
internals RenderLevel, RenderMode, DirectiveSet, DirectiveCallStack, Tag,
the sax listener...

I''m finding this makes it a lot easier to work with the code, I
don''t have
to think quite so hard about whether a specific class is a major-feature guy
or an internals-element implementation.

I put a snapshot of these out in branches/djl-namespace-additions-sketch so
you can look at a concrete sample.  There''s some ripple into other
code; a
lot of it is into the unit tests for directives, which are now crying out to
me for some helper services to abstract all the clutter in there about tags
and directive call stacks and such.

~ Deb

On 9/18/06, Deb Lewis <djlewis at acm.org> wrote:
> I don''t necessarily want to clean this up quite yet, but
let''s be aware that
> the structuring and dependencies between DirectiveBase, DirectiveDSL, and
> DirectiveHelpers is a bit muddled up at the moment as code has been pushed
> around into different arrangements.
>
> DirectiveDSL is used as base class for DirectiveBase itself, yet relies on
> services that come from DirectiveBase (notably attr_value, attrs).  To be
> proper, DirectiveDSL ought to be a mixin with a clear statement of
> dependencies that it needs to have satisfied ("mix this into your
directive
> impl/base class and provide the following services...) or it should be
> constructed as an abstract class with unimplemented placeholder methods
> which are required to be implemented by concrete subclass.
>
> And let me float this for your reaction: I''d *really* like to add
some
> namespace structure to partition the internal implementation components of
> the DirectiveDSL mechanism from the main class.  Ditto the Parser area (and
> perhaps even MIO and Analyzer).  When I read rdoc or work with the code,
> it''s getting confusing to have the top-level MasterView name space
> containing such a mix of major mechanisms along with all their internal
> pieces.
>
> [tools note: the ruby plugin I use in eclipse has a very useful Outline
view
> of code files - similar to how java code is presented, the Outline view
> alongside a ruby code file shows you the nesting structure of modules and
> classes as a tree, down to the method level, so the implementation and name
> space structuring of our code is very "tangible" in the
representations that
> I work with alongside the actual code files]
>
> I did a prototype of this in my own working copy, introducting
> MasterView::DirectiveDefinition into directive_dsl.rb to partition
> AttrArgDef, EventDef, DirectiveClassDef, and DirectiveDSLClassMethods into
> an internal namespace that''s essentially "the stuff
that''s the internals of
> DirectiveDSL".
>
> Similarly for parser.rb, though this one was a bit less clear what to call
> and where to split: I put in MasterView::TemplateProcessing to collect the
> internals RenderLevel, RenderMode, DirectiveSet, DirectiveCallStack, Tag,
> the sax listener...
>
> I''m finding this makes it a lot easier to work with the code, I
don''t have
> to think quite so hard about whether a specific class is a major-feature
guy
> or an internals-element implementation.
>
> I put a snapshot of these out in branches/djl-namespace-additions-sketch so
> you can look at a concrete sample.  There''s some ripple into other
code; a
> lot of it is into the unit tests for directives, which are now crying out
to
> me for some helper services to abstract all the clutter in there about tags
> and directive call stacks and such.
>
Yeah, I agree namespaces would help clean up things as would helpers
in the unit/functional tests. Part of the reason that I broke
DirectiveDSL out was so that users woulnd''t be looking at that and
getting confused since it is more supportive functionality rather than
direct accessors and things.

I think namespaces and helpers would help (no pun intended :-)