/ 
Data-URIID-v0.17
River stage one • 2 direct dependents • 2 total dependents
/ Data::URIID::Service

NAME

Data::URIID::Service - Extractor for identifiers from URIs

VERSION

version v0.17

SYNOPSIS

use Data::URIID;

my $extractor = Data::URIID->new;
my $result = $extractor->lookup( $URI );
my $service = $result->attribute('service');

my $name = $service->name;
my $ise = $service->ise;

This module represents a single service.

This package inherits from Data::URIID::Base.

METHODS

name

my $name = $service->name;

Returns the name of this service.

online

my $online = $service->online( [ $new_value ] );

Gets or sets the online status of the service. If this value is false no online operations are permitted. In addition to this value being true the online value for the extractor need to be true.

See also "extractor", "online" in Data::URIID.

setting

my $value = $service->setting( $setting[, $new_value ] );

Gets or sets the setting $setting the of the service.

The available settings depend on the service. This method may or may not die when an invalid setting or an invalid value is provided.

Setting an invalid value may result in failures when this service is being used.

Universally available settings

network_deny: Denies network access (i.e. online lookups) for this service.

register_service

use Data::URIID::Service;

Data::URIID::Service->register_service($id, %opts);

(since v0.17, experimental)

Registers a new service.

Note: This is an highly experimental method. It may be changed or replaced, or removed with future versions.

The service is identified by it's identifier $id (likely a Data::Identifier of type uuid) which must be globally unique. The method will die if it finds any problem with the identifier.

Note: The identifier given here identifies a specific service, not a type of service. So if there are more than one instances of a given service each must have it's own unique identifier.

The following, all optional, options are supported:

displayname

(experimental) Used as fallback displayname if $id does not provide one in some cases.

id_templates

An arrayref containing templates used to generate URIs from identifiers.

digest_templates

An arrayref containing templates used to generate URIs from digests.

id_patterns

An arrayref containing patterns used to extract identifiers from URIs.

Templates

Each template contains a hashref with the following keys:

id_type

(only for id templates) A filter for identifier types. This works on the names of the identifier types (e.g. uuid).

digest

(only for digest templates) A filter for digest algorithm types. This works on the algorithm names in universal tag format (e.g. sha-1-160).

template

The actual template. This might be a single string in an undefined format or an instance of URI::Template or URI::Template::Restrict.

filter

A filter that is applied to the value (the identifier or the digest value).

action

A filter for which actions this template applies. This works on the names of the actions (e.g. info).

options

Additional template options. No options are currently defined by this documentation.

Filter

A filter in the sense of templates is a regex (quoted using qr//), or an arrayref with exact values to match or a single string that is split into exact values using space and comma as seperator.

Template variables

The following variables are supported by templates (more may be supported):

type

The type (identifier type name e.g. uuid or digest algorithm name e.g. sha-3-512).

value

The identifier or digest value.

id

The identifier.

digest

The digest.

Patterns

Each pattern is a hashref with the following keys:

scheme

(required) The URI scheme to match. E.g. https.

Note: http might be considered an invalid valid.

host

(optional) The host to match as a string or regex (qr//).

path

(optional) The path to match as a string or rexgex (qr//).

type

(optional) The type of the identifier (e.g. uuid).

action

(optional) The action this matches (e.g. info).

match

A method (coderef) that is called to match the URI.

The method is called with the Data::URIID::Result as first argument, the URI (as URI) as second argument, and this hashref (the pattern) as thrid. It must return a hash (not a hashref) containing at least an id element. If a empty hash is returned a no-match condition is assumed.

It must return an element id that is a Data::Identifier of the found match. It may also return an element action that provides the name of the action.

KNOWN/SUPPORTED SERVICES

The following is a non-complete list of services for which lookups (online or offline) are supported. For a complete list of known services see "known" in Data::URIID.

wikidata and wikipedia

Wikidata is a large collection of machine readable data from all categories. It can act as a central connecting point for several types of identifiers and services. It also provides Wikipedia pages for the given subject.

The wikipedia services is only used for online lookups if a Wikipedia page is used as an input. It does not provide lookup from identifiers to Wikipedia links.

In many cases you want to enable online lookups for both wikidata, and wikipedia. This is specifically true if you want to work with very different services at once.

You commonly don't need to enable online lookups if all the services you're interested in use the same type of identifiers.

osm and overpass

The osm service is mainly used to lookup from OpenStreetMap identifiers to other identifiers as well as attributes. While the overpass service is mostly used to look up from other identifiers to OpenStreetMap identifiers.

If you work with places you most likely want to enable online lookups on those services.

factgrid

The factgrid provides information mostly on history topics. It contains a large amount of data for historical figures.

Data::URIID

This service is used to perform internal offline lookups on identifiers known to the module. It mainly provides display names for ISEs used by this module.

Data::Identifier

This service uses Data::Identifier as a data source. It can provide display names and similar for a number of common identifiers.

See also Data::Identifier::Wellknown.

AUTHOR

Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2023-2025 by Löwenfelsen UG (haftungsbeschränkt) <support@loewenfelsen.net>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)