/ 
HTTP-LRDD-0.101
River stage one • 1 direct dependent • 1 total dependent
/ HTTP::LRDD

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.