libhtml-microformats-perl 0.105-4 / usr / share / perl5 / HTML / Microformats.pm

package HTML::Microformats;

use strict qw(subs vars); no warnings;
use 5.010;

use HTML::HTML5::Parser;
use HTML::HTML5::Sanity qw(fix_document);
use HTML::Microformats::DocumentContext;
use HTML::Microformats::Datatype;
use HTML::Microformats::Format;
use JSON;
use RDF::Trine 0.130;
use XML::LibXML;

use Object::AUTHORITY;

BEGIN {
	$HTML::Microformats::AUTHORITY = 'cpan:TOBYINK';
	$HTML::Microformats::VERSION   = '0.105';
}

sub new_document
{
	my $class    = shift;
	my $document = shift;
	my $uri      = shift;
	my %opts     = @_;
	
	my $self = bless {}, $class;
	$self->modules; # force modules to be loaded
	
	if (ref $document && $document->isa('XML::LibXML::Document'))
	{
	}
	elsif ($opts{'type'} =~ /x(ht)?ml/i)
	{
		my $parser = XML::LibXML->new;
		$document  = $parser->parse_string($document);
	}
	else
	{
		my $parser = HTML::HTML5::Parser->new;
		$document  = fix_document( $parser->parse_string($document) );
	}
	
	$self->{'context'} = HTML::Microformats::DocumentContext->new($document, $uri);
	
	return $self;
}

sub profiles
{
	my $self = shift;
	return $self->{'context'}->profiles(@_);
}

sub has_profile
{
	my $self = shift;
	return $self->{'context'}->has_profile(@_);
}

sub add_profile
{
	my $self = shift;
	$self->{'context'}->add_profile(@_);
	return $self;
}

sub assume_profile
{
	my $self = shift;
	
	foreach my $fmt (@_)
	{
		my $profile = $fmt;
		($profile) = "HTML::Microformats::Format::${fmt}"->profiles
			if $fmt !~ ':';
		$self->add_profile($profile);
	}
	
	return $self;
}

sub assume_all_profiles
{
 	my $self = shift;
 	$self->assume_profile($self->formats);
	return $self;
}

sub parse_microformats
{
	my $self = shift;
	return if $self->{'parsed'};
	
	foreach my $fmt ($self->formats)
	{
		my @profiles = "HTML::Microformats::Format::${fmt}"->profiles;
		
		if ($self->has_profile(@profiles))
		{
			my @objects = "HTML::Microformats::Format::${fmt}"->extract_all(
				$self->{'context'}->document->documentElement,
				$self->{'context'});
			$self->{'objects'}->{$fmt} = \@objects;
		}
	}
	
	$self->{'parsed'} = 1;
	return $self;
}

sub clear_microformats
{
 	my $self = shift;
 	$self->{'objects'} = undef;
 	$self->{'context'}->cache->clear;
 	$self->{'parsed'}  = 0;
	return $self;
}

sub objects
{
	my $self = shift;
	my $fmt  = shift;
	$self->parse_microformats;
	return @{ $self->{'objects'}->{$fmt} }
		if wantarray;
	return $self->{'objects'}->{$fmt};
}

sub all_objects
{
	my $self = shift;
	$self->parse_microformats;	
	return $self->{'objects'};
}

sub TO_JSON
{
	return $_[0]->all_objects;
}

sub json
{
	my $self = shift;
	my %opts = @_;
	
	$opts{'convert_blessed'} = 1
		unless defined $opts{'convert_blessed'};

	$opts{'utf8'} = 1
		unless defined $opts{'utf8'};

	return to_json($self->all_objects, \%opts);
}
 
sub model
{
	my $self  = shift;
	my $model = RDF::Trine::Model->temporary_model;
	$self->add_to_model($model);
	return $model;
}

sub serialise_model
{
	my $self = shift;
	
	my %opts = ref $_[0] ? %{ $_[0] } : @_;
	$opts{as} ||= 'Turtle';
	
	my $ser = RDF::Trine::Serializer->new(delete $opts{as}, %opts);
	return $ser->serialize_model_to_string($self->model);
}

sub add_to_model
{
	my $self  = shift;
	my $model = shift;
	$self->parse_microformats;
	
	foreach my $fmt ($self->formats)
	{
		foreach my $object (@{ $self->{'objects'}->{$fmt} })
		{
			$object->add_to_model($model);
		}
	}
	
	return $self;
}

use Module::Pluggable
	require     => 1,
	inner       => 0,
	search_path => ['HTML::Microformats::Format'],
	only        => qr/^HTML::Microformats::Format::[^:]+$/,
	sub_name    => 'modules',
	;

sub formats
{
	my $class = shift || __PACKAGE__;
	return
		sort { lc $a cmp lc $b }
		map { s/^HTML::Microformats::Format:://; $_ }
		$class->modules;
}

1;

__END__

=head1 NAME

HTML::Microformats - parse microformats in HTML

=head1 SYNOPSIS

 use HTML::Microformats;
 
 my $doc = HTML::Microformats
             ->new_document($html, $uri)
             ->assume_profile(qw(hCard hCalendar));
 print $doc->json(pretty => 1);
 
 use RDF::TrineShortcuts qw(rdf_query);
 my $results = rdf_query($sparql, $doc->model);
 
=head1 DESCRIPTION

The HTML::Microformats module is a wrapper for parser and handler
modules of various individual microformats (each of those modules
has a name like HTML::Microformats::Format::Foo).

The general pattern of usage is to create an HTML::Microformats
object (which corresponds to an HTML document) using the
C<new_document> method; then ask for the data, as a Perl hashref,
a JSON string, or an RDF::Trine model.

=head2 Constructor

=over 4

=item C<< $doc = HTML::Microformats-E<gt>new_document($html, $uri, %opts) >>

Constructs a document object.

$html is the HTML or XHTML source (string) or an XML::LibXML::Document.

$uri is the document URI, important for resolving relative URL references.

%opts are additional parameters; currently only one option is defined:
$opts{'type'} is set to 'text/html' or 'application/xhtml+xml', to
control how $html is parsed.

=back

=head2 Profile Management

HTML::Microformats uses HTML profiles (i.e. the profile attribute on the
HTML E<lt>headE<gt> element) to detect which Microformats are used on a page. Any
microformats which do not have a profile URI declared will not be parsed.

Because many pages fail to properly declare which profiles they use, there
are various profile management methods to tell HTML::Microformats to
assume the presence of particular profile URIs, even if they're actually
missing.

=over 4

=item C<< $doc-E<gt>profiles >>

This method returns a list of profile URIs declared by the document.

=item C<< $doc-E<gt>has_profile(@profiles) >>

This method returns true if and only if one or more of the profile URIs
in @profiles is declared by the document.

=item C<< $doc-E<gt>add_profile(@profiles) >>

Using C<add_profile> you can add one or more profile URIs, and they are
treated as if they were found in the document.

For example:

 $doc->add_profile('http://microformats.org/profile/rel-tag')

This is useful for adding profile URIs declared outside the document itself
(e.g. in HTTP headers).

Returns a reference to the document.

=item C<< $doc-E<gt>assume_profile(@microformats) >>

For example:

 $doc->assume_profile(qw(hCard adr geo))

This method acts similarly to C<add_profile> but allows you to use
names of microformats rather than URIs.

Microformat names are case sensitive, and must match
HTML::Microformats::Format::Foo module names.

Returns	a reference to the document.

=item C<< $doc-E<gt>assume_all_profiles >>

This method is equivalent to calling C<assume_profile> for
all known microformats.

Returns	a reference to the document.

=back

=head2 Parsing Microformats

Generally speaking, you can skip this. The C<data>, C<json> and
C<model> methods will automatically do this for you.

=over 4

=item C<< $doc-E<gt>parse_microformats >>

Scans through the document, finding microformat objects.

On subsequent calls, does nothing (as everything is already parsed).

Returns	a reference to the document.

=item C<< $doc-E<gt>clear_microformats >>

Forgets information gleaned by C<parse_microformats> and thus allows
C<parse_microformats> to be run again. This is useful if you've modified
or added some profiles between runs of C<parse_microformats>.

Returns	a reference to the document.

=back

=head2 Retrieving Data

These methods allow you to retrieve the document's data, and do things
with it.

=over 4

=item C<< $doc-E<gt>objects($format); >>

$format is, for example, 'hCard', 'adr' or 'RelTag'.

Returns a list of objects of that type. (If called in scalar context,
returns an arrayref.)

Each object is, for example, an HTML::Microformat::hCard object, or an
HTML::Microformat::RelTag object, etc. See the relevant documentation
for details.

=item C<< $doc-E<gt>all_objects >>

Returns a hashref of data. Each hashref key is the name of a microformat
(e.g. 'hCard', 'RelTag', etc), and the values are arrayrefs of objects.

Each object is, for example, an HTML::Microformat::hCard object, or an
HTML::Microformat::RelTag object, etc. See the relevant documentation
for details.

=item C<< $doc-E<gt>json(%opts) >>

Returns data roughly equivalent to the C<all_objects> method, but as a JSON
string.

%opts is a hash of options, suitable for passing to the L<JSON>
module's to_json function. The 'convert_blessed' and 'utf8' options are
enabled by default, but can be disabled by explicitly setting them to 0, e.g.

  print $doc->json( pretty=>1, canonical=>1, utf8=>0 );

=item C<< $doc-E<gt>model >>

Returns data as an RDF::Trine::Model, suitable for serialising as
RDF or running SPARQL queries.

=item C<< $object-E<gt>serialise_model(as =E<gt> $format) >> 

As C<model> but returns a string.

=item C<< $doc-E<gt>add_to_model($model) >>

Adds data to an existing RDF::Trine::Model.

Returns a reference to the document.

=back

=head2 Utility Functions

=over 4

=item C<< HTML::Microformats-E<gt>modules >>

Returns a list of Perl modules, each of which implements a specific
microformat.

=item C<< HTML::Microformats-E<gt>formats >>

As per C<modules>, but strips 'HTML::Microformats::Format::' off the
module name, and sorts alphabetically.

=back

=head1 WHY ANOTHER MICROFORMATS MODULE?

There already exist two microformats packages on CPAN (see L<Text::Microformat>
and L<Data::Microformat>), so why create another?

Firstly, HTML::Microformats isn't being created from scratch. It's actually a
fork/clean-up of a non-CPAN application (Swignition), and in that sense
predates Text::Microformat (though not Data::Microformat).

It has a number of other features that distinguish it from the existing
packages:

=over 4

=item * It supports more formats.

HTML::Microformats supports hCard, hCalendar, rel-tag, geo, adr,
rel-enclosure, rel-license, hReview, hResume, hRecipe, xFolk, XFN,
hAtom, hNews and more.

=item * It supports more patterns.

HTML::Microformats supports the include pattern, abbr pattern, table cell
header pattern, value excerpting and other intricacies of microformat parsing
better than the other modules on CPAN.

=item * It offers RDF support.

One of the key features of HTML::Microformats is that it makes data
available as RDF::Trine models. This allows your application to benefit
from a rich, feature-laden Semantic Web toolkit. Data gleaned from
microformats can be stored in a triple store; output in RDF/XML or
Turtle; queried using the SPARQL or RDQL query languages; and more.

If you're not comfortable using RDF, HTML::Microformats also makes
all its data available as native Perl objects.

=back

=head1 BUGS

Please report any bugs to L<http://rt.cpan.org/>.

=head1 SEE ALSO

L<HTML::Microformats::Documentation::Notes>.

Individual format modules:

=over 4

=item * L<HTML::Microformats::Format::adr>

=item * L<HTML::Microformats::Format::figure>

=item * L<HTML::Microformats::Format::geo>

=item * L<HTML::Microformats::Format::hAtom>

=item * L<HTML::Microformats::Format::hAudio>

=item * L<HTML::Microformats::Format::hCalendar>

=item * L<HTML::Microformats::Format::hCard>

=item * L<HTML::Microformats::Format::hListing>

=item * L<HTML::Microformats::Format::hMeasure>

=item * L<HTML::Microformats::Format::hNews>

=item * L<HTML::Microformats::Format::hProduct>

=item * L<HTML::Microformats::Format::hRecipe>

=item * L<HTML::Microformats::Format::hResume>

=item * L<HTML::Microformats::Format::hReview>

=item * L<HTML::Microformats::Format::hReviewAggregate>

=item * L<HTML::Microformats::Format::OpenURL_COinS>

=item * L<HTML::Microformats::Format::RelEnclosure>

=item * L<HTML::Microformats::Format::RelLicense>

=item * L<HTML::Microformats::Format::RelTag>

=item * L<HTML::Microformats::Format::species>

=item * L<HTML::Microformats::Format::VoteLinks>

=item * L<HTML::Microformats::Format::XFN>

=item * L<HTML::Microformats::Format::XMDP>

=item * L<HTML::Microformats::Format::XOXO>

=back

Similar modules:
L<RDF::RDFa::Parser>,
L<HTML::HTML5::Microdata::Parser>,
L<XML::Atom::Microformats>,
L<Text::Microformat>,
L<Data::Microformats>.

Related web sites:
L<http://microformats.org/>, L<http://www.perlrdf.org/>.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

=head1 COPYRIGHT AND LICENCE

Copyright 2008-2012 Toby Inkster

This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=head1 DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.