NAME

BBCode::Tag - Perl representation of a BBCode tag

DESCRIPTION

See the documentation on BBCode::Parser for an overview of the typical usage of this package.

METHODS

Tag

Tag returns the name of the tag as used in BBCode.

The default implementation returns the final component of the object's class name; override this in subclasses as needed.

Class

Class returns a list of zero or more strings, each of which is a class that this tag belongs to (without any colons). For instance, [B] and [I] tags are both of class :INLINE, meaning that they can be found inside fellow inline tags. Tag classes are listed in order from most specific to least.

The default implementation returns an empty list.

BodyPermitted

BodyPermitted indicates whether or not the tag can contain a body of some sort (whether it be text, more tags, or both).

The default implementation returns false.

BodyTags

BodyTags returns a list of tags and classes that are permitted or forbidden in the body of this tag. See BBCode::Parser->permit() for syntax. If this tag doesn't permit a body at all, this value is ignored.

The default implementation returns an empty list.

new

        $parser = BBCode::Parser->new(...);
        $tag = BBCode::Tag->new($parser, 'B');

Constructs a new tag of the appropriate subclass.

parser

        $parser = $tag->parser();

Returns the BBCode::Parser that this tag was constructed with.

isPermitted

        if($tag->isPermitted('URL')) {
                # $tag can contain [URL] tags
        } else {
                # [URL] tags are forbidden
        }

forbidTags

        $tag->forbidTags(qw(IMG URL));

Mark the given tag(s) as forbidden, so that this tag (nor any of its children, grandchildren, etc.) can contain any forbidden tag.

At the moment, if a tag already contains one of the tags now forbidden, a warning is raised. In the future, this behavior will likely change.

body

        # Iterate over all this tag's immediate children
        my @body = $tag->body();
        foreach my $subtag (@body) { ...; }

        # Forcibly add a new child, overriding $tag->isPermitted()
        my $body = $tag->body();
        my $bold = BBCode::Tag->new($tag->parser(), 'B');
        push @$body, $bold;

Returns the list of child tags for this tag. In list context, returns a list; otherwise, returns an array reference.

CAUTION: The returned reference is a direct pointer to a BBCode::Tag internal structure. It is possible to bypass checks on security and correctness by altering it directly.

bodyHTML

        print HANDLE $tag->bodyHTML();

Recursively converts this tag and everything inside it into HTML text. In array context, returns the HTML line-by-line (with CRLF already appended); in scalar context, returns the HTML as one string.

pushBody $tag->pushBody( BBCode::Tag->new($tag->parser(), 'IMG', 'http://www.example.org/img.png') );

Appends one or more new child tags to this tag's body. Security and correctness checks are performed.

If any arguments are strings, they are upgraded to virtual [TEXT] tags.

SEE ALSO

BBCode::Parser

AUTHOR

Donald King <dlking@cpan.org>

cpanm BBCode::Parser

perl -MCPAN -e shell
install BBCode::Parser