/ 
HTML-BBReverse-0.04
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.

And why would you want to reverse the generated HTML? Well, when you have a nice dynamic website where you and/or visitors can post messages, and in those messages BBCode is used for markup. In normal cases, your website has a lot more pageviews than edits, and saving all those messages as HTML will be a lot faster than saving them as the original BBCode and parsing them to HTML for every visit.

So now all BBCode gets converted to HTML before it will be saved, but what if you want to edit a message? Just reverse the generated HTML back to BBCode, edit your message, and save it as HTML again.

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. Defaults to 1.

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) Defaults to 0.

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

Which will generate the following HTML:

[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://dev.yorhel.nl/HTML-BBReverse/, http://www.phpbb.com/phpBB/faq.php?mode=bbcode, HTML::BBCode, BBCode::Parser

CAVEATS

Laziness

HTML::BBReverse is a lazy module, which simply means it does not check any syntax, and just converts any BBCode to HTML (or back), even when the input contains errors like wrong nested tags or even close tags without start tags or start tags without close tags. Therefore, wrong input means wrong output. Note though that reversing HTML which is generated with parse with 'wrong' BBCode as input, should still give the same 'wrong' BBCode as output.

Lists formatting

The space between a code start tag ([code]) and the first item ([*]) will be completely ignored, and replaced with a linebreak. For example: When you parse

[list]some
text or [b]bbcode[/b]
here[*]item[/list]

to HTML, and reverse it back to BBCode, it will give the following output:

[list]
[*]item[/list]

This 'feature' (some might call it a bug) is added because it is not allowed to have content between <ul> and the first <li> in (X)HTML.

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.

TODO

HTML::BBReverse is still in development, and new functions will probably be added.

html-tag

A BBCode tag which allows people to insert raw HTML between [html] and [/html] tags.

Syntax checking

An extra method which checks the syntax of BBCode and maybe the generated HTML, and an option to new where you can configure wether the syntax should be checked before a parse of reverse, and what to do if there is a syntax error.

And of course HTML::BBReverse needs a little more testing and bugfixes before it will be considered as stable.

AUTHOR

Y. Heling, <yorhel@cpan.org>

CREDITS

I would like to thank the following people:

  • Thijs Wijnmaalen for helping to refine the idea

  • M. Blom for pointing out some bugs

  • Elsbeth Dokter for giving mental support

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.