NAME
    HTTP::LRDD - link-based resource descriptor discovery

SYNOPSIS
     use HTTP::LRDD;
 
     my $lrdd        = HTTP::LRDD->new;
     my @descriptors = $lrdd->discover($resource);
     foreach my $descriptor (@descriptors)
     {
       my $description = $lrdd->parse($descriptor);
       # $description is an RDF::Trine::Model
     }

VERSION
    0.101

DESCRIPTION
    Note: the LRDD specification has ceased to be, with some parts being
    merged into the host-meta Internet Draft. This CPAN module will go in
    its own direction, bundling up best-practice techniques for discovering
    descriptors for a given URI.

  Import Routine
    "use HTTP::LRDD (@predicates);"
        When importing HTTP::LRDD, you can optionally provide a list of
        predicate URIs (i.e. the URIs which rel values expand to). This may
        also include IANA-registered link types, which are short tokens
        rather than full URIs.

        If you do not provide a list of predicate URIs, then a sensible
        default set is used.

  Constructors
    "HTTP::LRDD->new(@predicates)"
        Create a new LRDD discovery object using the given predicate URIs.
        If @predicates is omitted, then the predicates passed to the import
        routine are used instead.

    "HTTP::LRDD->new_strict"
        Create a new LRDD discovery object using the 'describedby' and
        'lrdd' IANA-registered predicates.

    "HTTP::LRDD->new_default"
        Create a new LRDD discovery object using the default set of
        predicates ('describedby', 'lrdd', 'xhv:meta' and 'rdfs:seeAlso').

  Public Methods
    "$lrdd->discover($resource_uri)"
        Discovers a descriptor for the given resource; or if called in a
        list context, a list of descriptors.

        A descriptor is a resource that provides a description for
        something. So, if the given resource URI was the web address for an
        image, then the descriptor might be the web address for a metadata
        file about the image. If the given URI was an e-mail address, then
        the descriptor might be a profile document for the person to whom
        the address belongs.

        The following sources are checked (in order) to find links to
        descriptors.

        *   HTTP response headers ("Link" header; "303 See Other" status)

        *   HTTP response message (RDF or RDFa)

        *   https://HOSTNAME/.well-known/host-meta

        *   http://HOSTNAME/.well-known/host-meta

        If none of the above is able to yield a link to a descriptor, then
        the resource URI itself may be returned if it is in RDF or RDFa
        format (i.e. potentially self-describing).

        There is no guaranteed file format for the descriptor, but it is
        usually RDF, POWDER XML or XRD.

        This method can also be called without an object (as a class method)
        in which case, a temporary object is created automatically using
        "new".

    "$lrdd->parse($descriptor_uri)"
        Parses a descriptor in XRD or RDF (RDF/XML, RDFa, Turtle, etc).

        Returns an RDF::Trine::Model or undef if unable to process.

        This method can also be called without an object (as a class method)
        in which case, a temporary object is created automatically using
        "new".

    "$lrdd->process($resource_uri)"
        Performs the equivalent of "discover" and "parse" in one easy step.

        Calls "discover" in a non-list context, so only the first descriptor
        is used.

    "$lrdd->process_all($resource_uri)"
        Performs the equivalent of "discover" and "parse" in one easy step.

        Calls "discover" in a list context, so multiple descriptors are
        combined into the resulting graph.

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

SEE ALSO
    XRD::Parser, WWW::Finger, RDF::TrineShortcuts.

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

