Development discussion for the docutils project

Felix Wiemann | 9 Mar 2006 23:12

Refactoring the directive interface

(FYI, David and I have talked at PyCon about refactoring the directive
interface towards a more OO-oriented approach.)

I've created a directives branch::

    svn diff svn+ssh://svn.berlios.de/svnroot/repos/docutils/branches/directives -r4375:HEAD

I have added a "parsers.rst.Directive" base class on the "directives"
branch.  I didn't want to call it "parsers.rst.directives.Directive,
because I have the notion that the directives themselves are extensions
to reStructuredText (which just happen to be shipped with core Docutils)
and thus logically belong into a separate directory, whereas the
"Directive" interface is an extension point [1]_ which belongs to the
core of the reST parser.  After all, states.py knows about that
interface.

David, could you please have a look at the code?  If you think it's OK,
I'll refactor the rest of the directives.

.. [1] The term "extension point" is mentioned here:
   http://www.acmqueue.org/modules.php?name=Content&pa=showpage&pid=286

--

-- 
For private mail please ensure that the header contains 'Felix Wiemann'.

"the number of contributors [...] is strongly and inversely correlated with the
number of hoops each project makes a contributing user go through."      -- ESR

-------------------------------------------------------
This SF.Net email is sponsored by xPML, a groundbreaking scripting language

(Continue reading)

headers

David Goodger | 9 Mar 2006 23:30

Re: Refactoring the directive interface

[Felix Wiemann]
> I have added a "parsers.rst.Directive" base class on the
> "directives" branch.  I didn't want to call it
> "parsers.rst.directives.Directive,
...

I thought about that too; your choice seems fine to me.

> David, could you please have a look at the code?  If you think it's
> OK, I'll refactor the rest of the directives.

The refactored directive looks fine.  So far it's just moving the code
out of a "directive" function into the Directive.run method, and
adding "self." as appropriate, right?

The modified docutils.rst.states.Body.parse_directive_block doesn't
support the new required_arguments, optional_arguments, &
final_argument_whitespace attributes yet though.  I'm sure you would
have discovered this quickly 

--

-- 
David Goodger <http://python.net/~goodger>

headers

Felix Wiemann | 10 Mar 2006 16:24

Re: Refactoring the directive interface

David Goodger writes:

> So far it's just moving the code out of a "directive" function into
> the Directive.run method, and adding "self." as appropriate, right?

Basically yes, but usually there's a bit more to do because the directive
functions call each other -- e.g. all the admonitions.  Or the sidebar
implementation calls the topic directive with node_class=nodes.sidebar.

I do not try to *mechanically* refactor those because the resulting code
probably would not make sense at all in OOP terms; instead I map these
dependencies between functions into simple class hierarchies.

I still don't change the inner working of the functions, though, e.g. by
factoring out all the error checking code.  IMO that can and should be
done later.

--

-- 
Felix Wiemann -- http://www.ososo.de/

-------------------------------------------------------
This SF.Net email is sponsored by xPML, a groundbreaking scripting language
that extends applications into web and mobile media. Attend the live webcast
and join the prime developer group breaking into this new coding territory!
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642