Provided by: libxml-atom-microformats-perl_0.002-3_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);

        use RDF::TrineShortcuts qw(rdf_query);
        my $results = rdf_query($sparql, $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; then ask for the data, as a
       Perl hashref, a JSON string, or an RDF::Trine model.

   Constructor
       "$feed = 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
       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.

       "$feed->add_profile(@profiles)", "$feed->entry_add_profile($entryid, @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" 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.

       "$feed->assume_profile(@microformats)", "$feed->entry_assume_profile($entryid, @profiles)"
           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" 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.

       "$feed->assume_all_profiles", "$feed->entry_assume_all_profiles($entryid)"
           This method is equivalent to calling "assume_profile" for all known microformats.

   Parsing Microformats
       Generally speaking, you can skip this. The "data", "json" and "model" methods will
       automatically do this for you.

       "$feed->parse_microformats"
           Scans through the feed, finding microformat objects.

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

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

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

       "$feed->objects($format)", "$feed->entry_objects($entryid, $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" is a variant to allow you to fetch data for one specific entry within
           the feed, if you know that entry's ID.

       "$feed->all_objects", "$feed->entry_all_objects($entryid)"
           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" is a variant to allow you to fetch data for one specific entry
           within the feed, if you know that entry's ID.

       "$feed->json(%opts)", "$feed->entry_json($entryid, %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" is a variant to allow you to fetch data for one specific entry within the
           feed, if you know that entry's ID.

       "$feed->model(%opts)", "$feed->entry_model($entryid, %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.

           "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.

           $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.09_04 or above is installed, then $opts{'atomowl'} will
           automatically pull in DataRSS data too.

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

BUGS

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

SEE ALSO

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

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

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT

       Copyright 2010 Toby Inkster

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