Text::Microformat - A Microformat parser

Version 0.02

	use Text::Microformat;
	use LWP::Simple;

	# Parse a document
	my $doc = Text::Microformat->new(
	    get('http://phil.windley.org/hcard.html')
	);

	# Extract all known Microformats
	my @formats = $doc->find;

	my $hcard = shift @formats;

	# Easiest way to get a value (returns the first one found, else undef)

	my $full_name = $hcard->Get('fn');
	my $family_name = $hcard->Get('n.family-name');
	my $city = $hcard->Get('adr.locality');

	# Get the human-readable version specifically

	my $family_name = $hcard->GetH('n.family-name');

	# Get the machine-readable version specifically

	my $family_name = $hcard->GetM('n.family-name');

	# The more powerful interface (access multiple properties)

	my $family_name = $hcard->n->[0]->family_name->[0]->Value;

	# Dump to a hash

	my $hash = $hcard->AsHash;

	# Dump to YAML

	print $hcard->ToYAML, "\n";

	# Free the document and all the formats

	$doc->delete;

Text::Microformat is a Microformat parser for Perl.

Text::Microformat sports a very pluggable API, which allows not only new kinds of Microformats to be added, but also extension of the parser itself, to allow new parsing metaphors and source document encodings.

* Extracting Microformats from HTML, XHTML and XML

* Extracting Microformats from entity-encoded or CDATA sections in RSS feeds.

* The include pattern

* Microformats built from other Microformats

* hCard

* hGrant

* new($content, %opts)

Parses the string $content and creates a new Text::Microformat object.

Recognized options:

* content_type => 'text/html'

Specify the content type. Any content type containing 'html' invokes the HTML Parser, and content type containing XML invokes XML Parser. Defaults to 'text/html'. (See HTML::TreeBuilder and XML::TreeBuilder)

* find()

Returns an array of all known Microformats in the document.

* delete()

Deletes the underlying parse tree - which is required by HTML::TreeBuilder to free up memory. Behavior of Text::Microformat::Element::* objects is undefined after this method is called.

This is as easy as creating a new module in the Text::Microformat::Element::* namespace, having Text::Microformat::Element as a super-class. It will be auto-loaded by Text::Microformat.

Every Microformat element has it's own namespace auto-generated, for example:

 Text::Microformat::Element::hCard::n::family_name

So it's easy to override the default behavior of Text::Microformat::Element via inheritance.

See existing formats for hints.

This is as easy as creating a new module in the Text::Microformat::Plugin::* namespace. It will be auto-loaded by Text::Microformat. Text::Microformat has several processing phases, and uses NEXT to traverse the plugin chain.

Current processing phases are, in order of execution:

* defaults

Set default options in $c->opts

* pre_parse

Pre-parsing activities (Operations on the document source, perhaps)

* parse

Parsing - at least one plugin must parse $c->content into $c->tree

* post_parse

Post-parsing activities (E.g. the include pattern happens here)

* pre_find_formats

Before looking for Microformats

* find_formats

Populate the $c->formats array with Text::Microformat::Element objects

* post_find_formats

After looking for Microformats

A plugin may add handlers to one or more phases.

See existing plugins for hints.

* Documentation!

* Add more formats

* Add filtering options to the find() method

* Parsing and format-finding performance could definitely be improved

HTML::TreeBuilder, XML::TreeBuilder, http://microformats.org

Keith Grennan, <kgrennan at cpan.org>

Log bugs and feature requests here: http://code.google.com/p/ufperl/issues/list

Project homepage: http://code.google.com/p/ufperl/

Copyright 2007 Keith Grennan, all rights reserved.

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