NAME

E2::Message - A module for accessing Everything2 messages

SYNOPSIS

        use E2::Message;

        my $catbox = new E2::Message;
        $catbox->login( "username", "password" ); # see E2::Interface
        $catbox->set_room( "Outside" ); 

        # List public messages
        
        my @msg = $catbox->list_public;

        # Output the messages
        
        print "Public Messages:\n";
        print "(Topic: " . $catbox->topic . ")\n";
        foreach my $m (@msg) {
                print "$m->{author}: $m->{text}\n";
        }

        # List unarchived private messages
        
        @msg = $catbox->list_private( 1 );

        # Output the messages
        
        print "Private Messages:\n";
        foreach my $m (@msg) {
                print "($m->{group}) " if $m->{group};
                print "$m->{author}: $m->{text}\n";
        }

DESCRIPTION

This module provides an interface to http://everything2.com's messaging system (the chatterbox as well as private messages). It inherits E2::Ticker.

E2::Message fetches public and private messages from everything2.com. Subsequent calls to its list_public and list_private will return only new messages, unless the corresponding reset method has been called.

CONSTRUCTOR

new

new creates an E2::Message object that defaults to "Guest User" on E2 and, until login is called, can retrieve only public messages and can send neither public nor private messages.

METHODS

$catbox->topic

This method returns the current public room's topic. This topic is updated as a side-effect to both list_public and set_room, so if neither of these methods have been called, topic will return undef.

$catbox->room

This method returns the current room name.

$catbox->room_id

This method returns the current room's node_id.

$catbox->list_public

list_public fetches and returns any public messages in the current room that have been posted since the last call to list_public, as well as updating the topic, room, and room_id. It returns a list of hashrefs representing the fetched messages, each with the following keys:

        author          # Username of message author
        author_id       # User_id of message author
        message_id      # Id of message
        time            # Timestamp of message
        text            # Text of the message
        

list_public returns an empty list if no new messages exist.

Exceptions: 'Unable to process request', 'Parse error:'

$catbox->list_private [ DROP_ARCHIVED ]

list_private fetches and returns any private messages that have been posted sincethe last call to list_private. If DROP_ARCHIVED is true, only messages that do not have the 'archive' flag will be returned. This method returns a list of hashrefs representing the fetched messages, each with the following keys:

        author          # Username of message author
        author_id       # User_id of message author
        id              # Id of message
        time            # Timestamp of message
        text            # Text of the message

        # The following only exist for
        # group messages

        group           # Name of usergroup 
        group_id        # Id of usergourp
        grouptype       # Type of usergroup
        

list_private returns an empty list if no new messages exist.

Exceptions: 'Unable to process request', 'Parse error:'

$catbox->reset_public

This method resets the public message ticker, so the next call to list_public will retrieve all available public messages (they will all be considered "unfetched").

$catbox->reset_private

This method resets the private message ticker, so that in the next call to list_private, all private messages will be considered "unfetched."

$catbox->send MESSAGE_TEXT

send sends "TEXT" as if it were entered into E2's chatterbox. This message need not be escaped in any way. It returns true on success and undef on failure.

Exceptions: 'Unable to process request'

$catbox->blab RECIPIANT_ID, MESSAGE_TEXT

blab sends the private "blab" message MESSAGE_TEXT to user_id RECIPIANT_ID. Returns true on success and undef on failure.

Exceptions: 'Unable to process request'

$catbox->delete MESSAGE_ID

delete permanently deletes the private message with id MESSAGE_ID from Everything2.com. Returns true on success and undef on failure.

Exceptions: 'Unable to process request'

$catbox->set_room ROOM_NAME

set_room changes the current public room to ROOM_NAME. It returns true on success, 0 if ROOM_NAME is already the current room, and undef on failure.

Exceptions: 'Unable to process request'

SEE ALSO

E2::Interface, E2::Ticker, http://everything2.com, http://everything2.com/?node=clientdev

AUTHOR

Jose M. Weeks <jose@joseweeks.com> (Simpleton on E2)

COPYRIGHT

This software is public domain.