/ 
Data-Identifier-v0.17
River stage one • 8 direct dependents • 8 total dependents
/ Data::Identifier::Generate

NAME

Data::Identifier::Generate - format independent identifier object

VERSION

version v0.17

SYNOPSIS

use Data::Identifier::Generate;

This module allows generation of instances of Data::Identifier from common non-identifier values. For generation of UUIDs from identifier values see "uuid" in Data::Identifier. The generated identifiers are of type UUID.

This can be used standalone if only an identifier for the given value is needed or as part of a generation logic.

The methods of this module might perform (limited and quick) checks for validity of the given data. If a request is found invalid the method dies. However it is in the responsibility of the caller to ensure the data is correct. Any checks by this module are solely meant as a last resort to finding obvious errors.

The method may also perform auto-correction. This may for example the case a obsolete value is passed and a more current value is known.

See also: Data::TagDB::Factory.

METHODS

integer

my Data::Identifier $identifier = Data::Identifier::Generate->integer($int [, %opts] );

Creates an identifier for the given integer.

The following options (all optional) are supported:

displayname

The displayname as to be used for the identifier. This is the same as defined by "new" in Data::Identifier.

Defaults to the passed number.

unicode_character

my Data::Identifier $identifier = Data::Identifier::Generate->unicode_character($type => $request [, %opts] );
# e.g.:
my Data::Identifier $identifier = Data::Identifier::Generate->unicode_character(unicode => 0x1F981);
# or:
my Data::Identifier $identifier = Data::Identifier::Generate->unicode_character(unicode => 'U+1F981');

Creates an identifier for the given unicode character.

The following types are supported:

unicode

The unicode code point as a number (e.g. 0x1F981) or as in the standard format (e.g. 'U+1F981').

ascii

The US-ASCII code point (e.g. 65).

raw

A perl string with exactly one character. The character is

The following options (all optional) are supported:

allow_special

If special characters are allowed. This setting is a protection against false results, specifically with REPLACEMENT CHARACTER and similar characters.

Defaults to false.

displayname

The displayname as to be used for the identifier. This is the same as defined by "new" in Data::Identifier.

Defaults to the data from the request.

colour

my Data::Identifier $identifier = Data::Identifier::Generate->colour($colour [, %opts ] );
# e.g.:
my Data::Identifier $identifier = Data::Identifier::Generate->colour('#decc9c');

Generates an identifier for a given colour. Currently the colour must be given as a string in form #RRGGBB.

The following options (all optional) are supported:

displayname

The displayname as to be used for the identifier. This is the same as defined by "new" in Data::Identifier.

Defaults to the data from the request.

date

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

Generates an identifier for a given date.

The date must be one of the following: A string (in form YYYYZ, YYYY-MMZ, or YYYY-MM-DDZ) representing a gregorian date, a number representing the time as a UNIX epoch (see "time" in perlfunc, "$^T" in perlvar), a blessed object that provides epoch such as DateTime, or the special values now or today.

Note: When dates are passed in string/ISO 8601 format they must refer to UTC and have the correct suffix Z. If you have timestamps in other timezones than UTC convert them to an epoch first and pass them as epoch. The standard module DateTime might be of help with that. Just appending Z to timestamps in local time or passing timestamps without the Z suffix will result in wrong results!

Note: This function currently only supports 4-digit gregorian dates. Therfore only values for the years 1583 to 9999 (inclusive) can be calculated.

Also if the value is passed in anything but the string form the limits of "gmtime" in perlfunc apply. This also means that this function is year 2038 safe if gmtime is. In this case the range is also limited to the year 2999 to detect common programming errors (the time passed as milliseconds rather than seconds).

The following options (all optional) are supported:

displayname

The displayname as to be used for the identifier. This is the same as defined by "new" in Data::Identifier.

Defaults to the passed date formatted as ISO 8601.

precision

The precision to use for the identifier. One of year, month, and day.

Defaults to the highest possible precision available with the given date.

multiplicity

my Data::Identifier $identifier = Data::Identifier::Generate->multiplicity($subtype => $number, %opts);
# e.g.:
my Data::Identifier $identifier = Data::Identifier::Generate->multiplicity(minimum => 5);

(since v0.13)

Generates an identifier for a specific number of entities to be used with e.g. the tagpool-tagged-as relation. This type of identifier should be avoided if a better relation can be used.

There are currently two subtypes defined:

total

The total number of entities in a given work. This includes background characters and entities often not noticed (e.g. flies).

It its strongly recommended not to use this type unless the value can be proven. It is recommended to use minimum when in doubt.

minimum

The minimum number of entities in a given work. It is safe to set this to a lower value than the actual value. E.g. tag a file with this type of identifier and only count foreground characters.

The following options (all optional) are supported:

displayname

The displayname as to be used for the identifier. This is the same as defined by "new" in Data::Identifier.

Defaults to a name from a build in list or $number if no entry is found.

gte_simple

my Data::Identifier $identifier = Data::Identifier::Generate->gte_simple($profile => $request, %opts);

(since v0.13)

Generates an identifier using simple GTE rules. This method must not be called in list context.

This is an experimental method. It may be changed, renamed, or removed without notice.

The profile is a hashref with the parameters for the profile or the name of a well known profile or an Data::Identifier of a well known profile. Other types might also be supported.

Currently this module does not define any well known profiles.

If it is a hashref it contains the following keys:

case_folding

Optional. The case folding rule to use. One of undef or 'none', 'upper', and 'lower'. This is applied to the request as first part of normalisation. See also "uc" in perlfunc, "lc" in perlfunc, and "fc" in perlfunc.

Defaults to undef.

generator

Optional. The same as the generator option of "generic".

namespace

Required. The same as the namespace option of "generic".

order

Required. The normal order of the subelements. This is used as part of normalisation. The value is a string with each character being a single element.

strip_slash

Optional. Strip all slashes (/) from the request as part of normalisation.

Defaults to false.

strip_spaces

Optional. Strip all spaces (\s) from the request as part of normalisation.

Defaults to false.

The following, all optional, options are supported:

info

This is an experimental option. It holds a hashref that is used to pass information on the generated identifier back to the caller.

generic

my Data::Identifier $identifier = Data::Identifier::Generate->generate(%opts);

This provides a most generic interface for generation. It should be avoided in in favour of more specific ones.

The following options are supported:

displayname

The displayname as to be used for the identifier. This is the same as defined by "new" in Data::Identifier.

This option is optional.

generator

The identifier for this generator. This is the same as defined by "new" in Data::Identifier.

This option is optional.

input

The raw input for the generator. Must be a string of raw bytes.

This option is to be avoided in favour of request, Exactly one of input or request must be given.

namespace

The namespace to use. Must be an Data::Identifier or raw UUID.

This option is optional if type is passed with the type holding an namespace. See also "namespace" in Data::Identifier.

request

The request to be passed to the generator. The type and range of this value depends on style which must be provided longside request.

Exactly one of request or input must be given.

style

The style to be used by the generator.

Currently supported: integer-based, id-based, name-based, tag-based, tagcombiner, colour.

This option is required unless input is provided.

For tag-based the request must be a raw UUID, a Data::Identifier, or anything "new" in Data::Identifier takes via from.

For tagcombiner the request must be an array reference with each element of a type supported by tag-based. The array must also include at least two distinct identifiers.

type

The type of the identifier to be passed via request.

Must be a Data::Identifier.

This is optional.

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)