/ 
Data-TagMap-v0.02
/ Data::TagMap

NAME

Data::TagMap - module for working with tag maps

VERSION

version v0.02

SYNOPSIS

use Data::TagMap;

This module implements a way to map between host defined tag identifiers and tags.

All methods in this module die on error unless documented otherwise.

This module inherit from Data::Identifier::Interface::Userdata.

METHODS

new

my Data::TagMap $map = Data::TagMap->new;

Creates a new map object. No parameters are supported.

add_one

$map->add_one($hdi => $to);

This method adds an entry for the given host defined identifier ($hdi) with the value $to. $to must be of any type supported by "new" in Data::Identifier using from.

add_colours

$map->add_colours($hdi => @colours);

Adds zero or more colours to the map starting at host identifier $hdi.

The colour values must be in #RRGGBB format or any colour object accepted by "new" in Data::Identifier using from, preferably a Data::URIID::Colour.

add_range

$map->add_range($from, $type, $to, length => $length);
# e.g.:
$map->add_range(100, sid => 1, length => 128);

Add a range to the map. The range is defined using a starting poing ($from), a starting identifier ($to of type $type), and a length ($length).

$type must be a Data::Identifier, or value valid for wellknown in "new" in Data::Identifier or a UUID. $type must also be supported for ranges (it must be an identifier type that is numeric).

The range must not overlap with any other mappings.

next_free

my $next_hdi = $map->next_free( [ $meta_range ] );

(since v0.02)

Finds the next free host defined identifier for the given meta range. If no meta range is given ANY is used.

This method will die if no valid host defined identifier is found.

add_meta_range

$map->add_meta_range($meta_ranges, %opts);

(experimental since v0.02)

Adds the meta range $meta_ranges to the list.

The following options are supported:

start

The first host defined identifier in this meta range. This option is required.

end

The last host defined identifier in this meta range. This option is optional. This option cannot be given together with length.

length

The length of this meta range. This option is optional. This option cannot be given together with end.

Note: This method might or might not perform tests on the validity of the ranges. Which tests are performed is subject change for future versions.

The following ranges are supported. All ranges can be suffxed with _low, _mid, and _high. This is useful to split ranges if the target stores host defined identifiers in encodings with variable size.

sid

(since v0.02)

This meta range is for small-identifier mappings. It is common to have the sid mapping as the first range so sids and host defined identifiers map to the same values.

sni

(since v0.02)

This meta range is used to map SIRTX numerical identifiers.

raen

(since v0.02)

This meta range is used to map RoarAudio error numbers, a type of portable error codes similar to errno.

chat0w

(since v0.02)

This meta range is uded to map chat word tags.

colours

(since v0.02)

This meta range is used to map colour values.

unicodecp

(since v0.02)

This meta range is used to map unicode code points. If unicodecp_low is used it is common to have it map the full ASCII range (code points 0 to 127).

wd

(since v0.02)

This meta range is used to map wikidata items (Q, P, and L alike).

inode

(since v0.02)

This meta range is used by filesystems or similar data structures. It is used to map to the inodes on the filesystem. It is common that there is only one range that maps directly to all inodes, hence having the same or a larger size than the inode table.

glyph

(since v0.02)

This meta range is used by fonts to map the individual glyphs.

individual

(since v0.02)

This meta range is used for individual tags that are not part of any range. See also "add_range".

get

my $id  = $map->get($as, $hdi);
# or:
my @ids = $map->get($as, @hdi);

This method will return the entry for the given host defined identifier as an object of type $as.

Valid values for $as are those valid for the same parameter of "as" in Data::Identifier.

Note: This method is sensitive to it's context (scalar or list).

reverse_get

my $hdi  = $map->reverse_get($as, $id);
# or:
my @hdis = $map->reverse_get($as, @ids);

(experimental since v0.02)

This method will return the host defined identifier for the given identifiers.

Note: This method is sensitive to it's context (scalar or list).

AUTHOR

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

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)