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. Surely it would be best to have ->format act in the same way whichever Formatter module you were using? If 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 need to rely on a function to do the right thing, so it is swappable... :-)
You wouldn't loose anything, you can rely on ->document returning a document and ->fragment returning a fragment, that's idea of the current proposal anyway. ->format($string) initialises the formatter 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 up: That you can't always rely on a fragment being returned. I presume that it is very rare that you can't rely on a document being returned, but such situations might exist.
In the current proposal, I have turned to this problem and said that it must return undef in these rare situations. However, I'm open to the idea that the formatter must make a "best effort" to return a document or fragment, also in the case where it is not clearly defined what the document or fragment may be.
When pushed, I might even agree it is the most sensible thing to do, so that the calling application wouldn't need to care about error situations.
The problem with this approach is that the quality of the returned matter is lower that you might expect, and you wouldn't discover it. However, I guess it is not so much of a concern, since we'll mostly work on syntaxes that aren't very rich to begin with. Most of the matter is relatively crude, and the gain from not having to deal with the error situations might be greater than the loss of predictability 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 is different, it takes the string to be converted as argument. To now define that it should only return fragments would change its semantics from previous version, admittedly with no effect, since all existing Formatters return fragments.
That's why I felt defining two new methods would make more sense, fragment and document will give you exactly what you need in terms of swappability. The difficult point is what you should do in the case where it is not completely clear what a fragment or document _is_. Here, perhaps undef is not the Right Thing[tm] to return.
Another difficulty with ->format_as_document is that one would clearly define if it should initialise like format do, or if one should call ->format first and then ->format_as_document. And if you should call either before calling things like ->links and ->title... I think I prefer to have a single initialising method. In fact, I thought about changing the constructor and drop the new(), but I decided against that, to allow using parent's methods like ->charset, which is something we may want to define too...
Great discussion!
Cheers,
Kjetil