HTML::SBC - simple blog code for valid (X)HTML
Version 0.15
use HTML::SBC; my $translator = HTML::SBC->new(); my $html = $translator->sbc($text);
or with vintage interface:
use HTML::SBC qw(sbc_translate); my $html = sbc_translate($text);
Simple Blog Code is a simple markup language. You can use it for guest books, blogs, wikis, boards and various other web applications. It produces valid and semantic (X)HTML from input and is patterned on that tiny usenet markups like *bold* and _underline_. See language description for details.
HTML::SBC tries to give useful error messages and guess the right translation even with invalid input. It will always produce valid (X)HTML.
HTML::SBC now (since 0.10) uses an OO interface, but the old interface is still available. See "Vintage interface" for details.
my $translator = HTML::SBC->new()
creates a translator with english language for error messages. Additionally, you can set initial values for all attributes, e. g.:
my $translator = HTML::SBC->new({ language => 'german', image_support => 1, error_callback => sub { print "<li>$_[0]</li>\n"; }, linkcheck_callback => sub { return $_[0] =~ m{archive}; }, imgcheck_callback => sub { return $_[0] =~ m{naked\d{4}\,jpg}; }, });
For the meaning of the attributes, see the accessor documentations below. Note: the arguments for new are passed in a hashref.
new
Accessor method for the language field. It defines the language of your error messages. All accessors are both setter and getter:
language
$language = $translator->language(); $translator->language($new_language);
Valid languages: 'english' (default), 'german'.
Accessor method for the image_support field. It defines whether image code is parsed or not. Image markup is translated if and only if this field has a true value, so for this field all values are valid.
image_support
Accessor method for the error_callback field. The error_callback callback is called on every error that occurs while parsing your SBC input. It gets the error message as first argument and a reference to the translator object as second argument. Valid values are: undef, coderefs.
error_callback
Accessor method for the linkcheck_callback field. The <linkcheck_callback> callback is called if there is hyperlink markup in your SBC input. It gets the URL as first argument and has to return a true value if that URL is considered valid, false otherwise. Valid values are: undef, coderefs.
linkcheck_callback
Accessor method for the imgcheck_callback field. The <imgcheck_callback> callback is called if there is image markup in your SBC input. It gets the URL as first argument and has to return a true value if that URL is considered valid, false otherwise. Valid values are: undef, coderefs.
imgcheck_callback
my $html = $translator->sbc($text);
Returns some valid HTML block elements which represent the given SBC $text.
$text
my $line = $translator->sbc_inline($text);
Returns some valid HTML inline content which represents the given SBC $text. $text may only contain inline SBC markup.
After translation you can look for errors in your SBC input:
my @errors = $translator->errors();
returns a list of warnings/errors in the chosen language.
while (my $error = $translator->next_error()) { do_something_with($error); }
Implements an iterator interface to your error messages. It will return the next error message or undef if there's nothing left.
Remember the possibility to use your own error callback method.
There are some SBC tools implemented as class methods.
my $reply = HTML::SBC->quote($original);
If you have some text in simple blog code $original and you want it to be sbc-quoted (e. g. for reply functionality in boards). You can add the author's name as second argument:
$original
my $reply = HTML::SBC->quote($original, $author);
my $plain = HTML::SBC->remove_hyperlinks($sbc);
This class methods strips any hyperlink urls from given sbc input. It is often used for search scripts which usually don't want to search within urls. It also removes image markup.
my $description = HTML::SBC->description('german');
If you want some newbies to use SBC, just show them our SBC language description in your favourite language (english is default).
For backward compatibility, HTML::SBC implements its vintage non-OO interface (versions < 0.10) so you can use newer versions of HTML::SBC without any changes in your source code, for example:
use HTML::SBC qw( sbc_translate ); HTML::SBC::german(); my ($html, $errors) = sbc_translate($text); print "$_\n" for @$errors;
To import this vintage interface,
use HTML::SBC qw( sbc_translate sbc_description );
or import everything (except language getter):
use HTML::SBC qw( :vintage );
HTML::SBC::english() sets the language of your error messages to english.
HTML::SBC::english()
HTML::SBC::german() sets the language of your error messages to german.
HTML::SBC::german()
my ($html, $errors) = sbc_translate($text);
sbc_translate() returns the html output and an arrayref to your error messages. To ignore the errors, just evaluate sbc_translate() in scalar context.
sbc_translate()
my ($inline_html, $errors) = sbc_translate_inline($inline_text);
does the same with inline content (see sbc_inline).
sbc_inline
my $reply = sbc_quote($original);
If you have some text in simple blog code $original and you want it to be sbc-quoted (e. g. for reply functionality in boards), just use this. You can add the author's name as second argument:
my $reply = sbc_quote($original, $author);
my $description = sbc_description();
If you want some newbies to use SBC, just show them our SBC language description.
Simple blog code is a simple markup language. Paragraphs in input (text between newlines) are translated in (X)HTML P elements. In paragraphs, some
are allowed as follows:
*emphasis*
<em>emphasis</em>
_strong emphasis_
<strong>strong emphasis</strong>
<http://www.example.org/>
<a href="http://www.example.org/">http://www.example.org/</a>
<http://www.example.org/ hyperlink>
<a href="http://www.example.org/">hyperlink</a>
{http://www.example.org/foo.jpg}
<img src="http://www.example.org/foo.jpg" alt="">
{http://www.example.org/foo.jpg image}
<img src="http://www.example.org/foo.jpg" alt="image">
There are some elements on block level which don't have to be in paragraphs.
[nice quote]
<div class="quote"> <blockquote> nice quote </blockquote> </div>
[another nice quote] author
<div class="qoute"> <cite>author</cite> <blockquote> another nice quote </blockquote> </div>
- first\n- second\n- third\n
<ul> <li>first</li> <li>second</li> <li>third</li> </ul>
# first\n# second\n# third\n
<ol> <li>first</li> <li>second</li> <li>third</li> </ol>
Block level elements have to be started in new lines. In quotes, you can use block level elements, e. g.
[ \[...\] the three great virtues of a programmer: - laziness, - impatience and - hubris. ] Larry Wall
You'll get the nice quote from Larry with an inner list. You can see here, that characters with a special meaning have to be escaped in SBC. You would use "\*" to get an asterisk, for example.
Mirko Westermeier, <mail at memowe.de>
<mail at memowe.de>
Please report any bugs or feature requests to bug-html-sbc at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-SBC. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-html-sbc at rt.cpan.org
I love feedback. :-)
You can find documentation for this module with the perldoc command.
perldoc HTML::SBC
Thanks to Florian Ragwitz (rafl) for many helpful comments and suggestions.
Copyright 2006 Mirko Westermeier, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install HTML::SBC, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::SBC
CPAN shell
perl -MCPAN -e shell install HTML::SBC
For more information on module installation, please visit the detailed CPAN module installation guide.