OOP Interface

Constructor

new

    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.

Accessor methods

language

Accessor method for the "language" field. It defines the language of your error messages. All accessors are both setter and getter:

    $language = $translator->language();
    $translator->language($new_language);
    

Valid languages: 'english' (default), 'german'.

image_support

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.

error_callback

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.

linkcheck_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.

imgcheck_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.

Translation methods

sbc

    my $html = $translator->sbc($text);
    

Returns some valid HTML block elements which represent the given SBC $text.

sbc_inline

    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.

Error handling methods

After translation you can look for errors in your SBC input:

errors

    my @errors = $translator->errors();
    

returns a list of warnings/errors in the chosen language.

next_error

    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.

Class methods

There are some SBC tools implemented as class methods.

quote

    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:

    my $reply = HTML::SBC->quote($original, $author);
    

remove_hyperlinks

    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.

description

    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).

Vintage interface

    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 );

english

"HTML::SBC::english()" sets the language of your error messages to english.

german

"HTML::SBC::german()" sets the language of your error messages to german.

sbc_translate

    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_inline

    my ($inline_html, $errors) = sbc_translate_inline($inline_text);
    

does the same with inline content (see "sbc_inline").

sbc_quote

    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);
    

sbc_description

    my $description = sbc_description();
    

If you want some newbies to use SBC, just show them our SBC language description.

Language

inline elements

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}" (optional, only in oo)

    <img src="http://www.example.org/foo.jpg" alt="">
    

"{http://www.example.org/foo.jpg image}" (optional, only in oo)

    <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.

block level elements

"[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.