NAME

XML::Loy::XRD - Extensible Resource Descriptor Extension

SYNOPSIS

use XML::Loy::XRD;

# Create new document
my $xrd = XML::Loy::XRD->new;

# Set subject and add alias
$xrd->subject('http://sojolicious.example/');
$xrd->alias('https://sojolicious.example/');

# Add properties
$xrd->property(describedBy => '/me.foaf' );
$xrd->property(private => undef);

# Add links
$xrd->link(lrdd => {
  template => '/.well-known/webfinger?resource={uri}'
});

print $xrd->to_pretty_xml;

# <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
# <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"
#      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
#   <Subject>http://sojolicious.example/</Subject>
#   <Alias>https://sojolicious.example/</Alias>
#   <Link rel="lrdd"
#         template="/.well-known/webfinger?resource={uri}" />
#   <Property type="describedby">/me.foaf</Property>
#   <Property type="private"
#             xsi:nil="true" />
# </XRD>

print $xrd->to_json;

# {"subject":"http:\/\/sojolicious.example\/",
# "aliases":["https:\/\/sojolicious.example\/"],
# "links":[{"rel":"lrdd",
# "template":"\/.well-known\/webfinger?resource={uri}"}],
# "properties":{"private":null,"describedby":"\/me.foaf"}}

DESCRIPTION

XML::Loy::XRD is a XML::Loy base class for handling Extensible Resource Descriptor documents with JRD support.

This code may help you to create your own XML::Loy extensions.

METHODS

XML::Loy::XRD inherits all methods from XML::Loy and implements the following new ones.

new

# Empty document
my $xrd = XML::Loy::XRD->new;

# New document by XRD
$xrd = XML::Loy::XRD->new(<<'XRD');
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Subject>http://sojolicious.example/</Subject>
  <Alias>https://sojolicious.example/</Alias>
  <Link rel="lrdd"
        template="/.well-known/webfinger?resource={uri}" />
  <Property type="describedby">/me.foaf</Property>
  <Property type="private"
            xsi:nil="true" />
</XRD>
XRD

print $xrd->link('lrdd')->attr('template');

# New document by JRD
my $jrd = XML::Loy::XRD->new(<<'JRD');
{"subject":"http:\/\/sojolicious.example\/",
"aliases":["https:\/\/sojolicious.example\/"],
"links":[{"rel":"lrdd",
"template":"\/.well-known\/webfinger?resource={uri}"}],
"properties":{"private":null,"describedby":"\/me.foaf"}}
JRD

print join ', ', $jrd->alias;

Create a new XRD document object. Beside the accepted input of XML::Loy::new, it can also parse JRD input.

alias

$xrd->alias(
  'https://sojolicious.example/',
  'https://sojolicious.example'
);
my @aliases = $xrd->alias;

Adds multiple aliases to the xrd document or returns an array of aliases.

Note: This is an experimental method and may be changed in further versions.

expired

if ($xrd->expired) {
  print "Don't use this document anymore!"
};

Returns a true value, if the document has expired based on the value of <Expires />, otherwise returns false.

expires

$xrd->expires('1264843800');
# or
$xrd->expires('2010-01-30T09:30:00Z');

print $xrd->expires->to_string;

Set an expiration date or get the expiration date as a XML::Loy::Date::RFC3339 object.

This method is experimental and may return another object with a different API!

filter_rel

my $new_xrd = $xrd->filter_rel(qw/lrdd author/);
$new_xrd = $xrd->filter_rel('lrdd author');
$new_xrd = $xrd->filter_rel(['lrdd', 'author']);

# New XRD without any link relations
$new_xrd = $xrd->filter_rel;

Returns a cloned XRD document, with filtered links based on their relations. Accepts an array, an array reference, or a space separated string describing the relation types. See WebFinger for further information.

This method is experimental and may change without warnings!

link

# Add links
my $link = $xrd->link(profile => '/me.html');

$xrd->link(hcard => {
  href => '/me.hcard'
})->add(Title => 'My hcard');

# Get links
print $xrd->link('lrdd')->attr('href');

# use Mojo::DOM remove method
$xrd->link('hcard')->remove;

Adds links to the xrd document or retrieves them. Accepts the relation as a scalar and for adding either an additional hash reference containing the attributes, or a scalar value referring to the href attribute.

property

# Add properties
$xrd->property(created => 'today');
my $prop = $xrd->property(private => undef);
print prop->text;

# Get properties
my $prop = $xrd->property('created');
print prop->text;

# use Mojo::DOM remove method
$xrd->property('private')->remove;

Adds properties to the xrd document or retrieves them. To add empty properties, undef has to be passed as the property's value.

subject

$xrd->subject('http://sojolicious.example/');
my $subject = $xrd->subject;

Sets the subject of the xrd document or returns it.

to_json

print $xrd->to_json;

Returns a JSON string representing a JRD document.

MIME-TYPES

When loaded as a base class, XML::Loy::XRD makes the mime-type application/xrd+xml available.

DEPENDENCIES

Mojolicious.

AVAILABILITY

https://github.com/Akron/XML-Loy

COPYRIGHT AND LICENSE

Copyright (C) 2011-2021, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the same terms as Perl.

cpanm XML::Loy

perl -MCPAN -e shell
install XML::Loy