Provided by: libxml-atom-microformats-perl_0.004-2_all bug

NAME

       XML::Atom::Microformats - parse microformats in Atom content

SYNOPSIS

        use XML::Atom::Microformats;

        my $feed = XML::Atom::Microformats
           -> new_feed( $xml, $base_uri )
           -> assume_profile( qw(hCard hCalendar) );
        print $feed->json(pretty => 1);

        my $results = RDF::Query
           -> new( $sparql )
           -> execute( $feed->model );

DESCRIPTION

       The XML::Atom::Microformats module brings the functionality of HTML::Microformats to Atom
       1.0 Syndication feeds. It finds microformats embedded in the <content> elements (note: not
       <summary>) of Atom entries.

       The general pattern of usage is to create an XML::Atom::Microformats object (which
       corresponds to an Atom 1.0 feed) using the "new_feed" method; tell it which types of
       Microformat you expect to find there; then ask for the data, as a Perl hashref, a JSON
       string, or an RDF::Trine model.

   Constructor
       "XML::Atom::Microformats->new_feed($xml, $base_url)"
           Constructs a feed object.

           $xml is the Atom source (string) or an XML::LibXML::Document.

           $base_url is the feed URL, important for resolving relative URL references.

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

       XML::Atom::Microformats uses a similar mechanism. Because Atom does not have a <head>
       element, Atom <link> is used instead:

         <link rel="profile" href="http://ufs.cc/x/hcalendar" />

       These links can be used on a per-entry basis, or for the whole feed.

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

       "add_profile(@profiles)"
           Using "add_profile" you can add one or more profile URIs, and they are treated as if
           they were found on the document.

           For example:

            $feed->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).

       "entry_add_profile($entryid, @profiles)"
           "entry_add_profile" is a variant to allow you to add a profile which applies only to
           one specific entry within the feed, if you know that entry's ID.

       "assume_profile(@microformats)"
           For example:

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

           This method acts similarly to "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.

       "entry_assume_profile($entryid, @profiles)"
           "entry_assume_profile" is a variant to allow you to add a profile which applies only
           to one specific entry within the feed, if you know that entry's ID.

       "assume_all_profiles"
           This method is equivalent to calling "assume_profile" for all known microformats.

       "entry_assume_all_profiles($entryid)"
           This method is equivalent to calling "entry_assume_profile" for all known
           microformats.

   Parsing Methods
       You can probably skip this section. The "data", "json" and "model" methods will
       automatically do this for you.

       "parse_microformats"
           Scans through the feed, finding microformat objects.

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

       "clear_microformats"
           Forgets information gleaned by "parse_microformats" and thus allows
           "parse_microformats" to be run again. This is useful if you've added some profiles
           between runs of "parse_microformats".

   Data Retrieval Methods
       These methods allow you to retrieve the feed's data, and do things with it.

       "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 relevent documentation for details.

       "entry_objects($entryid, $format)"
           "entry_objects" is a variant to allow you to fetch data for one specific entry within
           the feed, if you know that entry's ID.

       "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 relevent documentation for details.

       "entry_all_objects($entryid)"
           "entry_all_objects" is a variant to allow you to fetch data for one specific entry
           within the feed, if you know that entry's ID.

       "json(%opts)"
           Returns data roughly equivalent to the "all_objects" method, but as a JSON string.

           %opts is a hash of options, suitable for passing to the 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 $feed->json( pretty=>1, canonical=>1, utf8=>0 );

       "entry_json($entryid, %opts)"
           "entry_json" is a variant to allow you to fetch data for one specific entry within the
           feed, if you know that entry's ID.

       "model(%opts)"
           Returns data as an RDF::Trine::Model, suitable for serialising as RDF or running
           SPARQL queries. Quads are used (rather than triples) which allows you to trace
           statements to the entries from which they came.

           $opts{'atomowl'} is a boolean indicating whether or not to include data from
           XML::Atom::OWL in the returned model.  If enabled, this always includes AtomOWL data
           for the whole feed (not just for a specific entry), even if you use the "entry_model"
           method.

           If RDF::RDFa::Parser 1.096 or above is installed, then $opts{'atomowl'} will
           automatically pull in DataRSS data too.

       "entry_model($entryid, %opts)"
           "entry_model" is a variant to allow you to fetch data for one specific entry within
           the feed, if you know that entry's ID.

       "add_to_model($model, %opts)"
           Adds data to an existing RDF::Trine::Model. Otherwise, the same as "model".

       "entry_add_to_model($entry, $model, %opts)"
           Adds data to an existing RDF::Trine::Model. Otherwise, the same as "entry_model".

BUGS

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

SEE ALSO

       HTML::Microformats, XML::Atom::OWL, XML::Atom::FromOWL, RDF::RDFa::Parser.

       <http://microformats.org/>, <http://www.perlrdf.org/>.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT

       Copyright 2010-2012 Toby Inkster

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

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.