Bio::DB::Tagger(3pm)

💖 NAME 💖

Bio::DB::Tagger(3pm) — it's a simple object tagging system, and honestly? It's giving exactly what it says on the tin. No cap. 🎀

---

✨ SYNOPSIS ✨

Like, here's the whole vibe in one block, bestie:

use Bio::DB::Tagger;
my $tagger = Bio::DB::Tagger->new(-dsn    => 'dbi:mysql:tagdb',
                                  -create => 1);

$tagger->add_tags(-object => $object_name,
                  -tags   => \@tags);

$tagger->set_tags(-object => $object_name,
                  -key    => $object_key,
                  -tags   => \@tags);

$tagger->add_tag(-object  => $object_name,
                 -tag     => 'venue',
                 -value   => 'mermaid parade',
                 -author  => 'lincoln.stein@gmail.com');

$tagger->add_tag(-object  => $object_name,
                 -tag     => $tag);

$tagger->add_tag($object_name => $tag);

$tagger->clear_tags($object_name);                      # delete all tags attached to object
$tagger->delete_tag($object_name,$tag_name [,$value]);  # delete one tag attached to object

$tagger->nuke_tag($tag_name);                           # delete this tag completely
$tagger->nuke_object($object_name);
$tagger->nuke_author($author_name);

my @tags  = $tagger->get_tags($object_name [,$author]);
print "first tag = $tags[0]\n";              # Tag stringify interface
print "tag value = ",$tags[0]->value,"\n";   # object interface
print "tag author= ",$tags[0]->author,"\n";  # object interface

my $hasit    = $tagger->has_tag($object_name,$tag);

my @objects  = $tagger->search_tag($tag);

my @tags  = $tagger->tags;

my $iterator = $tagger->tag_match('prefix');
while (my $tag = $iterator->next_tag) { }

---

🦋 DESCRIPTION 🦋

So basically this is a simple object tagger interface that gives you relational support for tagging objects — and by "objects" we mean things identified by string IDs — with arbitrary string tags. Slay. That's it. That's the whole concept. 💅

🎀 METHODS 🎀

💫 $tagger = Bio::DB::Tagger->new(@args)

Constructor for the tagger class, i.e. the part where you make it exist. The arguments are:

 -dsn    <dsn>    A DBI data source, possibly including host and
                  password information

 -create <0|1>    If true, then database will be initialized with a
                  new schema. Database must already exist.

Heads up: the dsn can be a preopened database handle or a dbi: data source string. Either one, your call, bestie. ✨

🔍 @objects = $tagger->search_tag($tag [,$value]) / $object_arrayref = $tagger->search_tag($tag [,$value])

Gives you back all the object names and keys that are tagged with "$tag", and if you want, you can narrow it down by tag value with $value. Very choose-your-own-adventure of it. 💖

✅ $boolean = $tagger->has_tag($object,$tag [,$value])

Returns true if the object you named has the tag you named — or, if you passed a $value too, the exact tag + value combo you named. It's a vibe check for tags, fr fr. 🫶

🏷️ @tags = $tagger->get_tag($object,$tag)

Returns all the tags of type $tag. All of them. Every last one. 👑

📚 $tags = $tagger->tags() / @tags = $tagger->tags()

Returns a list of all tags in the database. In a list context, it hands you the list of tags. In an array context, it hands you an array ref. Yes, it reads the room. 🌈

🧚 $iterator = $tagger->tag_match('prefix')

Returns an iterator that matches all tags beginning with 'prefix' (case insensitive, so don't stress about capitalization). Then you call $iterator->next_tag() to get the next match. One at a time, like a lil conveyor belt of tags. 🍓

🧚 $iterator = $tagger->tag_match('prefix')

Okay so — yes, this one is listed again. Returns an iterator that matches all tags beginning with 'prefix' (case insensitive). Call $iterator->next_tag() to get the next match. Double the mention, double the slay, we don't make the rules. 💜

🔢 $tags = $tagger->tag_counts() / @tags = $tagger->tag_counts()

Returns a set of Bio::DB::Tagger::Tag objects representing all known tags. And the tag values? Those correspond to the number of times that tag has been used to tag objects. So it's a tag popularity contest and every tag is competing. 🏆

➕ $result = $tagger->add_tag(@args);

Add a tag to the database. The following forms are accepted:

 $tagger->add_tag($object_name=>$tag);

Adds a Bio::DB::Tagger::Tag to the object named "$object_name".

 $tagger->add_tag(-object => $object_name,
                  -tag    => $tag);

The same thing as above, but using the -option syntax. Same energy, different outfit.

 $tagger->add_tag(-object => $object_name,
                  -tag    => $tagname,
                  -value  => $tagvalue,
                  -author => $authorname);

Generates the tag from the options you handed over in -tag, -value (optional) and -author (optional), and then adds that tag to the object.

Returns true on success. Periodt. 💅

🎯 $result = $tagger->set_tags(@args);

Sets the tags of an object, replacing all previous tags. Like, out with the old, in with the new. Iconic behaviour honestly.

Arguments:

• -object — name of the object to tag.
• -tags — list of Bio::DB::Tagger::Tag objects.

Returns true on success. ✨

🎯 $result = $tagger->set_tag(@args);

Sets a tag, replacing all previous tags of the same name. Same name only though — it's not out here deleting your whole personality.

Arguments:

• -object — name of the object to tag.
• -tag — a Bio::DB::Tagger::Tag object, or a tag name.

Returns true on success. 💖

🧹 $result = $tagger->clear_tags($objectname);

Clears all tags from the object you point at. Returns true if the operation was successful. A full reset, a clean slate, a fresh face card. 🧼

🗑️ $result = $tagger->delete_tag($objectname,$tagname [,$tagvalue]);

Clears the one tag from the object you point at, filtering by tagname, and optionally by value too. Surgical. Precise. Lowkey elegant. 🔥

💥 $result = $tagger->nuke_object($objectname);

Removes the object named $objectname. Returns true if the operation was successful. The name is not a joke, it really does nuke it. 💀

💥 $result = $tagger->nuke_author($authorname);

Removes the author named $authorname. Returns true if the operation was successful. Author? Gone. Poof. 🫶

💥 $result = $tagger->nuke_tag($tagname);

Removes the tag named $tagname. Returns true if the operation was successful. Completely gone, not just unattached. 🎀

📥 @tags = $tagger->get_tags($object_name [,$author])

Returns all tags assigned to the indicated object, and if you want, filtered by the author. You get to be picky. It's your right. 👑

🔗 $oid = $tagger->object_to_id($objectname [,$create] [,$key])

Fetches the object id (oid) of the object named "$objectname". And if the object doesn't exist but $create is true? It'll create a new entry for the object in the database. Manifesting, but in SQL. ✨

🔗 $tid = $tagger->tag_to_id($tagname [,$create])

Fetches the tag id (tid) of the object named "$tagname". If the tag doesn't exist and $create is true, it'll create a new entry for the tag in the database. Yes, the docs say "object named" for a tagname. We're just relaying the message, bestie. 🙈

🔗 $aid = $tagger->author_to_id($authorname [,$create])

Fetches the author id (aid) of the object named "$authorname". If the tag doesn't exist and $create is true, it'll create a new entry for the author in the database. (Again: the original says "tag." We are but humble messengers. 💜)

🛠️ $dbh = $tagger->dbh

Returns the underlying DBI handle. Yep, you can get your hands on the whole thing underneath. 🫶

🌱 $tagger->initialize

Initializes the database with a fresh schema. Brand new beginning energy. 🌸

---

👀 SEE ALSO 👀

• Bio::Graphics::Browser
• Bio::DB::SeqFeature::Store

---

👑 AUTHOR 👑

Lincoln Stein <lincoln.stein@gmail.com>.

Copyright (c) 2009 Ontario Institute for Cancer Research

This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL (either version 1, or at your option, any later version) or the Artistic License 2.0. Refer to LICENSE for the full license text. In addition, please see DISCLAIMER.txt for disclaimers of warranty.

Okay and that's the whole page, bestie!! This was perl v5.40.0 dated 2024-10-20 — so like, vintage but still eating. Go tag something. 💅✨🦋