On mandag 24 januar 2005, 14:36, Kjetil Kjernsmo wrote:
I'll write up a specification like I envision it with fragment and document, plus some other stuff, and send that too in a moment.
Uhm, right. Here we go, this is my proposal for a draft (i.e. v0.9) of the Formatter API:
NAME Formatter - The Formatter API specification
VERSION 0.9
SYNOPSIS Formatters are Perl Modules conforming to the following specification. Formatters are intended to assist the conversion between different markup syntaxes.
INTRODUCTION The basic idea of Formatters is to have a simple and standard way to convert from one format to another. This is a common problem across many applications, and so, a simple API for all applications to use is desireable.
Formatters generally operate on strings. For example, you have a plain text string, possibly with a bit of syntax, and you want to convert it to HTML. You will simply use the appropriate Formatter module, and call the "format" method on it, with the text string as parameter. The HTML will be returned.
In many cases, the Formatter will be a thin wrapper around a different module which does the hard work.
DESCRIPTION Module naming convention A Formatter module should be named with the format it is converted to first, then the format it is converted from. For example, the module Formatter::HTML::Textile will convert from the Textile syntax to HTML.
Methods "new" The constructor must be implemented, and return a reference "bless"ed into this class. There are no other requirements on the constructor, but implementors will find it useful to have a field for the string "format" will be sent.
"format($string)" This method shall initialize the formatter. As argument it must take a string with the text that one wants converted. The "format" method must allow the user to call "format" on the class name, and call the constructor implicitly in that case.
This method must return the converted string. It is however free to return a document fragment or a full document based on what is most appropriate for the module. See the "document" and "fragment" methods.
"document" The "document" method may be called on the object after it has been initialized with the "format" method. It must return a full document if it can be produced or "undef" if not. For example, if it converts to HTML, it must return a full, valid HTML document.
"fragment" The "document" method may be called on the object after it has been initialized with the "format" method. It shall only return a minimal fragment of the converted text, as little as possible markup shall be added to the fragment. In the example of HTML, it must not return a full document, and should only produce markup that can be inserted in a HTML "body" element. If it is unable to produce just the minimal markup, it must return "undef".
"links" This method may be called on the object after it has been initialized with the "format" method. Should return all links found the input plain text string as a list or an empty list if none can be found.
"title" This method may be called on the object after it has been initialized with the "format" method. Should return the title of the document or "undef" if none can be found.
Inheritance from other modules A Formatter module may inherit methods from other modules. It may inherit all the methods mentioned above if they exist in a suitable parent class, and also other methods, to aid setting syntax-specific parameters.
Formatter module implementors are encouraged to contact the API author(s) to discuss methods that should be included in the API.
AUTHOR Kjetil Kjernsmo, kjetilk@cpan.org
ACKNOWLEDGEMENTS The Formatter API was originally conceived on the openguides channel on irc.perl.org. In particular, Tom Insam was an important architect of the API.
EXAMPLES The module Formatter::HTML::Preformatted contains a minimal Formatter by the author of the specification.
COPYRIGHT AND LICENSE Copyright (C) 2005 by Kjetil Kjernsmo
This specification can be redistributed it and/or modified it under the same terms as Perl itself. The author asks that only modules conformant with the specification uses the Formatter:: namespace.
So, how does that sound?
Cheers,
Kjetil