Data::Taxonomy::Tags - Represents a set of tags for any item

Data-Taxonomy-Tags documentation Contained in the Data-Taxonomy-Tags distribution.

Index

Code Index:

NAME

Top

Data::Taxonomy::Tags - Represents a set of tags for any item

SYNOPSIS

Top

    use Data::Taxonomy::Tags;

    my $tags = Data::Taxonomy::Tags->new('perl tags cpan module system:meta');

    print $_, "\n" for $tags->tags;

    print $_, "\n" for $tags->categories;

DESCRIPTION

Top

Data::Taxonomy::Tags will basically take care of managing tags for an item easier. You provide it with a string of tags and it'll allow you to call methods to get all the tags and categories as well as add and delete tags from the list.

Methods

new($string[,\%options])

The first argument is a string of tags. This string is stripped of any leading and trailing whitespace. The second argument, which is optional, is a hashref of options.

Returns a Data::Taxonomy::Tags object;

separator => ['\s+', ' ']

Specifies the regex pattern (or compiled regex) which will be used to split the tags apart and the character(s) used between tags when converting the object back to a string. Make sure to escape any special characters in the regex pattern.

If the value is not an arrayref, then the same value is used for both operations (and is escaped for the regex).

Defaults to ['\s+', ' '].

category => [':', ':']

Specifies the regex pattern (or compiled regex) which will be used to split the tag name from it's optional category and the character(s) used between the category and tag when converting to a string. Make sure to escape any special characters in the regex pattern.

If the value is not an arrayref, then the same value is used for both operations (and is escaped for the regex).

Defaults to [':', ':'].

tags

Returns an array or arrayref (depending on context) of Data::Taxonomy::Tags::Tag objects.

add_to_tags($tags)

Processes the string and adds the tag(s) to the object.

remove_from_tags($tags)

Processes the string and removes the tag(s) from the object.

remove_category($category)

Removes all tags with the specified category.

categories

Returns an array or arrayref (depending on context) of the unique categories.

tags_with_category($category)

Returns an array or arrayref (depending on context) of the tags with the specified category

as_string

Returns the tag list as a string (that is, what was given to the constructor). Overloading is used as well to automatically call this method if the object is used in a string context.

BUGS

Top

All bugs, open and resolved, are handled by RT at https://rt.cpan.org/NoAuth/Bugs.html?Dist=Data-Taxonomy-Tags.

Please report all bugs via https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Taxonomy-Tags.

LICENSE

Top

Copyright 2005, Thomas R. Sibley.

You may use, modify, and distribute this package under the same terms as Perl itself.

AUTHOR

Top

Thomas R. Sibley, http://zulutango.org:82/

Data-Taxonomy-Tags documentation Contained in the Data-Taxonomy-Tags distribution. 
package Data::Taxonomy::Tags;

use strict;
use warnings;

use vars qw($VERSION $ERROR);
$VERSION = '0.05';

use overload
	'""'     => sub { shift->as_string },
	fallback => 1;

# Constants for separator and category
use constant SPLIT  => 0;
use constant JOIN   => 1;

use Data::Taxonomy::Tags::Tag;


sub new {
    my ($class, $tags, $opt) = @_;
    
    my $self = bless {
        _input       => $tags,
        separator   => ['\s+', ' '],
        category    => [':', ':'],
    }, $class;
    
    if (defined $opt) {
        for (qw(separator category)) {
            if (defined $opt->{$_}) {
                $self->{$_} = ref $opt->{$_} eq 'ARRAY' && @{$opt->{$_}} == 2
                                ? $opt->{$_}
                                : [qr/\Q$opt->{$_}\E/, $opt->{$_}];
            }
        }
    }
    
    $self->add_to_tags($tags);
    
    return $self;
}


sub tags {
    return wantarray && defined $_[0]->{tags}
            ? @{$_[0]->{tags}}
            : $_[0]->{tags};
}


sub add_to_tags {
    my ($self, $input) = @_;
    my @tags = split /$self->{separator}[SPLIT]/, $self->_cleanup($input);
    
    $_ = Data::Taxonomy::Tags::Tag->new($_, { separator => $self->{category} })
        for @tags;
    
    @tags = @{$self->_remove_from_tagset($self->as_string, \@tags)};
    
    push @{$self->{tags}}, @tags;
}


sub remove_from_tags {
    my ($self, $input) = @_;
    $self->{tags} = $self->_remove_from_tagset($input, [$self->tags]);
}

sub _remove_from_tagset {
    my ($self, $input, $tagset) = @_;
    
    my %tags =   map { $_ => 1 }
               split /$self->{separator}[SPLIT]/, $self->_cleanup($input);
    
    my @result = grep { !$tags{$_} } @$tagset;
    return \@result;
}


sub remove_category {
    my ($self, $category) = @_;
    
    {
        no warnings 'uninitialized';
        @{$self->{tags}} = grep { $_->category ne $category } $self->tags;
    }
}


sub categories {
    my $self = shift;

    my %seen;
    my @cats = grep { defined $_ && !$seen{$_}++ }
                map { $_->category }
                    $self->tags;

    return wantarray ? @cats : \@cats;
}


sub tags_with_category {
    my ($self, $category) = @_;
    
    my @tags;
    {
        no warnings 'uninitialized';

        @tags =  map { $_->[1]->name }
                grep { $_->[0] eq $category }
                 map { [$_->category, $_] }
                     $self->tags;
    }

    return wantarray ? @tags : \@tags;
}


sub as_string {
    my $self = shift;
    
    return defined $self->tags
            ? join $self->{separator}[JOIN], $self->tags
            : undef;
}

sub _cleanup {
    my ($self, $str) = @_;
    {
        no warnings 'uninitialized';
        $str =~ s/^\s*//g;
        $str =~ s/\s*$//g;
    }
    return $str;
}


42;