Source

p5-xml-atom-microformats / README

NAME
    XML::Atom::Microformats - parse microformats in Atom feeds

SYNOPSIS
     use XML::Atom::Microformats;
 
     my $feed = HTML::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);

VERSION
    0.00_02

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 pages 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::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.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.