[cgi-wiki-dev] Formatter API change proposal

Tue, 25 Jan 2005 13:30:17 +0100

On tirsdag 25 januar 2005, 10:35, Kake L Pugh wrote:
> Ahh, I get it now. =A0It's not clear from the name that ->format does
> initialisation and leaves things behind in the formatter for
> ->document and ->fragment to act on.

Yup, it is not quite clear.

> It also seems possible that the ability to return a fragment rather
> than a document (or vice versa) could depend on the input as well as
> the class of the formatter.

Hmmm, it could, there are many unknowns when you try to create something=20
that is supposed to work over a wide array of things... But I suspect=20
that usually you can smack something around any string to get a whole=20
document...=20

> And it feels wrong to me that information about the last input is
> stored in the formatter. =A0If you want to format something else before
> you're done with the last thing, either the work is lost or you need
> to create a new formatter, and that feels very wrong.

Hmmm, I didn't understand that...

If you format $foo->format("the *foo* of bar") you can always call=20
$foo->title anywhere, so there is nothing lost there. If OTOH you want=20
to $baz->format("barring _foo_"), yes you should create a new object, I=20
see that as a good thing. Nothing is lost since all the hard work must=20
be done separately for each string anyway. I think I learnt something=20
about this in OO class a while ago... :-)

> Finally, it seems that there really should be some _programmatic_ way
> to find out whether we can get a fragment (or a document) back from
> our input.

Hm, well, that was the idea with requiring that it should return undef=20
if it couldn't return what we wanted, you could check the return value,=20
like...:

> With those points in mind, how about we change ->format to ->parse,
> and return an object:
>
> =A0 my $parsed =3D $formatter->parse( $string );
> =A0 if ( $parsed->can( "document" ) ) {
> =A0 =A0 =A0 print $parsed->as_document;
> =A0 } else {
> =A0 =A0 =A0 print "<html><head><title>My Doc</title></head><body>",
> =A0 =A0 =A0 =A0 =A0 =A0 $parsed->as_fragment, "</body></html";
> =A0 }

 =A0 my $formatter =3D Formatter::Foo::Bar->format( $string );
 =A0 if ( $formatter->document ) {
 =A0 =A0 =A0 print $formatter->document;
 =A0 } else {
 =A0 =A0 =A0 print "<html><head><title>My Doc</title></head><body>",
 =A0 =A0 =A0 =A0 =A0 =A0 $formatter->fragment, "</body></html";
 =A0 }

While some way to find the capabilities of a formatter is nice, I can't=20
really see any advantage to is in this case.=20

But then, when we started discussing this, I realized that it would be=20
better just to demand that when you call $formatter->document; you're=20
done, you can trust that you'll get something. It may not be the best,=20
but it is something you can use. To take the worries off of the user.=20

> This allows expansion of the API like so:
>
> =A0 if ( $parsed->can( "interwiki_links" ) ) {
> =A0 =A0 @links =3D $parsed->interwiki_links;
> =A0 }

Yup. Well, I agree that something to check capabilities of the object is=20
useful, but only in the cases where it is much more expensive to just=20
do it than find out if we have a capability. I suspect that in most=20
cases here, it'll be pretty cheap to find the links, so testing on=20
$formatter->interwiki_links would be sufficient. Formatters that know=20
they do expensive operations can cache their result transparently.

> $parsed would be of class something like Formatter::Parsed::UseMod.

That would be a pretty radical departure from the architecture we are=20
aiming at, which is a simple Formatter::To::From between formats. And=20
I'm sort of running out on time... :-(

> The way this fits in with Wiki::Toolkit is that when a node is
> created, its content is parsed by a Formatter, and the $parsed object
> is stored in the node object.

OK!

I've been discussing with jerakeen offlist, and what we have come to is=20
to drop the new method, make format the constructor, which returns the=20
object, not the string. Then, the document and fragment methods return=20
the strings. OK?

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