view release on metacpan or  search on metacpan

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

	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
C<BBCode::Tag> internal structure.  It is possible to bypass checks on
security and correctness by altering it directly.

=head3 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 L<toHTML()|/"toHTML"> instead.

=head3 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 L<toText()|/"toText"> instead.

=head3 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 C<eval> to catch any exceptions.

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

=head3 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 C<toBBCode> is recommended each time
the user previews his/her message.  This makes it easier for the user to spot
troublesome code.

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

=head3 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
L<the Text::Unidecode module|Text::Unidecode> if you want 7-bit ASCII output.

=head3 toLinkList

	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 L<the follow_links setting|BBCode::Parser/"follow_links"> 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.

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

=head2 CLASS METHODS

=head3 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, C<BBCode::Tag::URL> becomes "URL".)  Override this in
subclasses as needed.

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