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'

AUTHOR

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

COPYRIGHT

This software is public domain.