NAME

Data::Identifier - format independent identifier object

VERSION

version v0.07

SYNOPSIS

use Data::Identifier;
# or:
use Data::Identifier {option => value, ...};

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".

This package inherits from Data::Identifier::Interface::Known.

OPTIONS

The following options are supported. Some are marked as experimental.

disable

Note: This is an experimental option. It may be changed, renamed, or removed without notice.

This option allows to disable a feature. This is a global setting, and therefore should only be used at the top level code.

In order for this to be most effective this should be used in the top level code before any other module is use-ed or require-ed that makes use of this module.

This setting takes an arrayref of strings or a single string that is a comma separated list.

Currently the following features can be disabled:

oid

Support for OID. This removes the "oid" function from this package, removes internal OID based caches, and parts of the OID detection and normalisation logic.

However this improves the speed of "register" and some others significantly.

This feature should only be disabled if you're sure you will not use OIDs in your code.

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).
fc: An FactGrid 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].

random

my Data::Identifier $identifier = Data::Identifier->random([ %opts ]);

Generate a new random identifier. This method will die on error.

The following options (all optional) are supported:

displayname

The same as the option of the same name in "new". See also "displayname".

sources

The backend data sources to use for generation of the identifier. This is an array reference with the names of the modules in order of preference (most preferred first).

Defaults to a list of high quality sources.

Currently supported are at least: Crypt::URandom, UUID4::Tiny, Math::Random::Secure, UUID::URandom, UUID::Tiny::Patch::UseMRS, UUID::Tiny (low quality).

type

The type to generate a random identifier in. A Data::Identifier or one of the special values uuid or ise.

known

my @list = Data::Identifier->known($class [, %opts ] );

This module implements "known" in Data::Identifier::Interface::Known. See there for details.

Supported classes:

wellknown

Returns a list with all well known identifiers.

This is useful to prime a database.

registered

Returns the list of all currently registered identifiers.

:all

Returns the list of all currently known identifiers.

wellknown

my @wellknown = Data::Identifier->wellknown(%opts);

This is an alias for:

my @wellknown = Data::Identifier->known('wellknown', %opts);

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".

as

my $res = $identifier->as($as, %opts);
# or:
my $res = $identifier->Data::Identifier::as($as, %opts); # $identifier is an alien type

This method converts the given identifier to another type of object.

$as must be a name of the package (containing :: or starting with an uppercase letter), or one of the special values.

Currently the following packages are supported: URI, Data::Identifier, Data::URIID::Result, Data::URIID::Service, Business::ISBN. Other packages might be supported. Packages need to be installed in order to be supported. Also some packages need special options to be passed to be available.

The folliwng special values are supported: uuid, oid, uri, sid, ise, and raw. All but raw are aliases to the corresponding functions. raw is an alias for the type set with the rawtype option (see below).

If $identifier is or may not be an Data::Identifier this method can be called like $identifier->Data::Identifier::as($as...). In that case $identifier is parsed as with from in "new".

If $identifier is a $as (see also rawtype below) then $identifier is returned as-is, even if $as would not be supported otherwise.

The following options (all optional) are supported:

default: Same as in "uuid".
no_defaults: Same as in "uuid".
rawtype: If $as is given as raw then this value is used for $as. This can be used to ease implementation of other methods that are required to accept raw.
extractor: An instance of Data::URIID. This is used to create instances of related packages such as Data::URIID::Result.

eq

my $bool = $identifier->eq($other); # $identifier must be non-undef
# or:
my $bool = Data::Identifier::eq($identifier, $other); # $identifier can be undef

Compares two identifiers to be equal.

If both identifiers are undef they are considered equal.

If $identifier or $other is not an instance of Data::Identifier or undef then it is checked against the list of well known identifiers (see "new"). If it has still no match "new" with the virtual type from is used.

cmp

my $val = $identifier->cmp($other); # $identifier must be non-undef
# or:
my $val = Data::Identifier::cmp($identifier, $other); # $identifier can be undef

Compares the identifiers similar to cmp. This method can be used to order identifiers. To check for them to be equal see "eq".

The parameters are parsed the same way as "eq".

If this method is used for sorting the exact resulting order is not defined. However:

The order is stable
Identifiers are ordered by type first
If the all identifiers have the same type this method tries to be smart about ordering (ordering numeric values correctly).
The order is the same for $a->cmp($b) as for - $b->cmp($a).

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 is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

To install Data::Identifier, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Data::Identifier

CPAN shell

perl -MCPAN -e shell
install Data::Identifier

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

OPTIONS

disable

METHODS

new

random

known

wellknown

type

id

uuid, oid, uri, sid

ise

as

eq

cmp

namespace

register

userdata

displayname

displaycolour, icontext, description

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions