NAME

Text::Tradition::Directory - a KiokuDB interface for storing and retrieving traditions and their owners

SYNOPSIS

  use Text::Tradition::Directory;
  my $d = Text::Tradition::Directory->new( 
    'dsn' => 'dbi:SQLite:mytraditions.db',
    'extra_args' => { 'create' => 1 },
  );
  
  my $tradition = Text::Tradition->new( @args );
  my $stemma = $tradition->add_stemma( dotfile => $dotfile ); # if Analysis module installed
  $d->save_tradition( $tradition );
  
  foreach my $id ( $d->traditions ) {
        print $d->tradition( $id )->name;
  }

  ## Users:
  my $userstore = Text::Tradition::UserStore->new(dsn => 'dbi:SQLite:foo.db');
  my $newuser = $userstore->add_user({ username => 'fred',
                                       password => 'somepassword' });

  my $fetchuser = $userstore->find_user({ username => 'fred' });
  if($fetchuser->check_password('somepassword')) { 
     ## login user or .. whatever
  }

  my $user = $userstore->deactivate_user({ username => 'fred' });
  if(!$user->active) { 
    ## shouldnt be able to login etc
  }
    

DESCRIPTION

Text::Tradition::Directory is an interface for storing and retrieving text traditions and all their data, including an associated stemma hypothesis and a user who has ownership rights to the tradition data. It is an instantiation of a KiokuDB::Model, storing traditions and associated stemmas by UUID.

The Text::Tradition::Directory package also includes the Text::Tradition::User class for user objects, and the Text::Tradition::Ownership role which extends the Text::Tradition class to handle user ownership.

ATTRIBUTES

MIN_PASS_LEN

Constant for the minimum password length when validating passwords, defaults to "8".

METHODS

new

Returns a Directory object.

traditionlist

Returns a hashref mapping of ID => name for all traditions in the directory.

tradition( $id )

Returns the Text::Tradition object of the given ID.

save( $tradition )

Writes the given tradition to the database, returning its ID.

delete( $tradition )

Deletes the given tradition object from the database. WARNING!! Garbage collection does not yet work. Use this sparingly.

USER DIRECTORY METHODS

add_user( $userinfo )

Takes a hashref of username, password.

Create a new user object, store in the KiokuDB backend, and return it.

create_user( $userinfo )

Takes a hashref that can either be suitable for add_user (see above) or be a hash of OpenID user information from Credential::OpenID.

find_user( $userinfo )

Takes a hashref of username or email, and possibly openIDish results from Net::OpenID::Consumer.

Fetches the user object for the given username and returns it.

modify_user( $userinfo )

Takes a hashref of username and password (same as add_user).

Retrieves the user, and updates it with the new information. Username changing is not currently supported.

Returns the updated user object, or undef if not found.

deactivate_user( $userinfo )

Takes a hashref of username.

Sets the users active flag to false (0), and sets all traditions assigned to them to non-public, updates the storage and returns the deactivated user.

Returns undef if user not found.

reactivate_user( $userinfo )

Takes a hashref of username.

Returns the user object if already activated. Activates (sets the active flag to true (1)), updates the storage and returns the user.

Returns undef if the user is not found.

delete_user( $userinfo )

CAUTION: Deletes actual data!

Takes a hashref of username.

Returns undef if the user doesn't exist.

Removes the user from the store and returns 1.

validate_password( $password )

Takes a password string. Returns true if it is longer than "MIN_PASS_LEN", false otherwise.

Used internally by "add_user".

user_traditionlist( $user )

Returns a tradition list (see specification above) but containing only those traditions visible to the specified user. If $user is the string 'public', returns only publicly-viewable traditions.

LICENSE

This package is free software and is provided "as is" without express or implied warranty. You can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Tara L Andrews <aurum@cpan.org> (initial release)

Shadowcat Systems http://www.scsys.co.uk/ (user functionality; making it all work)

cpanm Text::Tradition::Directory

perl -MCPAN -e shell
install Text::Tradition::Directory