NAME

 HTML::Transmorgify::Attributes - HTML transformation compiler

SYNOPSIS

 use HTML::Transmorgify::Attributes;

 my $attr = HTML::Transmorgify::Attributes->new($tag, \@atvals, $closed);

 print "$attr";

 my $tag = $attr->tag;

DESCRIPTION

This module provides the objects that hold the data about <tags> parsed by HTML::Transmorgify.

Construction

Usually HTML::Transmorgify::Attributes objects are created by HTML::Transmorgify in the process of compiling HTML transformations.

If you want to create one yourself, the arguments are:

$tag

This is the name of the tag. <$tags>.

\@atvals

This is an array of pairs that could be turned into a hash through simple assingment. The key side of the pair is the attribute name. The value side of the pair is the atribute value. For attributes that do not have a value, like checked in

 <input type=checkbox name=checky value=valued checked />

the value should be undef. Eg:

 my $attr = HTML::Transmorgify::Attributes->new("input",
        [ type => 'checkbox, name => 'checky', 
        value => 'valued', checked => undef ],
        1)

$closed

Closed should be true if this is a self-closed tag like

 <hr />

Methods

Several of the lookup methods (raw, static, get) all take the same set of arguments: the attribute name to be retrieved, an optional positional location to look for the attribute, and a optional hash of options.

The positional location is for use with non-HMTL markup in an HTML context. For example if you allow

 <for thing things>

as an alternative form for

 <for iter=thing in=things>

then you will need to specify a positional parameter. Only the first attributes following a tag can be positional. The first non-positional attribute blocks any positional lookups at its postion or beyond. Positions are numbered from zero.

The following object methods are provided:

$attr->get($attribute_name, $position, %options)

Lookup an attribute. If the attribute value has HTML tags in it, then use HTML::Transmorgify to process the value before returning it.

For attributes that do not have values, like checked in

 <input type=checkbox name=foo value=bar checked>

the name of the attribute will be returned.

$attr->raw($attribute_name, $position, %options)

Lookup an attribute. Return the value without processing it with HTML::Transmorgify.

For attributes that do not have values, like checked in

 <input type=checkbox name=foo value=bar checked>

the name of the attribute will be returned.

$attr->static($attribute_name, $position, %options)

Lookup an attribute. Only return the value if the value does not have any HTML tags in it.

For attributes that do not have values, like checked in

 <input type=checkbox name=foo value=bar checked>

the name of the attribute will be returned.

$attr->boolean($attribute_name, $position, $default_value, %options)

Look up an attribute using $attr->get($attribute_name, $position, %options) (unless $options{raw} is set, in which case $attr->raw($attribute_name, $position, %options) is used instead).

Evaluate the value with the boolean() function from HTML::Transmorgify: no, false, 0 are false, other values are true.

$attr->as_string(%options);

Converts the tag and its attributes into a string. Any attribute values will be processed with HTML::Transmorgify. This method is used to override stringification for the HTML::Transmorgify::Attributes object.

$attr->set(%new_values)

Sets new values for one or more attributes. This can be used to add additional attributes to the tag.

$attr->hide()

Marks an attribute as hidden. This will cause the attribute to be skipped by $attr->as_string().

$attr->hide_position()

Marks an attribute by position as hidden. This will cause the attribute to be skipped by $attr->as_string().

If you looked up an attribute by name and position, then you may not know how it was found. To hide such an attribute, use hide() and hide_position().

$attr->tag()

Returns the value of $tag that was used when constructing the object.

$attr->closed()

Returns the value of $closed that was used when constructing the object.

$attr->location()

At the time that the HTML::Transmorgify::Attributes object is created, it takes note of the current values of $HTML::Transmorgify::textref, pos($HTML::Transmorgify::textref), $HTML::Transmorgify::input_line, and $HTML::Transmorgify::input_file. It uses this construct a string that can be used to give context to any error messages involving the tag. This method returns that string. Calling this function can be expensive since it calculates the line number of the error.

$attr->needs_cooking()

This method returns a reference to a hash that maps attribute name to a boolean value: does the attribute in question have any HTML tags embedded in its value? It is true for those that do.

$attr->add_to_result()

This method causes the tag to be "compiled". The tag is pushed into HTML::Transmorgify's run buffer (@$rbuf). Depending on whether any attribute values have any embedded HTML tags or if $attr->eval_at_runtime(1) has been called, the tag can be pushed as either a literal string or as a CODE callback.

$attr->eval_at_runtime($newvalue)

This gets or sets a flag: does this attribute need to be evaluated at runtime or can it be turned into a string at compile time?

Addon module writers should be careful about this: this should be set to true unless you can tell at compile time that it is not needed. Do not set it to false.

$attr->output_callback(@callbacks)

Add CODE reference callbacks to be invoked if $attr->as_string() is called. Any defined return value from a callback will be used as the return value from as_string(). Only one callback is allowed to return a defined value. The callback will receive $attr as its only argument.

$attr->static_action($attributes, $coderefs)

This is a wrapper function for tag callbacks to use. It looks at $attributes which can be either a single attribute name or a reference to an array of attribute names. If the attribute (or attributes) values do not have any HTML markup in them, then $coderefs is evaluated immediately.

If not then $coderefs is pushed on the end of @$HTML::Transmorgify::rbuf for evaluation at runtime.

$attr->vals()

Returns a reference to the hash of raw attribute/value pairs.

$attr->last_position()

Returns the last position at which a positional attribute may be found. This is zero-based: if there are no positional attributes then this returns -1.

With an argument, this returns true if the argument is less than or equal to the last position.