.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Marpa::R2::HTML 3pm"
.TH Marpa::R2::HTML 3pm "2021-01-22" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Marpa::R2::HTML \- High\-level HTML Parser
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBDelete all tables\fR:
.PP
.Vb 1
\& use Marpa::R2::HTML qw(html);
\&
\& my $with_table = \*(AqText
More Text\*(Aq;
\& my $no_table = html( \e$with_table, { table => sub { return q{} } });
.Ve
.PP
\&\fBDelete everything but tables\fR:
.PP
.Vb 5
\& my %handlers_to_keep_only_tables = (
\& table => sub { return Marpa::R2::HTML::original() },
\& \*(Aq:TOP\*(Aq => sub { return \e( join q{}, @{ Marpa::R2::HTML::values() } ) }
\& );
\& my $only_table = html( \e$with_table, \e%handlers_to_keep_only_tables );
.Ve
.PP
The above works by turning the original text of the \s-1HTML\s0 into values
and concatenating the values at the top of the parse.
The same logic works even if a \fBtable is very defective\fR:
.PP
.Vb 3
\& my $with_bad_table = \*(AqTextI am a cell More Text\*(Aq;
\& my $only_bad_table =
\& html( \e$with_bad_table, \e%handlers_to_keep_only_tables );
.Ve
.PP
\&\fBDelete all comments\fR:
.PP
.Vb 3
\& my $with_comment = \*(AqText I am not a comment\*(Aq;
\& my $no_comment = html( \e$with_comment,
\& { \*(Aq:COMMENT\*(Aq => sub { return q{} } });
.Ve
.PP
By default, text is passed through unchanged, so that the user
need only specify semantic actions for those components she
wants changed. To \fBchange the title of a document\fR:
.PP
.Vb 6
\& my $old_title = \*(AqOld TitleA little html text\*(Aq;
\& my $new_title = html(
\& \e$old_title,
\& { \*(Aqtitle\*(Aq => sub { return \*(AqNew Title\*(Aq }
\& }
\& );
.Ve
.PP
\&\fBDelete all elements with a class attribute
of "\f(CB\*(C`delete_me\*(C'\fB"\fR:
.PP
.Vb 3
\& my $stuff_to_be_edited = \*(AqA
B
C\*(Aq;
\& my $edited_stuff = html( \e$stuff_to_be_edited,
\& { \*(Aq.delete_me\*(Aq => sub { return q{} } });
.Ve
.PP
Marpa::R2::HTML recognizes elements even if they have missing
start and/or end tags.
Marpa::R2::HTML can \fBsupply missing tags\fR:
.PP
.Vb 10
\& sub supply_missing_tags {
\& my $tagname = Marpa::R2::HTML::tagname();
\& return if Marpa::R2::HTML::is_empty_element($tagname);
\& return ( Marpa::R2::HTML::start_tag() // "<$tagname>\en" )
\& . Marpa::R2::HTML::contents() .
\& ( Marpa::R2::HTML::end_tag() // "$tagname>\en" );
\& }
\& my $html_with_just_a_title = \*(Aq
I am a title and That is IT!\*(Aq;
\& my $valid_html_with_all_tags =
\& html( \e$html_with_just_a_title, { q{*} => \e&supply_missing_tags } );
.Ve
.PP
Marpa::R2::HTML understands the hierarchical structure of an \s-1HTML\s0 document.
\&\fBFinding the maximum nesting depth in elements\fR is straightforward:
.PP
.Vb 9
\& sub depth_below_me {
\& return List::Util::max( 0, @{ Marpa::R2::HTML::values() } );
\& }
\& my %handlers_to_calculate_maximum_element_depth = (
\& q{*} => sub { return 1 + depth_below_me() },
\& \*(Aq:TOP\*(Aq => sub { return depth_below_me() },
\& );
\& my $maximum_depth_with_just_a_title = html( \e$html_with_just_a_title,
\& \e%handlers_to_calculate_maximum_element_depth );
.Ve
.PP
Marpa::R2::HTML tracks actual elements, however tagged.
The above code returns the same depth for \f(CW$valid_html_with_all_tags\fR
as for \f(CW$html_with_just_a_title\fR.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Marpa::R2::HTML does \*(L"high-level\*(R" parsing of \s-1HTML.\s0
It allows handlers to be specified for elements, terminals and other
components in the hierarchical structure of an \s-1HTML\s0 document.
Marpa::R2::HTML is an extremely liberal \s-1HTML\s0 parser.
Marpa::R2::HTML does not reject any documents,
no mater how poorly they fit the \s-1HTML\s0 standards.
.SH "THE Marpa::R2::HTML::html STATIC METHOD"
.IX Header "THE Marpa::R2::HTML::html STATIC METHOD"
The interface to
Marpa::R2::HTML is through the
\&\f(CW\*(C`Marpa::R2::HTML::html\*(C'\fR
static method.
It is
the only
Marpa::R2::HTML
method not part of the \s-1API\s0 for the
semantic actions.
.PP
\&\f(CW\*(C`html\*(C'\fR takes one or more arguments.
The first argument is required, and must be a reference to
a string to be parsed as \s-1HTML.\s0
The second and
subsequent arguments (all optional) are hash references
with handler descriptions.
(See the synopsis for several examples of
calls using the \f(CW\*(C`html\*(C'\fR method.)
.SS "CSS-style Handler Options"
.IX Subsection "CSS-style Handler Options"
Handler descriptions in Marpa::R2::HTML are key-value pairs
in a hash.
In each pair, the key is a CSS-style handler specifier,
and the value is a closure,
which is called the \fBaction\fR for the
handler.
.PP
Specifiers are \*(L"CSS-style\*(R" \*(--
their syntax imitates some of the basic cases
of \s-1CSS\s0 specifiers.
No attempt is planned
to implement the full \s-1CSS\s0 specifier syntax.
.PP
Supported specifier syntaxes are as follows:
.IP "Tagname Specifiers" 4
.IX Item "Tagname Specifiers"
.Vb 1
\& table => sub { return Marpa::R2::HTML::original() },
.Ve
.Sp
If a specifier contains no special characters
it is taken
as the name of an element.
(A \*(L"special\*(R" character is
anything except an alphanumeric, a hyphen or an underscore.)
Consistent with HTML::Parser's default behavior,
element names must be specified in lowercase.
.IP "Class Specifiers" 4
.IX Item "Class Specifiers"
A specifier which is a dot or period followed by a name
will match any element whose class attribute is the same as the specified name.
For example, the specifier "\f(CW\*(C`.delete_me\*(C'\fR\*(L" will match any element whose
class attribute is \*(R"\f(CW\*(C`delete_me\*(C'\fR".
.IP "Tagname-Class Pair Specifiers" 4
.IX Item "Tagname-Class Pair Specifiers"
A specifier which contains a dot or period somewhere other than
the first position (such as "\f(CW\*(C`span.label\*(C'\fR")
is treated as a dotted tagname-class pair.
Its action will be called for
any component whose tagname and class attribute both match
the specifiers.
.IP "The Tagname Wildcard Specifier" 4
.IX Item "The Tagname Wildcard Specifier"
A specifier of just an asterisk ("\f(CW\*(C`*\*(C'\fR") matches all elements.
Be careful to note that matching all elements is \fBnot\fR the same
as matching all components.
The element wildcard specifier will not match any pseudoclasses.
.IP "Pseudoclass Specifiers" 4
.IX Item "Pseudoclass Specifiers"
.Vb 1
\& \*(Aq:COMMENT\*(Aq => sub { return q{} }
.Ve
.Sp
A specifier which begins with a colon ("\f(CW\*(C`:\*(C'\fR") matches a pseudoclass.
Marpa::R2::HTML defines
pseudoclasses to deal with terminals and other non-element
components of the \s-1HTML\s0 hierarchy.
.SS "Conflicting Specifiers"
.IX Subsection "Conflicting Specifiers"
At most one semantic action is called for each component.
Where an element component matches several specifiers,
the action is picked based on the \fBmost specific match\fR.
.IP "1. Matches by tagname-class pair are the most specific." 4
.IX Item "1. Matches by tagname-class pair are the most specific."
.PD 0
.IP "2. Matches by class are the next most specific." 4
.IX Item "2. Matches by class are the next most specific."
.IP "3. Matches by tagname are considered less specific than matches by class." 4
.IX Item "3. Matches by tagname are considered less specific than matches by class."
.IP "4. The wildcard match is the least specific." 4
.IX Item "4. The wildcard match is the least specific."
.PD
.PP
Here's an example:
.PP
.Vb 7
\& my $html = <<\*(AqEND_OF_HTML\*(Aq;
\& High Span
\& Low Span
\& High Div
\& Low Div
\& Oddball Div
\& END_OF_HTML
\&
\& our @RESULTS = ();
\& Marpa::R2::HTML::html(
\& \e$html,
\& { q{*} => sub {
\& push @RESULTS, \*(Aqwildcard handler: \*(Aq . Marpa::R2::HTML::contents();
\& },
\& \*(Aqdiv\*(Aq => sub {
\& push @RESULTS, \*(Aq"div" handler: \*(Aq . Marpa::R2::HTML::contents();
\& },
\& \*(Aq.high\*(Aq => sub {
\& push @RESULTS, \*(Aq".high" handler: \*(Aq . Marpa::R2::HTML::contents();
\& },
\& \*(Aqdiv.high\*(Aq => sub {
\& push @RESULTS,
\& \*(Aq"div.high" handler: \*(Aq . Marpa::R2::HTML::contents();
\& },
\& \*(Aq.oddball\*(Aq => sub {
\& push @RESULTS,
\& \*(Aq".oddball" handler: \*(Aq . Marpa::R2::HTML::contents();
\& },
\& \*(Aqbody\*(Aq => sub {undef},
\& \*(Aqhead\*(Aq => sub {undef},
\& \*(Aqhtml\*(Aq => sub {undef},
\& \*(Aqp\*(Aq => sub {undef},
\& }
\& );
.Ve
.PP
Here is what \f(CW$result\fR would contain after the above code was run:
.PP
.Vb 5
\& ".high" handler: High Span
\& wildcard handler: Low Span
\& "div.high" handler: High Div
\& "div" handler: Low Div
\& ".oddball" handler: Oddball Div
.Ve
.SS "Details of the Specifier Syntax"
.IX Subsection "Details of the Specifier Syntax"
For elements and class names only alphanumerics, hyphens and underscores are supported.
Elements must be specified in lowercase, but they will match tagnames in the original
document on a case-insensitive basis.
.PP
Forcing element names to be lowercase follows the default behavior of
HTML::Parser, which coerces all tagnames to lowercase.
This is consistent with the \s-1HTML\s0 standards.
It is \fBnot\fR consistent with the \s-1XML\s0 standards,
and an option to configure this behavior may be added in
the future.
.PP
Pseudoclass names special to
Marpa::R2::HTML are case-sensitive, and must be all uppercase.
Lowercase is reserved for \s-1CSS\s0 pseudoclasses.
The \s-1CSS\s0 standard specifies that its pseudoclass names are case-indifferent.
No \s-1CSS\s0 pseudoclasses are supported at this writing.
.SH "PSEUDOCLASSES"
.IX Header "PSEUDOCLASSES"
Marpa::R2::HTML uses
HTML::Parser to do its low-level parsing.
HTML::Parser \*(L"events\*(R"
become the terminals for Marpa::R2::HTML.
.PP
Besides terminals and elements,
three other \s-1HTML\s0 components are recognized:
the \s-1SGML\s0 prolog (\f(CW\*(C`:PROLOG\*(C'\fR),
the \s-1SGML\s0 trailer (\f(CW\*(C`:TRAILER\*(C'\fR),
and the \s-1HTML\s0 document as a whole (\f(CW\*(C`:TOP\*(C'\fR).
.SS ":CDATA"
.IX Subsection ":CDATA"
The \f(CW\*(C`:CDATA\*(C'\fR pseudoclass specifies the action for
\&\s-1CDATA\s0 terminals.
Its action is called once for each non-whitespace raw \f(CW\*(C`text\*(C'\fR event
that is not reclassed as cruft.
(\fBRaw text\fR
is text in which any markup and entities should be left as is.)
.PP
More precisely,
a \f(CW\*(C`:CDATA\*(C'\fR terminal is created from any
HTML::Parser \f(CW\*(C`text\*(C'\fR event that has the \f(CW\*(C`is_cdata\*(C'\fR flag on;
that contains a non-whitespace character
as defined in the \s-1HTML 4.01\s0 specification
();
and that is not reclassed as cruft.
.SS ":COMMENT"
.IX Subsection ":COMMENT"
The \f(CW\*(C`:COMMENT\*(C'\fR pseudoclass specifies the action for \s-1HTML\s0 comments.
Its action is called once for every \f(CW\*(C`HTML::Parser\*(C'\fR \f(CW\*(C`comment\*(C'\fR event that
is not reclassed as cruft.
.SS ":CRUFT"
.IX Subsection ":CRUFT"
The \f(CW\*(C`:CRUFT\*(C'\fR pseudoclass specifies the action for cruft.
Its action is called once for every \f(CW\*(C`HTML::Parser\*(C'\fR event that
Marpa::R2::HTML reclasses as cruft.
.PP
Marpa::R2::HTML reclasses terminals as cruft when
they do not fit the structure of an \s-1HTML\s0 document.
One example of a terminal that
Marpa::R2::HTML would reclass as cruft is a
\&\f(CW\*(C`\*(C'\fR end tag in the \s-1HTML\s0 body.
.PP
Reclassing terminals as cruft is only done as the last resort.
When it can,
HTML::Parser forgives
violations of the \s-1HTML\s0 standards and accepts terminals as non-cruft.
.PP
Cruft is treated in much the same way as comments.
It is preserved, untouched, in the original text view.
.SS ":DECL"
.IX Subsection ":DECL"
The \f(CW\*(C`:DECL\*(C'\fR pseudoclass specifies the action for \s-1SGML\s0 declarations.
Its action is called once for every \f(CW\*(C`HTML::Parser\*(C'\fR \f(CW\*(C`declaration\*(C'\fR event that
is not reclassed as cruft.
.SS ":PCDATA"
.IX Subsection ":PCDATA"
The \f(CW\*(C`:PCDATA\*(C'\fR pseudoclass specifies the action for
\&\s-1PCDATA\s0 terminals.
Its action is called once for each non-whitespace non-raw \f(CW\*(C`text\*(C'\fR event
that is not reclassed as cruft.
.PP
More precisely,
a \f(CW\*(C`:PCDATA\*(C'\fR terminal is created from any
HTML::Parser \f(CW\*(C`text\*(C'\fR event that has the \f(CW\*(C`is_cdata\*(C'\fR flag \fBoff\fR;
that contains a non-whitespace character
as defined in the \s-1HTML 4.01\s0 specification
();
and that is not reclassed as cruft.
.PP
Markup and entities in
\&\f(CW\*(C`:PCDATA\*(C'\fR text
are expected to be interpreted eventually,
but it can be counter-productive to do this
during parsing.
An application may, for example,
be rewriting a document for display on the web.
In that case it will often
want to leave markup and entities for the client's browser
to interpret.
.PP
Marpa::R2::HTML leaves interpretation of markup and entities entirely to
the application.
An application which chooses to do the interpretation itself
may do it in the actions,
or deal with it in post-processing.
\&\s-1CPAN\s0 has excellent tools for this,
some of which are part of HTML::Parser.
.SS ":PI"
.IX Subsection ":PI"
The \f(CW\*(C`:PI\*(C'\fR pseudoclass specifies the action for \s-1SGML\s0 processing instructions.
Its action is called once for every HTML::Parser \f(CW\*(C`process\*(C'\fR event that
is not reclassed as cruft.
.SS ":PROLOG"
.IX Subsection ":PROLOG"
The \f(CW\*(C`:PROLOG\*(C'\fR pseudoclass specifies the action for \s-1SGML\s0 prolog.
This is the part of the \s-1HTML\s0 document which precedes the \s-1HTML\s0 root element.
Components valid in the
prolog include \s-1SGML\s0 comments, processing instructions and whitespace.
.SS ":TOP"
.IX Subsection ":TOP"
The action specified for the \f(CW\*(C`:TOP\*(C'\fR pseudoclass will be called
once and only once in every parse,
and will be the last action called in every parse.
The \f(CW\*(C`:TOP\*(C'\fR component is the entire
physical document, including
the \s-1SGML\s0 prolog,
the root element,
and the \s-1SGML\s0 trailer.
All the other \s-1HTML\s0 components in a document
will be descendants of the \f(CW\*(C`:TOP\*(C'\fR component.
.PP
The \f(CW\*(C`:TOP\*(C'\fR action is unique, in that there is always an action
for it, even if one is not specified.
The \f(CW\*(C`html\*(C'\fR method returns the value
returned by the \f(CW\*(C`:TOP\*(C'\fR action.
The default \f(CW\*(C`:TOP\*(C'\fR action returns a \fBreference\fR to a string
with the literal text value of all
of its descendants.
.SS ":TRAILER"
.IX Subsection ":TRAILER"
The \f(CW\*(C`:TRAILER\*(C'\fR pseudoclass specifies the action for \s-1SGML\s0 trailer.
This is the part of the \s-1HTML\s0 document which follows the \s-1HTML\s0 root element.
Components valid in the
trailer include \s-1SGML\s0 comments, processing instructions, and whitespace.
Cruft can also be found here, though for Marpa::R2::HTML that is a
last resort.
.SS ":WHITESPACE"
.IX Subsection ":WHITESPACE"
A Marpa::R2::HTML \f(CW\*(C`:WHITESPACE\*(C'\fR terminal is created for every
HTML::Parser \f(CW\*(C`text\*(C'\fR event that is entirely whitespace
as defined in the \s-1HTML 4.01\s0 specification
()
and that is not reclassed as cruft.
Whitespace is acceptable in places where non-whitespace is not,
and the difference can be very significant structurally.
.SH "VIEWS"
.IX Header "VIEWS"
I hope the synopsis convinces the reader
that the action semantics of Marpa::R2::HTML are natural.
This naturalness is achieved at the price of some novelty.
This section explains the ideas behind the semantic action \s-1API.\s0
Depending on taste,
readers may want to skip this section and go straight to
the \s-1API.\s0
.PP
The components of an \s-1HTML\s0 document form a hierarchy,
with the \f(CW\*(C`:TOP\*(C'\fR component on top, and the terminals on the bottom.
The traditional syntax tree method requires semantic actions
to know precisely
what children every component will have.
This processing model is not a good fit to \s-1HTML.\s0
Marpa::R2::HTML gives the writer of semantic actions
\&\*(L"views\*(R" of each component that better fit situations
where the number and type of
children is unknown or vaguely defined.
.PP
Marpa::R2::HTML's semantics
focus more widely \*(--
on a component's descendants instead of
just its direct children.
(The terms ancestor and descendant are used in the standard way:
If a component X is
above Y in the hierarchy,
X is an \fBancestor\fR of Y; and
Y is a \fBdescendant\fR of the X.)
.SS "The Original View"
.IX Subsection "The Original View"
The \fBoriginal view\fR sees the text of a component as it was
originally passed to the parser.
The original view never changes.
The original view is seen
through the \*(L"Marpa::R2::HTML::original\*(R" \s-1API\s0 method.
.SS "The Terminals View"
.IX Subsection "The Terminals View"
The \fBterminals view\fR sees the terminals corresponding to the
original text of a component.
The terminals view never changes.
The terminals view is usually seen as part of other views.
.PP
At this writing the \s-1API\s0 does not contain a \*(L"pure\*(R" terminals view method.
For a terminals view of the whole \s-1HTML\s0 document,
HTML::Parser does the job with significantly lower overhead.
For views and sections of views with no values defined,
the descendants view (described below)
is equivalent to the terminals view.
.SS "The Values View"
.IX Subsection "The Values View"
When actions are called, they return a value.
If that value is defined, it becomes visible to the \fBvalues view\fR of
its ancestors.
The values view of a component sees the visible values for its descendants.
.PP
The \fBvalues view\fR is an array, with the values ordered according to the
lexical order of the components whose actions returned them.
If no descendants have visible values,
then the values view is a zero-length array.
.PP
The values view is hierarchical.
When a component produces a visible value,
it makes the values of its descendants disappear.
That is, whenever the semantic action for a component X
returns anything other than a Perl \f(CW\*(C`undef\*(C'\fR, it has two effects:
.IP "\(bu" 4
That return value becomes the visible value associated with component X.
.IP "\(bu" 4
All the values previously visible due to semantic actions
for the descendants of component X disappear.
.PP
Values which disappear are gone forever.
There is no mechanism to make them \*(L"reappear\*(R".
.PP
As a special case, if an action for a component returns a Perl \f(CW\*(C`undef\*(C'\fR,
not only do the values of all its descendants disappear,
the component for the action also will not appear in the values view.
When its semantic action returns \f(CW\*(C`undef\*(C'\fR, a component permanently \*(L"drops out\*(R" of the values view
taking all descendants with it.
The original view is seen
through the \*(L"Marpa::R2::HTML::values\*(R" \s-1API\s0 method.
.SS "The Literal View"
.IX Subsection "The Literal View"
The literal view can be thought of as a mix between the original view
and the values view.
It sees a text string, like the original view.
But unlike the original view, the literal view includes the visible values.
.PP
Values appear in the \fBliteral view\fR in stringized form.
For sections of the original text without visible values,
the literal view is the same as the original
view.
In all Marpa::R2::HTML's views,
whether descendants are seen as text or values,
they
are seen in the original lexical order.
The literal view is seen
through the \*(L"Marpa::R2::HTML::literal\*(R" \s-1API\s0 method.
.SS "The Descendants View"
.IX Subsection "The Descendants View"
Just as the literal view can be thought of as a mix between the original view
and the values view,
the descendants view can be thought of a mix between the terminals view and the
values view.
.PP
The \fBdescendants view\fR sees an array of elements
with data for each
of the component's descendants,
in lexical order.
Where a value is visible, the descendants view sees data for the component with the
visible value.
Where no value is visible, the descendants view sees data for the terminals.
This means that
when no values are visible, the descendants view is the same as the terminals view.
.PP
The descendants view is implemented via the \*(L"Marpa::R2::HTML::descendants\*(R" method.
It is the most fine-grained and detailed way to look at the descendants of a component.
The descendants view can do anything that the other views can do,
but the other views should be preferred when they fit the application.
Other views are typically more intuitive and efficient.
.SS "Views versus Syntax Trees"
.IX Subsection "Views versus Syntax Trees"
Views are a generalization of the traditional method
for processing semantics: syntax trees.
The values view is the view that most
closely resembles a syntax tree.
But there are important differences.
.PP
In its purest form,
the syntax tree model
required the semantic actions to
define exactly how many and what kind of immediate children
each node had.
Each node in a syntax tree worked with its immediate children.
Children in a syntax tree appeared as values.
.PP
The values view, on the other hand, sees all its descendants,
not just its immediate children, but only if
they make themselves visible.
Because of this,
the values view lends itself to being mixed with other views.
The values view allows pieces of the tree to decide when they will
come into sight
and when they will fall out of view.
.SS "Views and Efficiency"
.IX Subsection "Views and Efficiency"
In most applications,
views are more efficient than syntax trees.
In terms of Marpa::R2::HTML views,
traditional syntax tree processing
corresponds most closely to the values view
when every component in the parse has a visible value.
For Marpa::R2::HTML this is close to the worst case.
.PP
Marpa::R2::HTML optimizes for unvalued components.
Unvalued components are represented as terminal spans.
Adjacent descendant spans are automatically merged.
This means the size and time required do not increase as
processing rises up the component hierarchy.
.PP
Terminals views are calculated on a just-in-time basis
when they are requested through the action \s-1API.\s0
The terminals view is produced quickly from the merged terminal span.
.PP
Original views are also calculated on a just-in-time basis
as requested.
Each terminal tracks the text it represents as a
character span.
The original text can be quickly reconstructed
as the text in the source document from
the first character location of its component's first terminal
to the last character location of the component's last terminal.
.PP
When a handler does not need to return a value,
the most efficient thing to do is to return \f(CW\*(C`undef\*(C'\fR.
This reverts that component and all its descendants to
the efficient unvalued representation.
.SH "THE SEMANTIC ACTION API"
.IX Header "THE SEMANTIC ACTION API"
Marpa::R2::HTML's semantic action \s-1API\s0 is implemented
mainly through context-aware static methods.
No arguments are passed to the
user's semantics action callbacks.
Instead the semantic actions get whatever data they need
by calling these static methods.
.SS "\s-1API\s0 Static Methods"
.IX Subsection "API Static Methods"
.IP "Marpa::R2::HTML::attributes" 4
.IX Item "Marpa::R2::HTML::attributes"
Returns a hash ref to the attributes of the start tag.
This hash ref is exactly the hash ref returned
for the \f(CW\*(C`attr\*(C'\fR arg specification of HTML::Parser.
The \f(CW\*(C`attributes\*(C'\fR \s-1API\s0 method
returns an empty hash
if there were no attributes,
if there was no start tag for this element,
or if the current component is not an element.
.IP "Marpa::R2::HTML::contents" 4
.IX Item "Marpa::R2::HTML::contents"
For an element, returns the literal view of the contents.
The contents of an element are its entire text
except for its start tag and its end tag.
For an non-element component, returns undef.
.IP "Marpa::R2::HTML::descendants" 4
.IX Item "Marpa::R2::HTML::descendants"
This static method implements the descendants view.
It takes one argument, the \*(L"dataspec\*(R".
The \fBdataspec\fR is a string specifying
the data to be returned for each descendant.
The \f(CW\*(C`descendants\*(C'\fR method
returns a reference to an array with one element per descendant,
in lexical order.
Each element in the array is a reference to an array whose
elements are
the per-descendant data requested in the string.
.Sp
The descendant data specification string has a syntax
similar to that of the \f(CW\*(C`argspec\*(C'\fR strings of HTML::Parser.
Details of that syntax are given below
.IP "Marpa::R2::HTML::end_tag" 4
.IX Item "Marpa::R2::HTML::end_tag"
For an element with an explicit end tag,
returns the original text of the end tag.
For non-element components, returns undef.
For elements with no end tag, returns undef.
.IP "Marpa::R2::HTML::is_empty_element" 4
.IX Item "Marpa::R2::HTML::is_empty_element"
For an element, returns a Perl true value if the element
is empty,
a defined Perl false value otherwise.
For non-element components, returns undef.
.IP "Marpa::R2::HTML::literal" 4
.IX Item "Marpa::R2::HTML::literal"
The \f(CW\*(C`Marpa::R2::HTML::literal\*(C'\fR method implements the literal view.
Returns a string containing the literal view of the component \*(--
its text as modified by any the visible values of its
descendants.
.IP "Marpa::R2::HTML::literal_ref" 4
.IX Item "Marpa::R2::HTML::literal_ref"
Returns a reference to a string containing the literal view of the
component. This can be useful for very long strings.
.IP "Marpa::R2::HTML::offset" 4
.IX Item "Marpa::R2::HTML::offset"
Returns the start offset of the component.
This is a zero-based location in the source document.
Some components are zero-length,
containing none of the tokens in the physical input.
The \f(CW\*(C`Marpa::R2::HTML::offset\*(C'\fR method return \f(CW\*(C`undef\*(C'\fR
for these.
.IP "Marpa::R2::HTML::original" 4
.IX Item "Marpa::R2::HTML::original"
The \f(CW\*(C`Marpa::R2::HTML::original\*(C'\fR method implements the original view.
Returns a string containing the original view of the component \*(--
its text unchanged from the source document.
.IP "Marpa::R2::HTML::start_tag" 4
.IX Item "Marpa::R2::HTML::start_tag"
For an element with an explicit start tag,
returns the original text of the start tag.
For non-element components, returns undef.
For elements with no explicit start tag, returns undef.
.IP "Marpa::R2::HTML::tagname" 4
.IX Item "Marpa::R2::HTML::tagname"
For an element component,
returns its tagname.
There is a tagname even if there are no
explicit tags.
Tagname is determined based on structure.
For non-element components, returns undef.
.IP "Marpa::R2::HTML::title" 4
.IX Item "Marpa::R2::HTML::title"
Returns the value of the title attribute.
For a non-element component, returns undef.
If there was no explicit start tag, returns undef.
If there was no title attribute, returns undef.
.IP "Marpa::R2::HTML::token_type" 4
.IX Item "Marpa::R2::HTML::token_type"
For a token, returns the token type.
The token types
are the event types from HTML::Parser:
"\f(CW\*(C`T\*(C'\fR\*(L" for text,
\&\*(R"\f(CW\*(C`S\*(C'\fR\*(L" for a start tag,
\&\*(R"\f(CW\*(C`E\*(C'\fR\*(L" for an end tag,
\&\*(R"\f(CW\*(C`PI\*(C'\fR\*(L" for a processing instruction,
\&\*(R"\f(CW\*(C`D\*(C'\fR\*(L" for an \s-1SGML\s0 declaration,
and \*(R"\f(CW\*(C`C\*(C'\fR" for a comment.
If the component is an element or some other
non-token, returns undef.
.IP "Marpa::R2::HTML::values" 4
.IX Item "Marpa::R2::HTML::values"
The \f(CW\*(C`Marpa::R2::HTML::values\*(C'\fR method implements the values view.
It returns a reference to an array of the descendant
values visible from this component,
in lexical order.
No elements of this array will be undefined.
The array will be zero length if no descendant
has a visible value.
.SS "Dataspecs"
.IX Subsection "Dataspecs"
.Vb 1
\& Marpa::R2::HTML::descendants(\*(Aqtoken_type,literal,element\*(Aq)
.Ve
.PP
The data specification string, or dataspec,
is a comma separated list of \fBdescendant data specifiers\fR.
The \f(CW\*(C`Marpa::R2::HTML::descendants\*(C'\fR method takes a dataspec
as its argument.
The \f(CW\*(C`Marpa::R2::HTML::descendants\*(C'\fR method returns a reference
to an array of references to arrays of per-descendant data.
The contents of the per-descendant data arrays
and their order is as specified
by the dataspec.
These are the valid descendant data specifiers:
.ie n .IP """element""" 4
.el .IP "\f(CWelement\fR" 4
.IX Item "element"
For an element descendant, returns the tagname.
A valid tagname is returned even if there were no explicit tags.
For non-element descendants, returns undef.
.ie n .IP """literal""" 4
.el .IP "\f(CWliteral\fR" 4
.IX Item "literal"
Returns a string containing the literal view of the
descendant.
.ie n .IP """original""" 4
.el .IP "\f(CWoriginal\fR" 4
.IX Item "original"
Returns a string containing the original view of the
descendant.
.ie n .IP """token_type""" 4
.el .IP "\f(CWtoken_type\fR" 4
.IX Item "token_type"
If the descendant is a terminal, returns the token type.
Token types are as described for the
\&\*(L"Marpa::R2::HTML::token_type\*(R" \s-1API\s0 method.
For components with visible values, returns undef.
.ie n .IP """value""" 4
.el .IP "\f(CWvalue\fR" 4
.IX Item "value"
For element descendants with a value, returns that
value.
In all other cases, returns undef.
.SS "The Instance Hash"
.IX Subsection "The Instance Hash"
Each Marpa::R2::HTML instance
makes available
a per-instance variable
as a scratchpad for the application:
\&\f(CW$Marpa::R2::HTML::INSTANCE\fR.
Each call to
Marpa::R2::HTML::html
creates a \f(CW$Marpa::R2::HTML::INSTANCE\fR
variable which is
reserved for that application using the \f(CW\*(C`local\*(C'\fR keyword.
Marpa::R2::HTML::html
initializes it to an empty hash,
but after that does not touch it.
When programming via side effects
is more natural than
passing data up the parse
tree (and it often is),
\&\f(CW$Marpa::R2::HTML::INSTANCE\fR can be used to
store the data.
.PP
Ordinarily, \f(CW$Marpa::R2::HTML::INSTANCE\fR is destroyed,
with the rest of the parse instance,
when \f(CW\*(C`Marpa::R2::HTML::html\*(C'\fR returns.
But it can be useful
for the \f(CW\*(C`:TOP\*(C'\fR semantic action to
return
\&\f(CW$Marpa::R2::HTML::INSTANCE\fR as the value of the parse.
.ie n .SS "Undefined Actions versus Actions Which Return ""undef"""
.el .SS "Undefined Actions versus Actions Which Return \f(CWundef\fP"
.IX Subsection "Undefined Actions versus Actions Which Return undef"
It is worth emphasizing that
the effect of not defining a semantic action for a component
is different from the effect of defining a semantic action which
returns a Perl \f(CW\*(C`undef\*(C'\fR.
The difference lies in what happens to any visible values
of the descendants of that component.
.PP
Where no action is defined for a component,
it leaves all that component's views as they were before.
That is, all values which were visible remain visible and
no new values become visible.
When an action is defined for a component, but that action returns undef,
no new values become visible, and
all descendant values which were visible \fBdisappear\fR.
.SS "Root Element versus :TOP Pseudoclass"
.IX Subsection "Root Element versus :TOP Pseudoclass"
It is important to understand the very
special function of the \f(CW\*(C`:TOP\*(C'\fR
component,
and to avoid confusing it with the \s-1HTML\s0 root element.
The most important distinctions are that
.IP "\(bu" 4
The semantic action
for \f(CW\*(C`:TOP\*(C'\fR pseudoclass is always the last action
to be called in a parse.
.IP "\(bu" 4
The \f(CW\*(C`:TOP\*(C'\fR component is \fBalways\fR the entire \s-1HTML\s0 document.
This can be true of the root element, but it is not true in
all cases.
.IP "\(bu" 4
The value that the action for the \f(CW\*(C`:TOP\*(C'\fR component
returns becomes the value that
the
Marpa::R2::HTML::html
method returns.
.PP
The root element is the \s-1HTML\s0 element whose tagname is "\f(CW\*(C`html\*(C'\fR", though
its start and end tags are optional
and can be omitted even in strictly valid \s-1HTML.\s0
Tags or no tags, every \s-1HTML\s0 document has a
root element.
(The \f(CW\*(C`:TOP\*(C'\fR component is not an element, so it does not have a tagname and
never has tags.)
.PP
The root element is always a descendant of the \f(CW\*(C`:TOP\*(C'\fR
component.
The \s-1SGML\s0 prolog and \s-1SGML\s0 trailer are always descendants of the \f(CW\*(C`:TOP\*(C'\fR
component.
The \s-1SGML\s0 prolog and \s-1SGML\s0 trailer
are never descendants of the root element.
.PP
If an action for the root element is specified,
it will also be called
once and only once in every parse.
An action for the root element can be specified in same way as actions
for other elements, using its tagname of "\f(CW\*(C`html\*(C'\fR".
An element wildcard action also becomes the action for the root element,
if no more specific handler declaration takes precedence.
.PP
A \f(CW\*(C`:TOP\*(C'\fR action will be called once and only once in every parse.
The \f(CW\*(C`:TOP\*(C'\fR action is unique in that there is a default action.
No other component has a default action.
.SS "Tags versus Structure"
.IX Subsection "Tags versus Structure"
Where tags conflict with structure,
HTML::Parser follows structure.
\&\*(L"Following structure\*(R" means that, for example,
if semantic actions for the \f(CW\*(C`html\*(C'\fR, \f(CW\*(C`head\*(C'\fR,
and \f(CW\*(C`body\*(C'\fR elements exist,
they will be called once and only once during every parse.
.PP
Consider this short and very defective \s-1HTML\s0 document:
.PP
.Vb 1
\& ShortText
.Ve
.PP
HTML::Parser starts the \s-1HTML\s0 document's body
when it encounters the \f(CW\*(C`\*(C'\fR start tag.
That means that, even if they were in the right order,
the two \f(CW\*(C`head\*(C'\fR tags cannot be fit into any reasonable parse
structure.
.PP
If an action is specified for the \f(CW\*(C`head\*(C'\fR element,
it will be called for the actual header,
and the original view of the \f(CW\*(C`head\*(C'\fR element component
will be the text "\f(CW\*(C`
Short\*(C'\fR".
The action for the \f(CW\*(C`head\*(C'\fR element will not be called again.
The two stray tags, \f(CW\*(C`\*(C'\fR and \f(CW\*(C`\*(C'\fR,
will be treated as descendants of
the \f(CW\*(C`body\*(C'\fR element, and reclassed as
\&\*(L"cruft\*(R" terminals.
.SS "Explicit and Implicit Elements"
.IX Subsection "Explicit and Implicit Elements"
If a semantic action
is specified for a tagname, it is called
whenever an element is found with that tagname,
even if there are no explicit tags for
that element.
The \s-1HTML\s0 standards allow both start and end tags
to be missing
for
\&\f(CW\*(C`html\*(C'\fR,
\&\f(CW\*(C`head\*(C'\fR,
\&\f(CW\*(C`body\*(C'\fR and
\&\f(CW\*(C`tbody\*(C'\fR elements.
Marpa::R2::HTML is more liberal,
and will recognize virtual tags for
\&\f(CW\*(C`table\*(C'\fR, \f(CW\*(C`tr\*(C'\fR, and \f(CW\*(C`td\*(C'\fR elements
as required to repair a defective table.
.PP
Marpa::R2::HTML is more even
liberal about recognizing virtual end tags
than it is about start tags.
Virtual start tags are recognized only for the specific
elements listed above.
For any non-empty \s-1HTML\s0 element, there is some circumstance
under which
Marpa::R2::HTML will recognize a virtual end tag.
At end of file,
as one example,
Marpa::R2::HTML will do its best to produce a balanced
\&\s-1HTML\s0 structure by
creating a virtual end tag for every element
in the stack of
currently active elements.
.SH "EXPORTS"
.IX Header "EXPORTS"
Marpa::R2::HTML exports nothing by default.
Optionally,
Marpa::R2::HTML::html
may be exported.
.SH "Copyright and License"
.IX Header "Copyright and License"
.Vb 5
\& Copyright 2014 Jeffrey Kegler
\& This file is part of Marpa::R2. Marpa::R2 is free software: you can
\& redistribute it and/or modify it under the terms of the GNU Lesser
\& General Public License as published by the Free Software Foundation,
\& either version 3 of the License, or (at your option) any later version.
\&
\& Marpa::R2 is distributed in the hope that it will be useful,
\& but WITHOUT ANY WARRANTY; without even the implied warranty of
\& MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
\& Lesser General Public License for more details.
\&
\& You should have received a copy of the GNU Lesser
\& General Public License along with Marpa::R2. If not, see
\& http://www.gnu.org/licenses/.
.Ve