view release on metacpan or  search on metacpan

lib/CGI/Wiki/Plugin/Categoriser.pm  view on Meta::CPAN

package CGI::Wiki::Plugin::Categoriser;
use strict;
use CGI::Wiki::Plugin;

use vars qw( $VERSION @ISA );
$VERSION = '0.02';
@ISA = qw( CGI::Wiki::Plugin );

=head1 NAME

CGI::Wiki::Plugin::Categoriser - Category management for CGI::Wiki.

=head1 DESCRIPTION

Uses node metadata to build a model of how nodes are related to each
other in terms of categories.

=head1 SYNOPSIS

  use CGI::Wiki;
  use CGI::Wiki::Plugin::Categoriser;

  my $wiki = CGI::Wiki->new( ... );
  $wiki->write_node( "Red Lion", "nice beer", $checksum,
                     { category => [ "Pubs", "Pub Food" ] } );
  $wiki->write_node( "Holborn Station", "busy at peak times", $checksum,
                     { category => "Tube Station" } );

  my $categoriser = CGI::Wiki::Plugin::Categoriser->new;
  $wiki->register_plugin( plugin => $categoriser );

  my $isa_pub = $categoriser->in_category( category => "Pubs",
                                           node     => "Red Lion" );
  my @categories = $categoriser->categories( node => "Holborn Station" );

=head1 METHODS

=over 4

=item B<new>

  my $categoriser = CGI::Wiki::Plugin::Categoriser->new;
  $wiki->register_plugin( plugin => $categoriser );

=cut

sub new {
    my $class = shift;
    my $self = {};
    bless $self, $class;
    return $self;
}

=item B<in_category>

  my $isa_pub = $categoriser->in_category( category => "Pubs",
                                           node     => "Red Lion" );

Returns true if the node is in the category, and false otherwise. Note
that this is B<case-insensitive>, so C<Pubs> is the same category as
C<pubs>. I might do something to make it plural-insensitive at some
point too.

=cut

sub in_category {
    my ($self, %args) = @_;
    my @catarr = $self->categories( node => $args{node} );
    my %categories = map { lc($_) => 1 } @catarr;
    return $categories{lc($args{category})};
}

=item B<subcategories>

  $wiki->write_node( "Category Pub Food",
                     "pubs that serve food",
                     $checksum,
                     { category => [ "Pubs", "Food", "Category" ] } );
  my @subcategories = $categoriser->subcategories( category => "Pubs" );
  # will return ( "Pub Food" )

  # Or if you prefer CamelCase node names:
  $wiki->write_node( "CategoryPubFood",
                     "pubs that serve food",
                     $checksum,
                     { category => [ "Pubs", "Food", "Category" ] } );