HTML::BBReverse - Perl module to convert HTML to BBCode and back
This document describes version 0.06 of HTML::BBReverse, released 2006-02-15.
This module is still beta, but should work as expected.
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);
HTML::BBReverse is a pure perl module for converting BBCode to HTML and is able to convert the generated HTML back to BBCode.
HTML::BBReverse
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.
The following methods can be used
my $bbr = HTML::BBReverse->new( allowed_tags => [ qw( b i u code url size color img quote list email html ) ], reverse_for_edit => 1, in_paragraph => 0, no_jslink => 1, );
new creates a new HTML::BBReverse object using the configuration passed to it.
new
The following options can be passed to new:
Specifies which BBCode tags will be parsed, for the current supported tags, see the list of supported tags below. Defaults to all supported tags.
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.
reverse
&
>
<
textarea
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.
<p>
</p>
When true, URLs starting with javascript: will be disabled for the [url] and [img] tags. Enabled by default.
javascript:
[url]
[img]
Parses BBCode text supplied as a single scalar string and returns the HTML as a single scalar string. See Supported tags below for the supported tags and their usage.
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
parse
The following BBCode tags are supported:
Standard markup tags, any text between [b] and [/b] will be bold, text between [i] and [/i] will be italic and text between [u] and [/u] will be underlined. For example:
[b]
[/b]
[i]
[/i]
[u]
[/u]
[i]italic[/i] [b]bold[/b] [u]underlined[/u]
Will be parsed to:
<i>italic</i> <b>bold</b> <span style="text-decoration: underline">underlined</span>
Note that the HTML <u> and </u> tags are not used for underlining, this is because they are deprecated and not allowed in XHTML 1.0 Strict.
<u>
</u>
Adds an image, can be used in two ways, one for an image without description and one for an image with description. For example:
[img]/path/to/image.jpg[/img] [img=image.jpg]description[/img]
<img src="/path/to/image.jpg" alt="" /> <img src="image.jpg" alt="description" title="description" />
The description should be a small one-line description of the image.
Used to quote someone (or something), syntax is similar to the img tag. Optional argument specifies the quoted author. For example:
img
[quote]Who said this?[/quote] [quote=Bill Gates] The great thing about a computer notebook is that no matter how much you stuff into it, it doesn't get bigger or heavier. [/quote]
<span class="bbcode_quote_header">Quote: <span class="bbcode_quote_body">Who said this?</span></span> <span class="bbcode_quote_header">Bill Gates wrote: <span class="bbcode_quote_body"> The great thing about a computer notebook is that no matter how much you stuff into it, it doesn't get bigger or heavier. </span></span>
[url=/some/url]link text[/url]
Creates a clickable link, argument is required. The above example will generate the following HTML:
<a href="/some/url">link text</a>
[email]email@example.org[/email]
Creates a clickable mailto: link. The above example will generate the following HTML:
mailto:
<a href="mailto:email@example.org"> email@example.org</a>
[size=30]huge[/size]
The size tag controls the size of the text in pixels. The above example will generate the following HTML:
size
<span style="font-size: 30px">huge</span><!--2-->
Note the <!--2-->, this HTML-comment is added for reverse to see the difference between the same end-tags.
<!--2-->
[color=red]Red[/color]
Changes the color of the text, the color can be in any acceptable HTML-format: color-names or hex-codes (preceded with a #). The above example will generate the following HTML:
#
<span style="color: red">Red</span><!--3-->
The list tag can be used to create lists of various types. Between the [list] and [/list] tags can the special [*] tag be used to specify an item. The [list] tag itself accepts one optional argument to specify the style of the list, which can be one of the following:
list
[list]
[/list]
[*]
[list] normal, dotted, list [list=1] numbered list [list=a] alphabetic list
For example:
[list] [*]item 1 [*]item 2 [/list]
Will generate a simple dotted list, created with the following HTML:
<ul> <li>item 1<br /> </li><li>item 2<br /> </ul>
Note that anything between the [list] tag and the first item will be ignored and replaced with a newline (\n).
\n
The code tag can be used to insert code, anything between the [code] and [/code] tags will be ignored, For example:
code
[code]
[/code]
[code] [b]This isn't bold text[/b] [/code]
<span class="bbcode_code_header">Code: <span class="bbcode_code_body"><br /> [b]This isn't bold text[/b] </span> </span>
The html tag can be used to insert raw html, anything between the [html] and [/html] tags will be treated as HTML and will not be parsed. For example:
html
[html]
[/html]
[html] And this is <b>raw</b> HTML :) [/html]
<!--BB-html--> And this is <b>raw</b> HTML :) <!--/BB-html-->
Note the <!--BB-html--> and <!--/BB-html--> tags, these are used by reverse to determine what should be treated as HTML.
<!--BB-html-->
<!--/BB-html-->
All tags (except of course code and html) can be nested, please note though that wrong nested BBCode will not automatically be corrected, and will generate wrong HTML. See Caveats below.
http://dev.yorhel.nl/HTML-BBReverse/, http://www.phpbb.com/phpBB/faq.php?mode=bbcode, HTML::BBCode, BBCode::Parser
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.
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.
<ul>
<li>
No known bugs, but that doesn't mean there aren't any. If you find a bug please report it at http://rt.cpan.org/Public/Dist/Display.html?Name=HTML-BBReverse or contact the author.
HTML::BBReverse is still in development, and new functions will probably be added.
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.
An extra option to new which specifies wether parse should automatically parse URLs and e-mail addresses to clickable links.
If you think of a useful feature which you would like to see in HTML::BBCode, just contact the author!
HTML::BBCode
Of course HTML::BBReverse also needs a little more testing and bugfixes before it will be considered stable.
Y. Heling, <yorhel@cpan.org>, (http://www.yorhel.nl/)
I would like to thank the following people:
Thijs Wijnmaalen (http://thijs.wijnmaalen.name/) for helping to refine the idea
M. Blom for pointing out some bugs
Copyright (C) 2005-2006 by Y. Heling
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install HTML::BBReverse, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::BBReverse
CPAN shell
perl -MCPAN -e shell install HTML::BBReverse
For more information on module installation, please visit the detailed CPAN module installation guide.