/ 
HTML-BBReverse-0.01
River stage zero No dependents
/ HTML::BBReverse

NAME

HTML::BBReverse - Perl module to convert HTML to BBCode and back

SYNOPSIS

use HTML::BBReverse

my $bbr = HTML::BBReverse->new();

# convert BBCode into HTML
my $html = $bbr->parse($bbcode);
# convert generated HTML back to BBCode
my $bbcode = $bbr->reverse($html);

DESCRIPTION

HTML::BBReverse is a pure perl module for converting BBCode to HTML and is able to convert the generated HTML back to BBCode.

METHODS

The following methods can be used

new

my $bbr = HTML::BBReverse->new(
  allowed_tags => [ qw( b i u code url size color img quote list email ) ],
  reverse_for_edit => 1,
  in_paragraph => 0,
);

new creates a new HTML::BBReverse object using the configuration passed to it.

options

The following options can be passed to new:

allowed_tags

Specifies which BBCode tags will be parsed, for the current supported tags, see the list of supported tags below. Defaults to all supported tags.

reverse_for_edit

When set to a positive value, the reverse method will parse &, > and < to their HTML entity equivalent. This option is useful when reversing HTML to BBCode for editing in a browser, in a normal textarea. When set to zero, the reverse method should just ignore these characters.

in_paragraph

Specifies wether the generated HTML is used between HTML paragraphs (<p> and </p>), and adds a </p> in front of and a <p> after every list. (XHTML 1.0 strict document types do not allow lists in paragraphs)

parse

Parses BBCode text supplied as a single scalar string and returns the HTML as a single scalar string.

reverse

Parses HTML generated from parse supplied as a single scalar string and returns BBCode as a single scalar string. Note that this method can only be used to reverse HTML generated by the parse method of this module, it won't be able to parse just any HTML to BBCode

SUPPORTED TAGS

The following BBCode tags are supported:

b, i, u, img, url, size, color, quote, list, email

Which will generate the following HTML:

Input                              Output

[b]bold[/b]                        <b>bold</b>
[i]italic[/i]                      <i>italic</i>
[u]underlined[/u]                  <span style="text-decoration: underline">underlined</span><!--1-->
[img]pic.png[/img]                 <img src="pic.png" alt="" />
[img=pic.png]desc[/img]            <img src="pic.png" alt="desc" title="desc" />
[url=/file]desc[/url]              <a href="/file">desc</a>
[size=20]text[/size]               <span style="font-size: 20px">text</span><!--2-->
[color=red]text[/color]            <span style="color: red">text</span><!--3-->
[quote]some quote[/quote]          <span class="bbcode_quote_header">Quote: <span class="bbcode_quote_body">some quote</span></span>
[quote=author]some quote[/quote]   <span class="bbcode_quote_header">author wrote: <span class="bbcode_quote_body">some quote</span></span>
[code]some code[/code]             <span class="bbcode_code_header">Code: <span class="bbcode_code_body">some code</span> </span>
[email]some@mail.addr[/email]      <a href="mailto:some@mail.addr">some@mail.addr</a>

Note the <!--x--> after some HTML close tags, these are used by the reverse method, to see the difference between HTML close tags which are the same, while the BBCode equivalent is not the same.

SEE ALSO

http://www.phpbb.com/phpBB/faq.php?mode=bbcode

KNOWN BUGS

This module does contain a few bugs, if you find another bug not listed here, please contact the author.

Multiple lists on one line

When there are two [list]-tags on one line, the first tag will be completely ignored, for example:

[list][*]item 1[*]item 2[/list][list]
[*]another item[/list]

Will be parsed to:

[list][*]item 1[*]item 2[/list]<ul>
<li>another item</li></ul>

Note that the generated HTML will still be reversed to the original BBCode. The best solution to this bug is just to add a linebreak after every list tag, this bug will probably be fixed in future versions of HTML::BBReverse.

Lists formatting

The space between a code start tag ([code]) and the first item ([*]) will be completely ignored, and replaced with a linebreak. This bug will probably not be fixed.

AUTHOR

Y. Heling, <yorhel@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Y. Heling

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.