/ 
Data-Identifier-v0.30
/ Data::Identifier::Util

NAME

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

VERSION

version v0.30

SYNOPSIS

use Data::Identifier::Util;

my Data::Identifier::Util $util = Data::Identifier::Util->new;

(since v0.23)

This package contains some utility methods that are left out of Data::Identifier to keep that module slim.

This package inherits from Data::Identifier::Interface::Userdata (since v0.23), and Data::Identifier::Interface::Subobjects (since v0.23).

Note: This package may register (see "register" in Data::Identifier) some identifiers required for the provided operations. This may or may not overlap with what Data::Identifier::Wellknown registers.

METHODS

new

my Data::Identifier::Util $util = Data::Identifier::Util->new;

(since v0.23)

Creates a new instance that can be used to call the different methods.

from_bool

my Data::Identifier $identifier = $util->from_bool($bool);

(experimental since v0.30)

Returns a true or false as an identifier based on the passed boolean. The value is check for it's boolean value by perl's rules.

is_true

my $bool = $util->is_true($identifier);

(experimental since v0.30)

Returns true if the given identifier represents true (not just a true-ish value).

This implementation tries to support many different vocabularies.

Note: As this tests for true (not true-ish) values can be both not-true and not-false.

See also: "is_false".

is_false

my $bool = $util->is_false($identifier);

(experimental since v0.30)

Returns true if the identifier represents false (not just a false-ish value).

All limitations and notes of "is_true" also apply.

See also: "is_true".

pack

my $packed = $util->pack($template => $identifier);
# e.g.:
my $packed = $util->pack(sid16 => $identifier);

(since v0.23)

This method can be used to pack identifiers into a (binary) format using a template. This is similar to "pack" in perlfunc.

$identifier is a Data::Identifier, or if not is converted to one using "new" in Data::Identifier with from.

The following templates are currently supported:

{sid|sni|hdi|udi}{8|16|32}

(since v0.23)

An small-identifier, sirtx-numerical-identifier, host-defined-identifier, or user-defined-identifier packed as 8, 16, or 32 bit value (in network byte order).

4+12

(since v0.23)

An small-identifier, sirtx-numerical-identifier, host-defined-identifier, or user-defined-identifier packed in the 4 bit prefix plus 12 bit identifier format. The prefix to be used is automatically selected. This module might make better decisions if Data::Identifier::Wellknown is loaded with the corresponding classes, and/or if a Data::TagMap is given via "so_attach" in Data::Identifier::Interface::Subobjects.

uuid128

(since v0.23)

An UUID as 128 bit (16 byte).

uuidhexdash, uuidHEXDASH

(since v0.27)

An UUID in hex-and-hash format. Use uuidhexdash for lower case and uuidHEXDASH for upper case.

Data::Identifier

(experimental since v0.29)

A full Data::Identifier object. This is mostly for compatibility with other APIs.

unpack

my Data::Identifier $identifier = $util->unpack($template => $packed);
# e.g.:
my Data::Identifier $identifier = $util->unpack(sid32 => $packed);
# or:
my Data::Identifier $identifier = $util->unpack('4+12' => $packed);

(since v0.23)

This method unpacks an identifier from a (binary) format using a template. This undoes what "pack" does. The same rules apply. See there for details.

Note: As of v0.23 this module expects $packed to have the correct length. Later versions of this module may add a mode in which trailing data in $packed might be allowed.

parse_sirtx

my Data::Identifier $identifier = $util->parse_sirtx($value);

(experimental since v0.23)

This methods tries to decode the given $value as a SIRTX identifier string. This method is limited in it's capabilities in that it does not support the full syntax, as well as it does not have any database or context as a data source.

See also "tag_by_specification" in Data::TagDB with style => 'sirtx'.

This might might support more values if Data::Identifier::Wellknown is loaded with the corresponding classes, and/or if a Data::TagMap is given via "so_attach" in Data::Identifier::Interface::Subobjects.

See also "render_sirtx".

render_sirtx

my $value = $util->render_sirtx($identifier);

(experimental since v0.24)

This methods tries to render an identifier in the standard SIRTX syntax. It will add escapes as needed.

Future versions of this method might support more identifiers or more compact syntax.

This might might support more values if Data::Identifier::Wellknown is loaded with the corresponding classes, and/or if a Data::TagMap is given via "so_attach" in Data::Identifier::Interface::Subobjects.

See also "parse_sirtx".

register_namespace

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

(experimental since v0.30)

Registers a namespace by creating a Data::Identifier object (unless one is already passed), updating it's values, and calling "register" in Data::Identifier on it before returning.

This function may also validate the passed values and update other global data structures.

$id is parsed as per from in "new" in Data::Identifier. However it must resolve to an UUID.

The following options from "new" in Data::Identifier are supported: displayname, tagname.

Currently no options specific to namespaces are supported.

Note: This method is not suitable for use with constant. However it is possible to register the Identifier as a constant and the use it with this method. For example:

use constant NS_INT => Data::Identifier->new(uuid => '5dd8ddbb-13a8-4d6c-9264-36e6dd6f9c99')->register;

Data::Identifier::Util->register_namespace(NS_INT, tagname => 'integer-namespace');

register_generator

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

(experimental since v0.30)

Registers a generator the same way "register_namespace" registers an namespace. All aspects of "register_namespace" apply as well but for the fact that this method is used to register generators and the list of specific options.

Currently the following options as known from "generic" in Data::Identifier::Generate are accepted but ignored: namespace, style, type.

Also the following keys not yet supported by "generic" in Data::Identifier::Generate are accepted but ignored: native_case, source_role, up_relation, for_type, copy_tagnames, native_ise_template.

Future versions of this module may implement those options.

register_type

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

(experimental since v0.30)

Registers a type the same way "register_namespace" registers an namespace. All aspects of "register_namespace" apply as well but for the fact that this method is used to register types and the list of specific options.

Currently the following type specific 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. This method calls "register_namespace" on the given namespace to ensure the namespace is correctly registered.

null_value

The value that represents a null for the given identifier. It will be aliased to the null identifier.

AUTHOR

Philipp Schafft <lion@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2023-2026 by Philipp Schafft <lion@cpan.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)