[cgi-wiki-dev] Formatter API change proposal

[Kjetil Kjernsmo]

On mandag 24 januar 2005, 19:26, Kake L Pugh wrote:
> This feels to me as though it's breaking the main strength of the
> whole idea of using Formatter instead of just using the underlying
> modules - a standard API. =A0Surely it would be best to have ->format
> act in the same way whichever Formatter module you were using? =A0If
> you can't rely on it to always return a document, or always return a
> fragment, then you lose the possibility of blithely swapping from one
> Formatter to another without making changes in the code.

Well, it is the whole reason why I started on this line of thought: I=20
need to rely on a function to do the right thing, so it is=20
swappable... :-)

You wouldn't loose anything, you can rely on ->document returning a=20
document and ->fragment returning a fragment, that's idea of the=20
current proposal anyway. ->format($string) initialises the formatter=20
and returns whatever, in the case where you don't care what you get.

I think the real controversy here is actually the problem Justin brought=20
up: That you can't always rely on a fragment being returned. I presume=20
that it is very rare that you can't rely on a document being returned,=20
but such situations might exist.

In the current proposal, I have turned to this problem and said that it=20
must return undef in these rare situations. However, I'm open to the=20
idea that the formatter must make a "best effort" to return a document=20
or fragment, also in the case where it is not clearly defined what the=20
document or fragment may be.

When pushed, I might even agree it is the most sensible thing to do, so=20
that the calling application wouldn't need to care about error=20
situations.=20

The problem with this approach is that the quality of the returned=20
matter is lower that you might expect, and you wouldn't discover it.=20
However, I guess it is not so much of a concern, since we'll mostly=20
work on syntaxes that aren't very rich to begin with. Most of the=20
matter is relatively crude, and the gain from not having to deal with=20
the error situations might be greater than the loss of predictability=20
as to what constitutes a fragment.


> How about you standardise that ->format will always return a
> fragment, and ->format_as_document will always return a document?

Well, that's a naming problem mostly... For one thing, the format method=20
is different, it takes the string to be converted as argument. To now=20
define that it should only return fragments would change its semantics=20
from previous version, admittedly with no effect, since all existing=20
=46ormatters return fragments.=20

That's why I felt defining two new methods would make more sense,=20
fragment and document will give you exactly what you need in terms of=20
swappability. The difficult point is what you should do in the case=20
where it is not completely clear what a fragment or document _is_.=20
Here, perhaps undef is not the Right Thing[tm] to return.

Another difficulty with ->format_as_document is that one would clearly=20
define if it should initialise like format do, or if one should call=20
=2D>format first and then ->format_as_document. And if you should call=20
either before calling things like ->links and ->title... I think I=20
prefer to have a single initialising method. In fact, I thought about=20
changing the constructor and drop the new(), but I decided against=20
that, to allow using parent's methods like ->charset, which is=20
something we may want to define too...=20

Great discussion!

Cheers,

Kjetil
=2D-=20
Kjetil Kjernsmo
Astrophysicist/IT Consultant/Skeptic/Ski-orienteer/Orienteer/Mountaineer
kjetil@kjernsmo.net  webmaster@skepsis.no  editor@learn-orienteering.org
Homepage: http://www.kjetil.kjernsmo.net/        OpenPGP KeyID: 6A6A0BBC