NAME

Data::TagDB - Work with Tag databases

VERSION

version v0.02

SYNOPSIS

    use Data::TagDB;

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

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);
    # 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.

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.

link

    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, ...]);

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

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)

cpanm Data::TagDB

perl -MCPAN -e shell
install Data::TagDB