Bio::DB::Tagger -- Simple object tagging system

       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.

perl v5.40.0                                       2024-10-20                               Bio::DB::Tagger(3pm)

       This is a simple object tagger interface that provides relational support for tagging objects (identified
       by string IDs) with arbitrary string tags.

   METHODS
       $tagger = Bio::DB::Tagger->new(@args)
           Constructor for the tagger class. 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.

           The dsn can be a preopened database handle or a dbi: data source string.

       @objects = $tagger->search_tag($tag [,$value])
       $object_arrayref = $tagger->search_tag($tag [,$value])
           Return  all  object  names  and  keys  that are tagged with "$tag", optionally qualified by tag value
           $value.

       $boolean = $tagger->has_tag($object,$tag [,$value])
           Returns true if indicated object has the indicated tag, or  the  indicated  combination  of  tag  and
           value.

       @tags = $tagger->get_tag($object,$tag)
           Returns all the tags of type $tag.

       $tags = $tagger->tags()
       @tags = $tagger->tags()
           Return  a  list of all tags in the database. In a list context, returns the list of tags. In an array
           context, returns an array ref.

       $iterator = $tagger->tag_match('prefix')
           Returns an  iterator  that  matches  all  tags  beginning  with  'prefix'  (case  insensitive).  Call
           $iterator->next_tag() to get the next match.

       $iterator = $tagger->tag_match('prefix')
           Returns  an  iterator  that  matches  all  tags  beginning  with  'prefix'  (case  insensitive). Call
           $iterator->next_tag() to get the next match.

       $tags = $tagger->tag_counts()
       @tags = $tagger->tag_counts()
           Return a set of Bio::DB::Tagger::Tag objects representing all known tags. The tag  values  correspond
           to the number of times that tag has been used to tag objects.

       $result = $tagger->add_tag(@args);
           Add a tag to the database. The following forms are accepted:

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

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

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

           The same as above using -option syntax.

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

           Generate  the  tag  from  the options provided in -tag, -value (optional) and -author (optional), and
           then add the tag to the object.

           Returns true on success.

       $result = $tagger->set_tags(@args);
           Set the tags of an object, replacing all previous tags.

           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);
           Set a tag, replacing all previous tags of the same name.

           Arguments: -object  Name of the object to tag.
                      -tag     A Bio::DB::Tagger::Tag object, or tag name

           Returns true on success.

       $result = $tagger->clear_tags($objectname);
           Clear all tags from the indicated object. Returns true if the operation was successful.

       $result = $tagger->delete_tag($objectname,$tagname [,$tagvalue]);
           Clear the one tag from the indicated object, filtering by tagname, optionally by value.

       $result = $tagger->nuke_object($objectname);
           Removes the object named $objectname. Returns true if the operation was successful.

       $result = $tagger->nuke_author($authorname);
           Removes the author named $authorname. Returns true if the operation was successful.

       $result = $tagger->nuke_tag($tagname);
           Removes the tag named $tagname. Returns true if the operation was successful.

       @tags = $tagger->get_tags($object_name [,$author])
           Return all tags assigned to the indicated object, optionally filtering by the author.

       $oid = $tagger->object_to_id($objectname [,$create] [,$key])
           Fetch the object id (oid) of the object named "$objectname". If the object doesn't exist, and $create
           is true, will create a new entry for the object in the database.

       $tid = $tagger->tag_to_id($tagname [,$create])
           Fetch the tag id (tid) of the object named "$tagname". If the tag doesn't exist, and $create is true,
           will create a new entry for the tag in the database.

       $aid = $tagger->author_to_id($authorname [,$create])
           Fetch the author id (aid) of the object named "$authorname". If the tag doesn't exist, and $create is
           true, will create a new entry for the author in the database.

       $dbh = $tagger->dbh
           Return underlying DBI handle.

       $tagger->initialize
           Initialize the database with a fresh schema.

       Bio::DB::Tagger -- Simple object tagging system

       Bio::Graphics::Browser, Bio::DB::SeqFeature::Store

        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) { }