view release on metacpan or  search on metacpan

lib/BBCode/Parser.pm  view on Meta::CPAN

=head1 NAME

BBCode::Parser - Parses BBCode tags

=head1 DESCRIPTION

BBCode is a simplified markup language used in several online forums
and bulletin boards.  It originated with phpBB, and remains most popular
among applications written in PHP.  Generally, users author their posts in
BBCode, and the forum converts it to a permitted subset of well-formed HTML.

C<BBCode::Parser> is a proper recursive parser for BBCode-formatted text.

=head1 OVERVIEW

A C<BBCode::Parser> object stores various settings that affect the parsing
process.  Simple settings are typically set when the parser is created using
L<new()|/"new">, but they can be queried using L<get()|/"get"> and altered
using L<set()|/"set">.

See L</"SETTINGS"> for more information.

In addition to the simple settings, specific BBCode tags (or classes of tags)
can be permitted or forbidden, using L<permit()|/"permit"> and
L<forbid()|/"forbid"> respectively.  By default, the only forbidden tag is
C<[HTML]>, which is normally a security violation if permitted.

See L</"CLASSES"> for a list of tag classes.

Once the parser has been configured appropriately, parse trees can be created
using the L<parse()|/"parse"> method.  The parse tree will consist of objects
derived from L<BBCode::Tag|BBCode::Tag>; the root of the tree will be a
L<BBCode::Body|BBCode::Body> object.

Converting the parse tree to HTML is quite simple: call L<toHTML()|BBCode::Tag/"toHTML">
on the root of the tree.  Likewise, the parse tree can be converted back to
BBCode by calling L<toBBCode()|BBCode::Tag/"toBBCode">.  See
L<"METHODS" in BBCode::Tag|BBCode::Tag/"METHODS"> to find out what other
output methods are available.

=head1 SETTINGS

The following settings can be manipulated using L<get()|/"get"> and L<set()|/"set">.

=over

=item css_prefix

(Type: String; Default: "bbcode-")

Many BBCode tags will add CSS classes as style hooks in the output HTML, such
as C<< <div class="bbcode-quote">...</div> >>.  This setting allows you to
override the naming scheme for those hooks.  At the moment, more direct control
of the CSS class names is not available.

=item css_direct_styles

(Type: Boolean; Default: FALSE)

Certain style-related BBCode tags, such as [U] (underline) and [S]
(strike-through) don't have a direct equivalent in modern XHTML 1.0 Strict.
If this value is TRUE, then the generated HTML will use a C<style> attribute
on a C<E<lt>spanE<gt>> tag to simulate the effects.  If this value is FALSE,
then the style attribute will be omitted.  In either case, a C<class> attribute
is provided for use as a hook by external CSS stylesheets (not provided).

=item follow_links

(Type: Boolean; Default: FALSE)

To prevent blog spam and the like, many search engines now allow HTML authors
to indicate that specific URLs on a page should not be indexed.  If this value
is TRUE, then there will be nothing special about the URL (meaning that search
engines are encouraged to follow the link).  If this value is FALSE, then a
C<rel="nofollow"> attribute will be added wherever it makes sense (warning
search engines that the link might be spam).

Whether or not to set this value to TRUE will depend on what you're using
C<BBCode::Parser> for.  If you're implementing a forum or bulletin board, TRUE
might be reserved for senior, more trusted members.  If you're implementing a
blog, the value might be TRUE for the blog owner but FALSE for visitors.

For more information, see L<http://www.google.com/webmasters/bot.html#www>.

(If you turn this setting on, C<follow_override> behaves as if it were on as
well.  That way, users can explicitly mark links with C<FOLLOW=0> if
necessary.)

=item follow_override

(Type: Boolean; Default: FALSE)

This BBCode implementation allows a user to override C<follow_links> using a
BBCode extension, the C<FOLLOW> parameter.  If this value is TRUE, the user
can override C<follow_links> with C<FOLLOW=1>; otherwise, the user must abide
by C<follow_links>.

(However, a user can always specify C<FOLLOW=0> regardless of this setting.
If the user posting the link doesn't think the link is trustworthy, it's
obviously not trustworthy.)

The same considerations that apply to C<follow_links> also apply to this
setting.

=item newwindow_links

(Type: Boolean; Default: FALSE)

For reasons largely having to do with site aesthetics, some site owners prefer
for external links to each open in a new window using C<E<lt>a target="_blank"E<gt>>.
For reasons largely having to do with browsing experience, some users prefer
to summarily execute the aforementioned site owners in the most painful manner
available.  If you turn this option on, you will anger and frustrate people
who suddenly find that their back buttons and/or tabs don't work right when
they visit your site.  Please take due consideration of that before setting
this option to a TRUE value and taking choices away from the people reading
your website.

=item newwindow_override

(Type: Boolean; Default: FALSE)