/ 
Data-TagDB-v0.03
River stage zero No dependents
/ Data::TagDB

NAME

Data::TagDB - Work with Tag databases

VERSION

version v0.03

SYNOPSIS

use Data::TagDB;

my $db = Data::TagDB->new($dsn, ...);
# or:
my $db = Data::TagDB->new($dbh);

# Create new database:
use Data::TagDB::Migration;
my Data::TagDB $db = Data::TagDB::Migration->create(...);

This module implements SQL based universal tag databases. Such databases can be used to store any kind of (semantic) data.

This module and it's submodule implement creation of databases, migration (to most current scheme), adding data and reading data from the database.

The instances of Data::TagDB::Tag repesent any kind of object (may it be file, user account or a real life object like a tree). It provides some convenience functions such as to query objects for their name.

Data::TagDB::Factory (via "factory") is provided for easy creation of new tags.

METHODS

new

my $db = Data::TagDB->new($dsn, ...);
# or:
my $db = Data::TagDB->new($dbh);

Returns a new object that can be used for lookups. Either an already connected DBI handle can be passed or data source that is then passed to "connect" in DBI internally.

dbh

my $dbh = $db->dbh;

Returns the current DBI connection.

disconnect

$db->disconnect

This disconnects from the database backend. It also renders this object useless.

tag_by_id

my Data::TagDB::Tag $tag = $db->tag_by_hint($type => $id);
# or:
my Data::TagDB::Tag $tag = $db->tag_by_hint($hint => $id);
# or:
my Data::Identifier $id = ...;
my Data::TagDB::Tag $tag = $db->tag_by_hint($id);
# e.g:
my Data::TagDB::Tag $tag = $db->tag_by_hint(uuid => 'abc...');

Gets a tag by an an identifier of the provided type. The type must be a Data::TagDB::Tag or a a string that is a valid hint.

If only argument is provided the argument must be an instance of Data::Identifier.

relation

my Data::TagDB::Iterator $iter = $db->relation(...);

Returns an iterator for relations. The following keys can be used to filter the list. All must be Data::TagDB::Tag or an array ref of them objects: tag, relation, context, filter, and related. Each may be prefixed with no_ for negative filtering.

metadata

my Data::TagDB::Iterator $iter = $db->metadata(...);

Returns an iterator for relations. The following keys can be used to filter the list. All must be Data::TagDB::Tag or an array ref of them objects: tag, relation, context, type, and encoding. Each may be prefixed with no_ for negative filtering.

Additionally data_raw can be used to filter for a data value.

my Data::TagDB::Iterator $iter = $db->link(...);

This combines "relation", and "metadata". An iterator is returned that lists both metadata, and relations (in any order). The common subset of filters can be used. Namely: tag, relation, and context.

wk

my Data::TagDB::WellKnown $tag = $db->wk;
my Data::TagDB::Tag       $tag = $wk->...;
# e.g.:
my Data::TagDB::Tag       $asi = $db->wk->also_shares_identifier;

Returns a dictionary of well known tags.

register_decoder

$db->register_decoder($type, $encoding, sub { ... });

Registers a decoder for a given type and encoding. Both $type, and $encoding must be Data::TagDB::Tag.

create_tag

my Data::TagDB::Tag $tag = $db->create_tag([$type => $value, ...], [$type => $value, ...]);
# or:
my Data::Identifier $id = ...;
my Data::Identifier $extra = ...;
my Data::TagDB::Tag $tag = $db->create_tag($id, [ $extra ]);

Create a tag (or return it if it already exists). Takes two lists if type-identifier pairs. The first list is the list of identifiers that uniquely identify the tag (e.g. an UUID). The second list contains additional, non unique identifiers (e.g. tagnames) and is optional.

If the tag does not exist it is created. Once it exists all identifiers added (for already existing tags missing identifiers are added).

Each list can be replaced by a single instance of Data::Identifier.

create_metadata

my Data::TagDB::Metadata $metadata = $db->create_metadata(
    tag         => $tag,        # required
    relation    => $relation,   # required
    context     => $context,
    type        => $type,
    encoding    => $encoding,
    data_raw    => $raw,        # required
);

Create a metadata entry if it does not yet exist. Returns it once created.

create_relation

my Data::TagDB::Relation $relation = $db->create_relation(
    tag         => $tag,        # required
    relation    => $relation,   # required
    related     => $related,    # required
    context     => $context,
    filter      => $filter,
);

Creates a relation (if it does not yet exist) and returns it.

create_cache

my Data::TagDB::Cache $cache = $db->create_cache;

Create a new cache object every time this is called. Cache objects can be used to speed up processing. See Data::TagDB::Cache for details.

migration

$db->migration->upgrade;

Get a migration object. This is mostly used for upgrading the database schema to the current one. It is recommended to perform upgrades for long running processes. For short running processes this can increase the startup time.

See also Data::TagDB::Migration.

factory

my Data::TagDB::Factory $factory = $db->factory;

Get a factory object used to create tags. See also Data::TagDB::Factory for details.

tag_by_hint

my Data::TagDB::Tag $tag = $db->tag_by_hint($hint);

Get a tag by hint. What hints are supported depends on what is stored in the database's hint table.

AUTHOR

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

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)