/ 
Data-Identifier-v0.04
River stage one • 1 direct dependent • 1 total dependent
/ Data::Identifier

NAME

Data::Identifier - format independent identifier object

VERSION

version v0.04

SYNOPSIS

use Data::Identifier;

my Data::Identifier $id = Data::Identifier->new(uuid => 'ddd60c5c-2934-404f-8f2d-fcb4da88b633');
my Data::Identifier $id = Data::Identifier->new(oid => '2.1.0.1.0');

my Data::Identifier $custom_type = Data::Identifier->new(uuid => ...);
my Data::Identifier $id = Data::Identifier->new($custom_type => '123abc');

my Data::Identifier $type = $id->type;
my $raw = $id->id;

my $uuid = $id->uuid;
my $oid  = $id->oid;
my $uri  = $id->uri;
my $ise  = $id->ise;

This module provides an common interface to identifiers of different types. Each identifier stores both it's raw value (called id) and it's type (type).

Note: Validation on the raw identifier value may or may not be performed depending on the type. The level of validation this module can do is limited by it's knowledge about the type as well as performance aspects. This module may therefore reject invalid values. But it is not safe to assume that it will reject all invalid values.

Note: This module performs basic deduplication and normalisation. This means that you might not always get back exactly the identifier you passed in but an equivalent one. Also note that deduplication is done with performance in mind. This means that there is no guarantee for two equal identifiers to become deduplicated. See also "register".

METHODS

new

my Data::Identifier $identifier = Data::Identifier->new($type => $id, %opts);

Creates a new identifier.

$type needs to be a Data::Identifier, a well known name, a UUID, wellknown, ise, or from.

If it is an UUID a type is created as needed.

If it is ise it is parsed as uuid, oid, or uri according to it's format.

If it is wellknown it refers to an identifier from the well known list.

If it is from then $id should refer to an object of some kind that should be converted to identifier. In this case not all options might be supported. Currently it is possible to convert from: Data::Identifier, Data::URIID::Colour, Data::URIID::Service, Data::URIID::Result, Data::TagDB::Tag, and Business::ISBN. If $id is not a reference it is parsed as with ise.

The following type names are currently well known:

uuid

An UUID.

oid

An OID.

uri

An URI.

wd

An wikidata identifier (Q, P, or L).

gtin

An GTIN (or EAN).

iban

An IBAN (International Bank Account Number).

bic

A BIC (Business Identifier Code).

doi

A doi (digital object identifier).

The following options are supported:

validate

A regex that should be used to validate identifiers if this identifier is used as a type.

namespace

The namespace used by a type. Must be a Data::Identifier or an ISE. Must also resolve to an UUID.

displayname

The name as to be returned by "displayname". Must be a scalar string value or a code reference that returns a scalar string. If it is a code reference the identifier object is passed as $_[0].

wellknown

my @wellknown = Data::Identifier->wellknown;

Returns a list with all well known identifiers.

This is mostly useful to prime a database.

type

my Data::Identifier $type = $identifier->type;

Returns the type of the identifier.

id

my $id = $identifier->id;

Returns the raw id of the identifier.

uuid, oid, uri, sid

my $uuid = $identifier->uuid( [ %opts ] );
my $oid  = $identifier->oid( [ %opts ] );
my $uri  = $identifier->uri( [ %opts ] );
my $sid  = $identifier->sid( [ %opts ] );

Return the UUID, OID, URI, or SID (small-identifier) of the current identifier or die if no identifier of that type is known nor can be calculated.

The following options (all optional) are supported:

default

The default value to return if no other value is available. This can be set to undef to change the method from dieing in failture to returning undef.

no_defaults

If set true do not try to generate a matching identifier. Note: This does not apply to sid() as small-identifiers cannot be generated. For sid() the option is ignored.

ise

my $ise = $identifier->ise( [ %opts ] );

Returns the ISE (UUID, OID, or URI) for the current identifier or die if no ISE is known nor can be calculated.

Supports all options also supported by "uuid", "oid", and "uri".

namespace

my Data::Identifier $namespace = $identifier->namespace;

Gets the namespace for the type $identifier or dies. This call is only valid for identifiers that are types.

register

$identifier->register;

Registers the identifier for deduplication. This can be used to register much used identifiers and types early in an application to increase performance. However, note that once registered an identifier object is cached for the life time of the process.

userdata

my $value = $identifier->userdata(__PACKAGE__, $key);
$identifier->userdata(__PACKAGE__, $key => $value);

Get or set user data to be used with this identifier. The data is stored using the given $key. The package of the caller is given to provide namespaces for the userdata, so two independent packages can use the same $key.

The meaning of $key, and $value is up to __PACKAGE__.

displayname

my $displayname = $identifier->displayname( [ %opts ] );

Returns a display name suitable to display to the user. This function always returns a string. This is mostly for compatibility with Data::TagDB::Tag.

The following options (all optional) are supported:

default

The default value to return if no other value is available. This can be set to undef to let this method return undef (not die).

no_defaults

If set true do not try to use any identifier or other fallback as displayname.

displaycolour, icontext, description

my $displaycolour = $identifier->displaycolour( [ %opts ] );
my $icontext      = $identifier->icontext( [ %opts ] );
my $description   = $identifier->description( [ %opts ] );

These functions always return undef. They are for compatibility with Data::TagDB::Tag.

The following options (all optional) are supported:

default

The default value to return if no other value is available (which is always the case). This is for compatibility with "displayname" and implementations of other packages.

no_defaults

This option is accepted but ignored. This is for compatibility with "displayname" and implementations of other packages.

AUTHOR

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

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)