= acts_as_20ggable

This gem implements categories ('Tags v2.0') engine inspired by Dmitriy Smirnov's
post http://spectator.ru/technology/web-building/tags2null .

It is heavily based on acts_as_taggable_on_steroids by Jonathan Viney (thanks!):
http://svn.viney.net.nz/things/rails/plugins/acts_as_taggable_on_steroids/

Also, it is under development and not production-ready yet. Look at FIXMEs, TODOs and OPTIMIZEs in code. Interface is subject to change, too.
  
== Instructions & usage

Almost everything concerned with original acts_as_taggable_on_steriods applies equally
to this plugin, so read original README first: 

 http://svn.viney.net.nz/things/rails/plugins/acts_as_taggable_on_steroids/README
 
=== Attention

TagHierarchyBuilder.rebuild_hierarchy relies on DB transactions. So, on
non-transactional datastores everything can break suddenly.

=== Playground configuration

Generate and apply migration:

  ruby script/generate acts_as_20ggable_migration
  rake db:migrate

Let's suppose we have photos and we want those photos to have tags:

  class Photo < ActiveRecord::Base
    acts_as_taggable
  end
  
Also let's suppose we already have some photos with some tags in DB.
 
=== Tags hierarchy editing

To dump tags hierarchy for editing, use

  hierarchy = TagHierarchyBuilder.dump_tags # => ['# Categories',
                                                  '# Synonyms',
                                                  '# Unlinked tags',
                                                  'Nature',
                                                  'Horse',
                                                  'Cat',
                                                  'Kitty',
                                                  'Animals']

Let user edit it as plain text, then to update hierarchy use

  # hierarchy => ['# Categories',
                  'Nature / Animals',
                  'Animals / Horse',
                  'Nature / Animals / Cat',
                  '# Synonyms',
                  'Cat = Kitty']

  TagHierarchyBuilder.rebuild_hierarchy(hierarchy)

Comments ("# …") in hierarchy specification are purely optional and inserted only 
for user convenience.

TagHierarchyBuilder can throw TagHierarchyBuilder::WrongSpecificationSyntax or Tag::HierarchyCycle. Errors descriptions still not implemented, sorry.

=== Finding tagged objects

find_tagged_with by default returns models with all subtags:

  Photo.find_tagged_with('Animals') # => Everything tagged with Animals, Horse, Cat, Kitty
  Photo.find_tagged_with('Animals', :exclude_subtags => true) # => Only tagged with Animals
  
== Other

Problems, comments, and suggestions all welcome. avanie@gmail.com