Make Creole Dialects More Modular

[GoogleCodeExporter]

When creating a dialectical variant of dialects.Creole10, one has to
subclass Creale10, super the __init__ and then redefine potentially lots
attributes other than just exactly what one wants to override.

In an effort to make the creation of dialects as painless as possible, I
offer the following API-compatible suggestion:

 1. Create a tokens dictionary where all basic (non-composite) markup will
be defined.
 2. For each attribute that is currently set in Creole10.__init__, create a
separate method for easy overriding.
 3. Ensure that each method that sets up a basic piece of markup uses the
token dictionary.
 4. Rewrite Creole10.__init__ to set attributes by calling each of these
methods.
 5. Ensure that __init__takes a tokens dictionary as a parameter, using the
new creaol10 tokens dictionary as the default.

This will allow the following:

 * When a user wants to simply redefine a single markup token, all they
need to do is import the tokens dictionary, update the key for the token
they want redefined, and instantiate Creole10 with their new dictionary.
 * When a user wants to keep the token but change the way that Creole10
treats that token, all they need to do is subclass Creole10 and override
the method responsible for that treatment.
 * When a user wants easy access to the all tokens defined by a given
dialect, all they need to do is inspect the token dictionary.

This last option is important, as it could provide the means by which wiki
text is stripped of markup.

Original issue reported on code.google.com by duncan.m...@gmail.com on 5 Nov 2008 at 11:13

[GoogleCodeExporter]

I put this as a high-priority item because this is a feature that we would need 
for
future use of Creole at Canonical. In addition, it blocks ticket #13.

Original comment by duncan.m...@gmail.com on 5 Nov 2008 at 11:20

[GoogleCodeExporter]

Oh, one more thing: before I start work on this, I want to finish the new unit 
test
framework. This new feature will use it :-)

Original comment by duncan.m...@gmail.com on 5 Nov 2008 at 11:25

[GoogleCodeExporter]

Creole10 was really never meant to be subclassed. My idea was that when a new 
version 
of Creole came along (or someone needed to make significant customizations) a 
new 
class should be created (i.e., Creole20). Hopefully the new class would be able 
reuse 
the rest of the library without too much trouble.

Of course this approach isn't very OO, and I agree that the Creole10 class 
needs 
work, so go for it :)

Some other ideas:

Do you think it would be better to have a Croele10 and Creole10WithAdditions 
class 
that subclasses a Creole class?

Or maybe just a Creole10 class that is subclassed by Creole10WithAdditions....

Original comment by stephen....@gmail.com on 5 Nov 2008 at 11:57

[GoogleCodeExporter]

What I have in mind is creating a base class which Creole10 will subclass. Any 
future
methods or attributes that are added and are likely to be generally useful can 
be put
on the base class, since such additions won't break backwards compatibility.

Any changes to methods in the base class (and therefore, implicitly, the 
Creole10
class) will need to be made in Creole20 (or whatever version number is 
applicable).

What I mean to say by all that is that the essence of your original plan remains
intact and pertinent with the changes I have in mind :-)

For right now, I see something along the following lines:
  dialects.BaseDialect
  dialects.Creole10
  tokens.base (a dict)
  tokens.creole10 (also a dict)

In the event that there are more than a few dialects bundled, I could see the 
need to
create a dialect sub-package, with modules for each dialect:
  dialect.base.BaseDialect
  dialect.base.tokens
  dialect.creole.Creole10
  dialect.creole.tokens10
  dialect.creole.Creole20
  dialect.creole.tokens20
  dialect.moinmoin.MoinMoin
  dialect.moinmoin.tokens

(I switched to a singluer package name, since that's a more common convention.)

But I don't think that will be necessary for a while ;-)

Original comment by duncan.m...@gmail.com on 6 Nov 2008 at 7:02

[GoogleCodeExporter]

I like your plan. 

If it makes sense, consider removing the 'use_additions' parameter from the 
__init__
method in favor of the following: 

  dialects.BaseDialect
  dialects.Creole10
  dialects.Creole10Plus <-- perhaps not needed
  tokens.base
  tokens.creole10
  tokens.creole10Plus

'use_additions' may still be needed, but I think a lot of what it is doing 
could be
better handled by creating a separate (sub)class and/or a separate tokens dict.

Also, try and put the macro functionality in the base class. (Even though the 
Creole
spec doesn't include it). 

Original comment by stephen....@gmail.com on 6 Nov 2008 at 2:35

[GoogleCodeExporter]

I've made some significant progress on this and delivered to the trunk. Still 
needs 
some work but I'm planning a release within 2 weeks. 

Original comment by stephen....@gmail.com on 21 Feb 2009 at 4:26

[GoogleCodeExporter]

Original comment by stephen....@gmail.com on 27 Feb 2009 at 2:34

• Changed state: Fixed