The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
BBCode-Parser-0.34
River stage zero No dependents
++
/ BBCode::Tag

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.

GENERAL USE

METHODS

new

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

Called as a class method. Takes three or more parameters: a class name (ignored), a BBCode::Parser object, the tag to be created, and any initial parameters. Returns a newly constructed tag of the appropriate subclass.

Initial parameters can be provided in one of two ways:

  • The value for the default parameter can be given as a plain string.

  • The value for any named parameter can be given as an anonymous array of length 2. The first element is the parameter name, and the second is the value. If the first element is undefined or the empty string, the default parameter is set instead.

Example:

        $url = BBCode::Tag->new(
                $parser,
                'URL',
                # Sets the default parameter (style 1)
                'http://www.example.com/',
                # Sets the FOLLOW parameter
                [ 'FOLLOW', '1' ],
        );
        $text = BBCode::Tag->new(
                $parser,
                'TEXT',
                # Sets the default parameter (style 2)
                [ undef, 'Example.com' ],
        );
        $url->pushBody($text);

parser

        $parser = $tag->parser();

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

isPermitted

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

Checks if the given BBCode tag is allowed in the body of this tag.

forbidTags

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

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

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 reference returned in scalar context 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 everything inside this tag into HTML. In array context, returns the HTML line-by-line (with '\n' already appended); in scalar context, returns the HTML as one string.

Odds are that you want to use toHTML() instead.

bodyText

        print HANDLE $tag->bodyText();

Recursively converts everything inside this tag into plain text. In array context, returns the plain text line-by-line (with '\n' already appended); in scalar context, returns the text as one string.

Odds are that you want to use toText() instead.

pushBody

        $tag->pushBody(
                'Image: ',
                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. Use eval to catch any exceptions.

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

toBBCode

Converts this BBCode tree back to BBCode. The resulting "deparsed" BBCode can reveal discrepancies between what the user means vs. what BBCode::Parser thinks the user means.

In a web environment, a round-trip using toBBCode is recommended each time the user previews his/her message. This makes it easier for the user to spot troublesome code.

toHTML

Converts this BBCode tree to HTML. This is generally the entire point of using BBCode.

At the moment, only XHTML 1.0 Strict output is supported. Future versions will likely support other HTML standards.

toText

Converts this BBCode tree to plain text.

Note that the result may contain Unicode characters. It is strongly recommended that you use UTF-8 encoding whenever you store or transmit the resulting text, to prevent loss of information. You might look at the Text::Unidecode module if you want 7-bit ASCII output.

        foreach $link ($tag->toLinkList) {
                my($followed,$tag,$href,$text) = @$link;
                print "<URL:$href> $text\n";
        }

Converts this BBCode tree into a list of all hyperlinks.

Each hyperlink is itself an anonymous array of length 4. The first element is a boolean that tells whether or not the link should be followed by search engines (see the follow_links setting for details). The second element is a string that holds the BBCode tag name that created this hyperlink. The third element is a string that holds the actual hyperlink address. The fourth element is the text content (if any) describing the link.

In scalar context, returns a reference to the array of hyperlinks. In list context, returns the array itself.

SUBCLASSING

While the details of subclassing presented below are currently accurate, a number of major changes are likely (mostly dealing with the addition of new BBCode tags at runtime). The API is not yet stable and will almost certainly change in incompatible ways. Hic sunt dracones.

CLASS METHODS

Tag

Returns the name of the tag as used in BBCode. For instance, the following code prints "URL":

        my $parser = BBCode::Parser->new;
        my $tree = $parser->parse("[URL]example.com[/URL]");
        printf "%s\n", $tree->body->[0]->Tag;

The default implementation returns the final component of the object's class name. (For instance, BBCode::Tag::URL becomes "URL".) Override this in subclasses as needed.

Class

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

For a more thorough discussion of tag classes, see "CLASSES" in BBCode::Parser.

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

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 (all tags are permitted).

NamedParams

Returns a list of named parameters that can be set on this tag. By default, the order in this list determines the order in "deparsed" BBCode. Override toBBCode() if this isn't acceptable.

At the moment, parameter aliases are not available. This may change in the future.

The default implementation returns an empty list (no parameters are permitted).

RequiredParams

Returns a list of named parameters that must be set on this tag.

If the returned list contains a named parameter that doesn't exist in the NamedParams() list, then the tag cannot be used. So don't do that.

The default implementation returns whatever NamedParams() returns (all permitted parameters are required).

(At the moment, this value still doesn't do anything, despite having been there since before 0.01 was released. However, it will eventually take effect somewhere around $tag->replaceBody time as $parser->parse finishes up. I think a $tag->finalize method is in order.)

DefaultParam

Returns the name of a single parameter that is fundamental enough that it is the parameter of the tag. Returns undef if no such parameter exists.

As an example, the [URL HREF] parameter is important enough to the [URL] tag that the following two lines of BBCode are equivalent:

        [URL HREF=example.com]Link[/URL]
        [URL=example.com]Link[/URL]

In this example, DefaultParam() returns 'HREF'.

The default implementation returns undef.

OpenPre

Returns a "fudge factor" value used in the default toBBCode(). The returned string is inserted into the "deparsed" BBCode just before the opening tag.

It is STRONGLY recommended that this value should only contain whitespace.

The default implementation returns the empty string.

OpenPost

Returns a "fudge factor" value used in the default toBBCode(). The returned string is inserted into the "deparsed" BBCode just after the opening tag and before the contents begin.

It is STRONGLY recommended that this value should only contain whitespace.

The default implementation returns the empty string.

ClosePre

Returns a "fudge factor" value used in the default toBBCode(). The returned string is inserted into the "deparsed" BBCode just before the closing tag and after the contents end.

It is STRONGLY recommended that this value should only contain whitespace.

The default implementation returns the empty string.

ClosePost

Returns a "fudge factor" value used in the default toBBCode(). The returned string is inserted into the "deparsed" BBCode just after the closing tag.

It is STRONGLY recommended that this value should only contain whitespace.

The default implementation returns the empty string.

INSTANCE METHODS

validateParam

Takes three parameters: the object, the name of a parameter, and the requested value for the parameter. Returns the actual value for the parameter. Throws an exception if the requested value is entirely unacceptable.

The default implementation returns all values unchanged. Override this to perform checking on the values of named parameters.

FIXME: This API is clunky, especially for inheriting.

SEE ALSO

BBCode::Parser

AUTHOR

Donald King <dlking@cpan.org>