NAME

Data::TagHive - hierarchical tags with values

VERSION

version 0.005

SYNOPSIS

  use Data::TagHive;

  my $taghive = Data::TagHive->new;

  $taghive->add_tag('book.topic:programming');

  $taghive->has_tag('book'); # TRUE

OVERVIEW

Data::TagHive is the bizarre, corrupted union of String::TagString and Data::Hive. It combines the "simple list of strings" of the former with the "hierarchical key-value/value pairs" of the latter, using a different interface from either.

It's probably better than that sounds, though.

A Data::TagHive object represents a set of tags. Each tag is a string that represents a structure of nested key-value pairs. For example, a library book might be tagged:

  book.pages.size:letter
  book.pages.count:180
  book.type:hardcover
  book.topic:programming.perl.cpan

Each tag is a set of key-value pairs. Later pairs are qualified by earlier pairs. Values are optional. Keys and values are separated by colons. Key-value pairs are separated by dots.

A tag is considered present if it was set explicitly or if any more-specific subtag of it was set. For example, if we had explicitly added all the tags shown above, a tag hive would then report true if asked whether each of the following tags were set:

  book
  book.pages
  book.pages.size
  book.pages.size:letter
  book.pages.count
  book.pages.count:180
  book.type
  book.type:hardcover
  book.topic
  book.topic:programming
  book.topic:programming.perl
  book.topic:programming.perl.cpan

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

METHODS

add_tag

  $taghive->add_tag( $tagstr );

This method adds the given tag (given as a string) to the hive. It will fail if there are conflicts. For example, if "foo:bar" is already set, "foo:xyz" cannot be set. Each tag can only have one value.

Tags without values may be given values through add_tag, but only if they have no tags beneath them. For example, given a tag hive with "foo.bar" tagged, "foo.bar:baz" could be added, but not "foo:baz"

has_tag

  if ($taghive->has_tag( $tagstr )) { ... }

This method returns true if the tag hive has the tag.

delete_tag

  $taghive->delete_tag( $tagstr );

This method deletes the tag from the hive, along with any tags below it.

If your hive has "foo.bar:xyz.abc" and you delete_tag "foo.bar" it will be left with nothing but the tag "foo"

all_tags

This method returns, as a list of strings, all the tags set on the hive either explicitly or implicitly.

AUTHOR

Ricardo Signes <cpan@semiotic.systems>

CONTRIBUTOR

Ricardo Signes <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Data::TagHive

perl -MCPAN -e shell
install Data::TagHive