String::Tagged::HTML - handle HTML content using String::Tagged
String::Tagged::HTML
String::Tagged
use String::Tagged::HTML; my $st = String::Tagged::HTML->new( "An important message" ); $st->apply_tag( 3, 9, b => 1 ); print $st->as_html( "h1" );
This subclass of String::Tagged provides a method, as_html, for rendering the string as an HTML fragment, using the tags to provide formatting. For example, the SYNOPSIS example will produce the output
as_html
<h1>An <b>important</b> message</h1>
With the exception of tags named raw, a tag applied to an extent of the String::Tagged::HTML will be rendered using start and end HTML tags of the same name. If the tag's value is a HASH reference, then this hash will be used to provide additional attributes for the HTML element. Tags whose names begin with _ will be ignored for this purpose.
raw
HASH
_
my $str = String::Tagged::HTML->new( "click " ) ->append_tagged( "here", a => { href => "/see/other.html" } ); print $str->as_html( "p" );
<p>click <a href="/see/other.html">here</a></p>
If it is not a HASH reference, then its value ought to be a simple boolean true value, such as 1.
1
The special tag named raw disables HTML entity escaping over its extent.
my $str = String::Tagged::HTML->new( "This <content> is escaped" ); my $br = String::Tagged::HTML->new_tagged( "<br/>", raw => 1 ); print +( $str . $br )->as_html( "p" );
<p>This <content> is escaped<br/></p>
<span>
Tags whose names begin _span_style_... are used to create a style attribute for an implied span tag.
_span_style_...
style
span
All tags with this name prefix are collected together. The part of the name following this prefix is used as the style property name and the value of the tag used for its value. These are all joined into a single string, and that is then used to generate the style tag.
As an extra convenience, any remaining underscores in the tag name will be converted to hyphens in the style property name.
my $str = String::Tagged::HTML->new( "Some big text" ); $str->apply_tag( 5, 3, _span_style_font_size => "large" ); print $str->as_html
Some <span style="font-size: large;">big</span> text
Because of the arbitrary way that String::Tagged tags may be applied, as compared to the strict nesting requirements in HTML, the as_html method may have to break a single String::Tagged tag into multiple regions. In the following example, the i tag has been split in two to allow it to overlap correctly with b.
i
b
my $str = String::Tagged::HTML->new( "bbb b+i iii" ); $str->apply_tag( 0, 7, b => 1 ); $str->apply_tag( 4, 7, i => 1 ); print $str->as_html
<b>bbb <i>b+i</i></b><i> iii</i>
String::Tagged::Formatting specifes a standard way that subclasses of String::Tagged can express a variety of simple formatting styles. HTML is a lot more flexible than this (and CSS doubly so). Certain limited support is provided for converting String::Tagged::Formatting tags into a form that can be rendered into standalone HTML.
String::Tagged::Formatting
The following tag conversions are supported:
bold <strong> under <u> italic <em> strike <strike> monospace <tt> sizepos = "super" <sup> sizepod = "sub" <sub> fg <span style="color: #rrggbb"> bg <span style="background-color: #rrggbb">
As well as the standard new and new_tagged constructors provided by String::Tagged, the following is provided.
new
new_tagged
$st = String::Tagged::HTML->new_raw( $str );
Returns a new String::Tagged::HTML instance with the raw tag applied over its entire length. This convenience is provided for creating objects containing already-rendered HTML fragments.
$st = String::Tagged::HTML->new_from_formatting( $fmt, %params );
Returns a new instance by converting String::Tagged::Formatting standard tags, as described above.
The following additional named arguments are recognised:
Optional. If true, linefeeds in the source string will be converted into <br/> HTML tags in the result. Defaults to true if absent, but the behaviour can be disabled by passing a defined-but-false value.
<br/>
$st = String::Tagged::HTML->parse_html( $html );
Returns a new String::Tagged::HTML instance by parsing the given HTML content and composing the plaintext parts of the content, with tags applied over the appropriate ranges of it.
This parsing is currently performed using HTML::TreeBuilder, and will not work if that module is not available.
The following methods are provided in addition to those provided by String::Tagged.
$html = $st->as_html( $element );
Returns a string containing an HTML rendering of the current contents of the object. If $element is provided, the output will be wrapped in an element of the given name. If not defined, no outer wrapping will be performed.
$element
Paul Evans <leonerd@leonerd.org.uk>
To install String::Tagged::HTML, copy and paste the appropriate command in to your terminal.
cpanm
cpanm String::Tagged::HTML
CPAN shell
perl -MCPAN -e shell install String::Tagged::HTML
For more information on module installation, please visit the detailed CPAN module installation guide.