Masterview devel - Jul 2006 - Another idea for the single file format for directives

We could use an inner class to hold the description and examples

class MyDirective
  class MetaInfo
     def description
       ...
     end

     def example
       ...
     end

  end
end

or even simply a Map to hold the pieces.

Just other ideas to add to the list.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060717/8e2b7520/attachment-0001.html

Yeah I see where you are going. I think this is shaping up. The only concern
is how to make it easy for people to submit these via upload without
packaging. If we were doing things in a single file (or two if they have
test cases) then I think they can handle it (many won''t do tests so
that
means one file). Simple http file upload and they are done.

Also simple install, place the single directive file in your directory and
you are done. Your dynamic doc app will be able to pick up the docs and
examples.

So if we include this meta class in the same file along with the directive
then I think it works well, doesn''t have to be an inner class just
pushing
for single file (+separate test file if they have one).

If we package things up for distribution then we certainly could split
things into separate files if we wanted to, however there is something to be
said for consistency.

So what do you think. I think the meta info class has merit for all the
things described (namespace, attr name, desc, examples), however how do we
keep it simple and down to single file upload and install?

On 7/18/06, Deb Lewis <dlewis at thinkfive.com>
wrote:
>
>  Jeff - I like the notion of having a standard DirectiveInfo meta-info
> class to associate with a directive implementation, which provides a
> standard approach for expressing the interesting metadata for a directive:
> version, description, optional category.  As you say, that then gives us a
> clean way to drive other interesting tools (admin views of loaded
> directives, doc generation, etc)
>
> Not sure if I like having the example bundled into the core runtime
> class.  Maybe example (and even description) are better done by a sibling
> class, located by convention using  name derived from that of the
> ModName::DirectiveClass, e.g. ModName::DirectiveClassDoc to contain
> supporting doc specifications?
>
> Similar to scheme for packaging and locating test cases - my_directive.rb
> + my_directive.rb pair of files.
>
> Also include optional attribute_name in there, so that our implementation
> of the standard class method attr_name on DirectiveBase can check for
> override before dropping into default_attr_name backstop.  (Or maybe that
> just all migrates into DirectiveInfo as method #attr_name or
> #attribute_name; I prefer the longer form, actually)
>
> I''d also like a namespace attribute in there to provide the
foundation for
> supporting multiple namespaces: #namespace_name. That would then be
> exploited by our standard methods for forming fully-qualified attribute
> names.  Someone assembling a library of addons could then subclass
> DirectiveInfo to install their own std namespace value and then use
> MyCustomDirectiveLibraryDirectiveIinfo in their directives.
>
> So directive protocol proposal: #directive_name returns the
> fully-qualified name of the directive''s attribute; #attribute_name
returns
> the simple attribute name, #namespace_name returns the namespace prefix
> qualifier.  Maybe deprecate the original #full_attr_name currently in
> DirectiveBase, would like to use method names that directly reflect XML
> namespace terminology for qnames.
>
> Believe we''ll also also need an override mechanism for namespaces
in the
> MV config options, just as xmlns markup allows the usage site to override
> the creator''s namespace in order to resolve namespace collisions
in their
> documents, but that would build on top of the basic facility.
>
> ~ Deb
>
>  ------------------------------
> *From:* Jeff Barczewski [mailto:jeff.barczewski at gmail.com]
> *Sent:* Monday, July 17, 2006 7:12 AM
> *To:* masterview-devel at rubyforge.org; djlewis at acm.org
> *Subject:* Another idea for the single file format for directives
>
> We could use an inner class to hold the description and examples
>
> class MyDirective
>   class MetaInfo
>      def description
>        ...
>      end
>
>      def example
>        ...
>      end
>
>   end
> end
>
> or even simply a Map to hold the pieces.
>
> Just other ideas to add to the list.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060718/05c6c330/attachment.html

Jeff - sounds like this is converging.  I think 2 files, one for the
directive impl that''s dropped into directives load path and one for
unit
tests, are needed.  Not good to introduce dependency on test environment in
the directive file itself, you want to be able to deploy app with just the
production code base.
 
If you''re competent enough to write a unit test (!), you can certainly
cope
with uploading two files rather than 1.
 
So - nitty detail: one MetaInfo class or 2, to separate doc/examples from
the runtime specification.  Maybe that''s just going overboard and 1 is
fine,
I waffle on how zealous to be on separating possible layers of code for that
sort of thing.
 
Whether to embed (include) the MI class or to have it as sibling class
located by convention based on directive class name maybe depends on whether
embedding will have the right characteristics if we bolt a degenerate guy
into DirectiveBase, I think.  Not sure we should put something in
DirectiveBase that pins down namespace_name=''mv'', because
that''s only
appropriate for our builtin guys, but not necesssarily custom directives.  
 
or maybe this is a place for a magic convenience decl notation implemented
in DirectiveBase that provides simple declarative notation for attr/ns name
and description:
 
   directive :attribute=>''coolthing'', :namespace =>
''myguys'', :description
=> ''One line summary of my cool thingy''
 
.. something like that (my coding fingers are  bit confused today hopping
between ruby, python, and smalltalk, ack).
 
And need to recheck the DirectoryRegistry loading magic to make sure
it''d do
the right thing if a file on the directives path has more than one class in
it (think it does, just don''t have that code up right this instant)
 
~ Deb
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060718/f3c22ffe/attachment-0001.html

Yes, the plugin loading registry thing simply require''s the files in
the
directory so it will load all the classes in there, not a problem there. By
having subclassed DirectiveBase we get informed of the directives as they
are defined no matter where they got required from or how (file, gem, etc).
So all the other meta classes would get parsed but since they don''t
subclass
DirectiveBase they don''t show up as loaded directives but can certainly
be
utilized. We could have a MetaInfoBase that they subclass if we wanted to
get all the directives that provide meta info using same mechanism.

If we used a DSL we could hide many of the complexities like you were
suggesting.

I think it is coming along here.


On 7/18/06, Deb Lewis <djlewis at acm.org> wrote:
>
>  Jeff - sounds like this is converging.  I think 2 files, one for the
> directive impl that''s dropped into directives load path and one
for unit
> tests, are needed.  Not good to introduce dependency on test environment in
> the directive file itself, you want to be able to deploy app with just the
> production code base.
>
> If you''re competent enough to write a unit test (!), you can
certainly
> cope with uploading two files rather than 1.
>
> So - nitty detail: one MetaInfo class or 2, to separate doc/examples from
> the runtime specification.  Maybe that''s just going overboard and
1 is fine,
> I waffle on how zealous to be on separating possible layers of code for
that
> sort of thing.
>
> Whether to embed (include) the MI class or to have it as sibling
> class located by convention based on directive class name maybe depends on
> whether embedding will have the right characteristics if we bolt a
> degenerate guy into DirectiveBase, I think.  Not sure we should put
> something in DirectiveBase that pins down
namespace_name=''mv'', because
> that''s only appropriate for our builtin guys, but not necesssarily
custom
> directives.
>
> or maybe this is a place for a magic convenience decl notation implemented
> in DirectiveBase that provides simple declarative notation for attr/ns name
> and description:
>
>    directive :attribute=>''coolthing'', :namespace =>
''myguys'', :description
> => ''One line summary of my cool thingy''
>
> .. something like that (my coding fingers are  bit confused today hopping
> between ruby, python, and smalltalk, ack).
>
> And need to recheck the DirectoryRegistry loading magic to make sure
it''d
> do the right thing if a file on the directives path has more than one class
> in it (think it does, just don''t have that code up right this
instant)
>
> ~ Deb
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/masterview-devel/attachments/20060718/51f4ec23/attachment.html