| 1 |
NAME |
| 2 |
HTTP::Link::Parser - parse HTTP Link headers |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use HTTP::Link::Parser ':standard'; |
| 6 |
use LWP::UserAgent; |
| 7 |
|
| 8 |
my $ua = LWP::UserAgent->new; |
| 9 |
my $response = $ua->get("http://example.com/foo"); |
| 10 |
|
| 11 |
# Parse link headers into an RDF::Trine::Model. |
| 12 |
my $model = parse_links_into_model($response); |
| 13 |
|
| 14 |
# Find data about <http://example.com/foo>. |
| 15 |
my $iterator = $model->get_statements( |
| 16 |
RDF::Trine::Node::Resource->new('http://example.com/foo'), |
| 17 |
undef, |
| 18 |
undef); |
| 19 |
|
| 20 |
while ($statement = $iterator->next) |
| 21 |
{ |
| 22 |
# Skip data where the value is not a resource (i.e. link) |
| 23 |
next unless $statement->object->is_resource; |
| 24 |
|
| 25 |
printf("Link to <%s> with rel=\"%s\".\n", |
| 26 |
$statement->object->uri, |
| 27 |
$statement->predicate->uri); |
| 28 |
} |
| 29 |
|
| 30 |
DESCRIPTION |
| 31 |
HTTP::Link::Parser parses HTTP "Link" headers found in an HTTP::Response |
| 32 |
object. Headers should conform to the format described in RFC 5988. |
| 33 |
|
| 34 |
Functions |
| 35 |
To export all functions: |
| 36 |
|
| 37 |
use HTTP::Link::Parser ':all'; |
| 38 |
|
| 39 |
`parse_links_into_model($response, [$existing_model])` |
| 40 |
Takes an HTTP::Response object (or in fact, any HTTP::Message object) |
| 41 |
and returns an RDF::Trine::Model containing link data extracted from |
| 42 |
the response. Dublin Core is used to encode 'hreflang', 'title' and |
| 43 |
'type' link parameters. |
| 44 |
|
| 45 |
$existing_model is an RDF::Trine::Model to add data to. If omitted, a |
| 46 |
new, empty model is created. |
| 47 |
|
| 48 |
`parse_links_to_rdfjson($response)` |
| 49 |
Returns a hashref with a structure inspired by the RDF/JSON |
| 50 |
specification. This can be thought of as a shortcut for: |
| 51 |
|
| 52 |
parse_links_into_model($response)->as_hashref |
| 53 |
|
| 54 |
But it's faster as no intermediate model is built. |
| 55 |
|
| 56 |
`relationship_uri($short)` |
| 57 |
This function is not exported by default. |
| 58 |
|
| 59 |
It may be used to convert short strings identifying relationships, |
| 60 |
such as "next" and "prev", into longer URIs identifying the same |
| 61 |
relationships, such as "http://www.iana.org/assignments/relation/next" |
| 62 |
and "http://www.iana.org/assignments/relation/prev". |
| 63 |
|
| 64 |
If passed a string which is a URI already, simply returns it as-is. |
| 65 |
|
| 66 |
Internal Functions |
| 67 |
These are really just internal implementations, but you can use them if |
| 68 |
you like. |
| 69 |
|
| 70 |
`parse_links_to_list($response)` |
| 71 |
This function is not exported by default. |
| 72 |
|
| 73 |
Returns an arrayref of hashrefs. Each hashref contains keys |
| 74 |
corresponding to the link parameters of the link, and a key called |
| 75 |
'URI' corresponding to the target of the link. |
| 76 |
|
| 77 |
The 'rel' and 'rev' keys are arrayrefs containing lists of |
| 78 |
relationships. If the Link used the short form of a registered |
| 79 |
relationship, then the short form is present on this list. Short forms |
| 80 |
can be converted to long forms (URIs) using the `relationship_uri` |
| 81 |
function. |
| 82 |
|
| 83 |
The structure returned by this function should not be considered |
| 84 |
stable. |
| 85 |
|
| 86 |
`parse_single_link($link, $base, [$default_lang])` |
| 87 |
This function is not exported by default. |
| 88 |
|
| 89 |
This parses a single Link header (minus the "Link:" bit itself) into a |
| 90 |
hashref structure. A base URI must be included in case the link |
| 91 |
contains relative URIs. A default language can be provided for the |
| 92 |
'title' parameter. |
| 93 |
|
| 94 |
The structure returned by this function should not be considered |
| 95 |
stable. |
| 96 |
|
| 97 |
BUGS |
| 98 |
Please report any bugs to <http://rt.cpan.org/>. |
| 99 |
|
| 100 |
SEE ALSO |
| 101 |
<http://www.ietf.org/rfc/rfc5988.txt>. |
| 102 |
|
| 103 |
RDF::Trine, HTTP::Response, XRD::Parser, HTTP::LRDD. |
| 104 |
|
| 105 |
<http://n2.talis.com/wiki/RDF_JSON_Specification>. |
| 106 |
|
| 107 |
<http://www.perlrdf.org/>. |
| 108 |
|
| 109 |
AUTHOR |
| 110 |
Toby Inkster <[email protected]>. |
| 111 |
|
| 112 |
COPYRIGHT AND LICENCE |
| 113 |
Copyright (C) 2009-2011, 2014 by Toby Inkster |
| 114 |
|
| 115 |
Permission is hereby granted, free of charge, to any person obtaining a |
| 116 |
copy of this software and associated documentation files (the "Software"), |
| 117 |
to deal in the Software without restriction, including without limitation |
| 118 |
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
| 119 |
and/or sell copies of the Software, and to permit persons to whom the |
| 120 |
Software is furnished to do so, subject to the following conditions: |
| 121 |
|
| 122 |
The above copyright notice and this permission notice shall be included in |
| 123 |
all copies or substantial portions of the Software. |
| 124 |
|
| 125 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 126 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 127 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
| 128 |
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 129 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
| 130 |
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
| 131 |
DEALINGS IN THE SOFTWARE. |
| 132 |
|