[cgi-wiki-dev] Formatter API change proposal

[Kjetil Kjernsmo]

--Boundary-00=_jWR9BYu8W94dEUZ
Content-Type: text/plain;
  charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

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
-- 
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

--Boundary-00=_jWR9BYu8W94dEUZ
Content-Type: text/plain;
  charset="iso-8859-1";
  name="Formatter-prop.pod"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
	filename="Formatter-prop.pod"

=head1 NAME

Formatter - The Formatter API specification

=head1 VERSION

0.9

=head1 SYNOPSIS

Formatters are Perl Modules conforming to the following
specification. Formatters are intended to assist the conversion
between different markup syntaxes.

=head1 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 C<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.


=head1 DESCRIPTION

=head2 Module naming convention

A Formatter module should be named with the format it is converted
B<to> first, then the format it is converted B<from>. For example, the
module L<Formatter::HTML::Textile> will convert from the Textile
syntax to HTML.


=head2 Methods

=over

=item C<new>

The constructor must be implemented, and return a reference C<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
C<format> will be sent.


=item C<format($string)>

This method shall initialize the formatter. As argument it must take a
string with the text that one wants converted.  The C<format> method
must allow the user to call C<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 C<document> and C<fragment> methods.

=item C<document>

The C<document> method may be called on the object after it has been
initialized with the C<format> method. It must return a full document
if it can be produced or C<undef> if not. For example, if it converts
to HTML, it must return a full, valid HTML document.

=item C<fragment>

The C<document> method may be called on the object after it has been
initialized with the C<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 C<body> element. If it is unable to produce just the minimal
markup, it must return C<undef>.

=item C<links>

This method may be called on the object after it has been initialized
with the C<format> method.  Should return all links found the input
plain text string as a list or an empty list if none can be found.

=item C<title>

This method may be called on the object after it has been initialized
with the C<format> method.  Should return the title of the document or
C<undef> if none can be found.

=back


=head2 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.

=head1 AUTHOR

Kjetil Kjernsmo, E<lt>kjetilk@cpan.orgE<gt>

=head1 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.

=head1 EXAMPLES

The module L<Formatter::HTML::Preformatted> contains a minimal
Formatter by the author of the specification.

=head1 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.

=cut

--Boundary-00=_jWR9BYu8W94dEUZ--