.\" 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
.\" ========================================================================
.\"
.IX Title "HTML::HTML5::Microdata::Parser 3pm"
.TH HTML::HTML5::Microdata::Parser 3pm "2021-09-12" "perl v5.32.1" "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"
HTML::HTML5::Microdata::Parser \- fairly experimental parser for HTML 'microdata'
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use HTML::HTML5::Microdata::Parser;
\&  
\&  my $parser = HTML::HTML5::Microdata::Parser\->new($html, $baseURI);
\&  my $graph  = $parser\->graph;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package aims to have a roughly compatible \s-1API\s0 to RDF::RDFa::Parser.
.PP
Microdata is an experimental metadata format, not in wide use. Use this module
at your own risk.
.ie n .IP "$p = HTML::HTML5::Microdata::Parser\->new($html, $baseuri, \e%options, $storage)" 8
.el .IP "\f(CW$p\fR = HTML::HTML5::Microdata::Parser\->new($html, \f(CW$baseuri\fR, \e%options, \f(CW$storage\fR)" 8
.IX Item "$p = HTML::HTML5::Microdata::Parser->new($html, $baseuri, %options, $storage)"
This method creates a new HTML::HTML5::Microdata::Parser object and returns it.
.Sp
The \f(CW$xhtml\fR variable may contain an \s-1XHTML/XML\s0 string, or a
XML::LibXML::Document. If a string, the document is parsed using
HTML::HTML5::Parser and HTML::HTML5::Sanity, which may throw an
exception. HTML::HTML5::Microdata::Parser does not catch the exception.
.Sp
The base \s-1URI\s0 is used to resolve relative URIs found in the document.
.Sp
Options [default in brackets]:
.Sp
.Vb 10
\&  * alt_stylesheet  \- Magic rel="alternate stylesheet". [1]
\&  * auto_config     \- See section "Auto Config" [0]
\&  * mhe_lang        \- Process <meta http\-equiv=Content\-Language>.
\&                      [1]
\&  * prefix_empty    \- URI prefix for itemprops of untyped items.
\&                      [undef]
\&  * strategy        \- URI generation strategy for itemprops of
\&                      typed items. [HTML::HTML5::Microdata::
\&                      Strategy::Heuristic]
\&  * tdb_service     \- thing\-described\-by.org when possible. [0] 
\&  * xhtml_base      \- Process <base href> element. [1]
\&  * xhtml_lang      \- Process @lang. [1]
\&  * xhtml_meta      \- Process <meta>. [0]
\&  * xhtml_cite      \- Process @cite. [0]
\&  * xhtml_rel       \- Process @rel. [0]
\&  * xhtml_time      \- Process <time> element more nicely. [0]
\&  * xhtml_title     \- Process <title> element. [0]
\&  * xml_lang        \- Process @xml:lang. [1]
.Ve
.Sp
\&\f(CW$storage\fR is an RDF::Trine::Storage object. If undef, then a new
temporary store is created.
.ie n .IP "$p\->xhtml" 8
.el .IP "\f(CW$p\fR\->xhtml" 8
.IX Item "$p->xhtml"
Returns the \s-1HTML\s0 source of the document being parsed.
.ie n .IP "$p\->uri" 8
.el .IP "\f(CW$p\fR\->uri" 8
.IX Item "$p->uri"
Returns the base \s-1URI\s0 of the document being parsed. This will usually be the
same as the base \s-1URI\s0 provided to the constructor, but may differ if the
document contains a <base> \s-1HTML\s0 element.
.Sp
Optionally it may be passed a parameter \- an absolute or relative \s-1URI\s0 \- in
which case it returns the same \s-1URI\s0 which it was passed as a parameter, but
as an absolute \s-1URI,\s0 resolved relative to the document's base \s-1URI.\s0
.Sp
This seems like two unrelated functions, but if you consider the consequence
of passing a relative \s-1URI\s0 consisting of a zero-length string, it in fact makes
sense.
.ie n .IP "$p\->dom" 8
.el .IP "\f(CW$p\fR\->dom" 8
.IX Item "$p->dom"
Returns the parsed XML::LibXML::Document.
.ie n .IP "$p\->set_callbacks(\e%callbacks)" 8
.el .IP "\f(CW$p\fR\->set_callbacks(\e%callbacks)" 8
.IX Item "$p->set_callbacks(%callbacks)"
Set callback functions for the parser to call on certain events. These are only necessary if
you want to do something especially unusual.
.Sp
.Vb 5
\&  $p\->set_callbacks({
\&    \*(Aqpretriple_resource\*(Aq => sub { ... } ,
\&    \*(Aqpretriple_literal\*(Aq  => sub { ... } ,
\&    \*(Aqontriple\*(Aq           => undef ,
\&    });
.Ve
.Sp
Either of the two pretriple callbacks can be set to the string 'print' instead of a coderef.
This enables built-in callbacks for printing Turtle to \s-1STDOUT.\s0
.Sp
For details of the callback functions, see the section \s-1CALLBACKS.\s0 \f(CW\*(C`set_callbacks\*(C'\fR must
be used \fIbefore\fR \f(CW\*(C`consume\*(C'\fR. \f(CW\*(C`set_callbacks\*(C'\fR itself returns a reference to the parser
object itself.
.ie n .IP "$p\->consume" 8
.el .IP "\f(CW$p\fR\->consume" 8
.IX Item "$p->consume"
The document is parsed for Microdata. Nothing of interest is returned by this
function, but the triples extracted from the document are passed to the
callbacks as each one is found.
.Sp
The \f(CW\*(C`graph\*(C'\fR method automatically calls \f(CW\*(C`consume\*(C'\fR, so normally you don't need
to call it manually. If you're using callback functions, it may be useful though.
.ie n .IP "$p\->consume_microdata_item($element)" 8
.el .IP "\f(CW$p\fR\->consume_microdata_item($element)" 8
.IX Item "$p->consume_microdata_item($element)"
You almost certainly do not want to use this method.
.Sp
It will consume a single Microdata item, assuming that \f(CW$element\fR is an
element that does or should have the \f(CW@itemscope\fR attribute set. Returns
the \s-1URI\s0 or blank node identifier for the item.
.Sp
This method is exposed mostly for the benefit of
HTML::HTML5::Microdata::ToRDFa.
.ie n .IP "$p\->\fBgraph()\fR" 8
.el .IP "\f(CW$p\fR\->\fBgraph()\fR" 8
.IX Item "$p->graph()"
This method will return an RDF::Trine::Model object with all
statements of the full graph.
.ie n .IP "$p\->\fBgraphs()\fR" 8
.el .IP "\f(CW$p\fR\->\fBgraphs()\fR" 8
.IX Item "$p->graphs()"
Provided for RDF::RDFa::Parser compatibility.
.SH "CALLBACKS"
.IX Header "CALLBACKS"
Several callback functions are provided. These may be set using the \f(CW\*(C`set_callbacks\*(C'\fR function,
which taskes a hashref of keys pointing to coderefs. The keys are named for the event to fire the
callback on.
.SS "pretriple_resource"
.IX Subsection "pretriple_resource"
This is called when a triple has been found, but before preparing the triple for
adding to the model. It is only called for triples with a non-literal object value.
.PP
The parameters passed to the callback function are:
.IP "\(bu" 4
A reference to the \f(CW\*(C`HTML::HTML5::Microdata::Parser\*(C'\fR object
.IP "\(bu" 4
A reference to the \f(CW\*(C`XML::LibXML::Element\*(C'\fR being parsed
.IP "\(bu" 4
Subject \s-1URI\s0 or bnode (string)
.IP "\(bu" 4
Predicate \s-1URI\s0 (string)
.IP "\(bu" 4
Object \s-1URI\s0 or bnode (string)
.PP
The callback should return 1 to tell the parser to skip this triple (not add it to
the graph); return 0 otherwise.
.SS "pretriple_literal"
.IX Subsection "pretriple_literal"
This is the equivalent of pretriple_resource, but is only called for triples with a
literal object value.
.PP
The parameters passed to the callback function are:
.IP "\(bu" 4
A reference to the \f(CW\*(C`HTML::HTML5::Microdata::Parser\*(C'\fR object
.IP "\(bu" 4
A reference to the \f(CW\*(C`XML::LibXML::Element\*(C'\fR being parsed
.IP "\(bu" 4
Subject \s-1URI\s0 or bnode (string)
.IP "\(bu" 4
Predicate \s-1URI\s0 (string)
.IP "\(bu" 4
Object literal (string)
.IP "\(bu" 4
Datatype \s-1URI\s0 (string or undef)
.IP "\(bu" 4
Language (string or undef)
.PP
Beware: sometimes both a datatype \fIand\fR a language will be passed. 
This goes beyond the normal \s-1RDF\s0 data model.)
.PP
The callback should return 1 to tell the parser to skip this triple (not add it to
the graph); return 0 otherwise.
.SS "ontriple"
.IX Subsection "ontriple"
This is called once a triple is ready to be added to the graph. (After the pretriple
callbacks.) The parameters passed to the callback function are:
.IP "\(bu" 4
A reference to the \f(CW\*(C`HTML::HTML5::Microdata::Parser\*(C'\fR object
.IP "\(bu" 4
A reference to the \f(CW\*(C`XML::LibXML::Element\*(C'\fR being parsed
.IP "\(bu" 4
An RDF::Trine::Statement object.
.PP
The callback should return 1 to tell the parser to skip this triple (not add it to
the graph); return 0 otherwise. The callback may modify the RDF::Trine::Statement
object.
.SH "ITEMPROP URI GENERATION STRATEGY"
.IX Header "ITEMPROP URI GENERATION STRATEGY"
The \f(CW\*(C`itemprop\*(C'\fR attribute does not need to be a full \s-1URI.\s0
.PP
.Vb 3
\& <div itemscope itemtype="http://example.com/Person">
\&   <span itemprop="phoneNumber">01234 567 890</span>
\& </div>
.Ve
.PP
The \f(CW\*(C`strategy\*(C'\fR option passed to the constructor tells the parser how to
convert \f(CW\*(C`phoneNumber\*(C'\fR in the above example into a \s-1URI.\s0 This can be a
callback function, or an object or class that provides a \f(CW\*(C`generate_uri\*(C'\fR
method.
.PP
Three strategies are bundled with this distribution:
.IP "\(bu" 4
\&\fBHTML::HTML5::Microdata::Strategy::Basic\fR \- don't attempt to convert to a \s-1URI\s0
.IP "\(bu" 4
\&\fBHTML::HTML5::Microdata::Strategy::Heuristic\fR \- smart strategy, the default
.IP "\(bu" 4
\&\fBHTML::HTML5::Microdata::Strategy::Microdata0\fR \- official strategy of early Microdata drafts
.SH "AUTO CONFIG"
.IX Header "AUTO CONFIG"
HTML::HTML5::Microdata::Parser has a lot of different options that can
be switched on and off. Sometimes it might be useful to allow the page
being parsed to control some of the options. If you switch on the
\&'auto_config' option, pages can do this.
.PP
A page can set options using a specially crafted <meta> tag:
.PP
.Vb 2
\&  <meta name="http://search.cpan.org/dist/HTML\-HTML5\-Microdata\-Parser/#auto_config"
\&     content="alt_stylesheet=0&amp;prefix_empty=http://example.net/" />
.Ve
.PP
Note that the \f(CW\*(C`content\*(C'\fR attribute is an application/x\-www\-form\-urlencoded
string (which must then be HTML-escaped of course). Semicolons may be used
instead of ampersands, as these tend to look nicer:
.PP
.Vb 2
\&  <meta name="http://search.cpan.org/dist/HTML\-HTML5\-Microdata\-Parser/#auto_config"
\&     content="alt_stylesheet=0;prefix_empty=http://example.net/" />
.Ve
.PP
Any option allowed in the constructor may be given using auto config,
except 'auto_config' itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
XML::LibXML, RDF::Trine, RDF::RDFa::Parser, 
HTML::HTML5::Parser, HTML::HTML5::Sanity.
.PP
<http://www.perlrdf.org/>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
Copyright (C) 2009\-2011 by Toby Inkster
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0