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
        archive         # Boolean: Is this message archived?

        # 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 [, CC ]

blab sends the private "blab" message MESSAGE_TEXT to user_id RECIPIANT_ID. If CC is true, sends a copy of the message to the sender as well. Returns true on success and undef on failure.

Exceptions: 'Unable to process request'

$catbox->archive MSG_ID_LIST

$catbox->unarchive MSG_ID_LIST

$catbox->delete MSG_ID_LIST

These methods archive, unarchive, or permanently delete the messages in MSG_ID_LIST (this is a list of message ids).

Exceptions: 'Unable to process request'

$catbox->perform HASH

This method performs multiple archive, unarchive, and delete operations on a list of messages.

HASH is organized as a hash of msg_id => operation pairs. Example:

        $catbox->perform( 
                100 => 'archive',
                101 => 'unarchive',
                102 => 'delete'
        );

If any operations besides "archive", "unarchive", and "delete" are specified, this method throws an "Invalid operation:" exception.

Exceptions: 'Unable to process request', 'Invalid operation:'

$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.