NAME

E2::Ticker - A module for fetching http://everything2.com's tickers.

SYNOPSIS

        use E2::Ticker;

        my $ticker = new E2::Ticker;

        # List New Writeups

        print "New Writeups:\n-------------\n";

        foreach my $n ($ticker->new_writeups) {
                print $n->{title} . "\n";
        }

        # List Other Users

        print "\nOther Users:\n------------\n";

        foreach my $u ($ticker->other_users) {
                print $u->{name};
                print '[$]' if $u->{editor};
                print '[@]' if $u->{god};
                print "\n";
        }

        # (and so on...)

DESCRIPTION

This module provides an interface for fetching http://everything2.com's New Writeups, Cool Nodes, Editor Cools, Random Nodes, Other Users, Time Since, Available Rooms, Best Users, Node Heaven, Maintenance Nodes, Scratch Pad, and Raw Vars, and Interfaces tickers. It also serves as a base class for other modules that load ticker pages.

CONSTRUCTOR

new: new creates a new E2::Ticker object.

METHODS

$ticker->new_writeups [ COUNT ]

This method fetches the New Writeups ticker from everything2 and returns a list of hashrefs (sorted reverse-chronologically). If COUNT is specified, it returns ``COUNT'' values, otherwise it returns the server's default count.

The returned hashrefs have the following keys:

        title           # Writeup title
        id              # node_id
        type            # type (person, place, thing, or idea)
        author          # Author's username
        author_id       # Author's user_id
        parent          # Parent node
        parent_id       # Parent's node_id

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

$ticker->other_users [ ROOM_ID ]

This method fetches the Other Users ticker from everything2 and returns a list of hashrefs (sorted by descending XP). If ROOM_ID is specified, only users in the specified room are listed.

The returned hashrefs have the following keys:

        name    # Username
        id      # user_id
        god     # Boolean: Member of gods group?
        editor  # Boolean: Member of Content Editors group? 
        edev    # Boolean: Member of edev group?
        xp      # User's experience number
        borged  # Is this user borged?

        # The following are only defined if user is not "outside"

        room    # Name of the room user is in
        room_id # node_id of room user is in
        
NOTE: only users who are members of edev are able to determine whether another user is an edev member.

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

$ticker->random_nodes

This method fetches the Random Nodes ticker from everything2 and returns a list of hashrefs.

The returned hashrefs have the following keys:

        title
        id

This method also retrieves the ``random wit'' from everything2, which is then retrievable by calling random_wit.

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

$ticker->cool_nodes [ WRITTEN_BY ] [, COOLED_BY ] [, COUNT ] [, OFFSET ]

This method fetches the Cool Nodes ticker from everything2 and returns a list of hashrefs (sorted reverse-chronologically). Results can be filtered by ``WRITTEN_BY'' and ``COOLED_BY'', which should be usernames. If COUNT is specified, this method returns ``COUNT'' values. COUNT has a server default of 50, and a max of 50 as well. OFFSET specifies how many values back to start in the list, and is used for paging through Cool Nodes.

The returned hashrefs have the following keys:

        title           # Title of the writeup
        id              # node_id
        author          # Author's username
        author_id       # Author's user_id
        cooledby        # Username of user who C!d the writeup
        cooledby_id     # user_id of user who C!d the writeup

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

$ticker->editor_cools

This method fetches the Editor Cools (or ``Endorsements'') ticker from everything2 and returns a list of hashrefs (sorted reverse-chronologically). If COUNT is specified, it returns ``COUNT'' values, otherwise it returns the server's default count.

The returned hashrefs have the following keys:

        title           # Title of the node (not writeup) edcooled
        id              # node_id
        editor          # Username of the editor who cooled the node
        editor_id       # user_id of the editor who cooled the node

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

$ticker->time_since [ USER_LIST ]

This method fetches the Time Since ticker and returns a list of values. If USER_LIST is not specified, it returns a list with one value, that corresponding to the currently-logged-in user.

Otherwise, USER_LIST should be a list of either usernames or user_ids.

It returns a list of hashrefs with the following keys:

        name    # Username
        id      # user_id
        time    # The last time this user was seen

time_since determines whether the USER_LIST is composed names or ids by testing to see if the items in the list are all integers or not. This means that, if a user has a name that is also a valid integer, this name must be passed in a list with other usernames that are not.

time_since also fetches the current time, which is retrievable via a call to time_since_now.

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

$ticker->available_rooms

This method returns a list of available rooms. The first item in this list is the ``go outside'' superdoc.

Each item in this list is a hashref with the following keys:

        title   # The room's title
        id      # The room's node_id

This method returns undef on failure.

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

$ticker->best_users [ NOGODS ]

This method returns a list of Everything2's Best Users. If NOGODS (boolean) is specified, site admins are not included in the listing.

Each item in the returned list is a hashref with the following keys:

        user            # Username of this user
        id              # user_id of this user
        experience      # This user's experience number
        writeups        # The number of writeups this user has posted
        level           # The level of this user (integer)
        level_string    # The level string of this user 
                        # Example: "11 (Godhead)"

NOTE: The e2 server currently ignores the NOGODS option (ebu_noadmins) and instead serves a list based upon the logged-in user's preference (specified in a checkbox on http://everything2.com/?node=Everything's+Best+Users). The NOGODS option should be considered broken (ignored) until this is resolved serverside.

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

$ticker->node_heaven [ NODE_ID ]

This method returns a list of the currently-logged-in user's node heaven (deleted writeups). If NODE_ID is specified, it returns a list with a single element, the deleted writeup corresponding to that NODE_ID. If the specified NODE_ID is not a deleted writeup, or if the user has no deleted writeups, this method returns an empty list.

If the current user is not logged-in, this method returns undef.

Each element in the returned list is a hashref with the following keys:

        title           # The title of the writeup
        id              # The node_id of the writeup
        reputation      # The reputation the writeup had when deleted
        createtime      # The timestamp of the writeup's creation

If NODE_ID is specified, the additional key will be included:

        text            # The text of the writeup

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

$ticker->maintenance_nodes

This method returns a list of maintenance nodes (example: ``E2 Nuke Request''). It returns a list of hashrefs with the following keys:

        title   # Title of node
        id      # node_id of node

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

$ticker->raw_vars

This method returns a hashref to the current user's ``raw vars'' hash on E2. It consists of a number of key/value pairs.

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

$ticker->load_interfaces

This method loads the site-independant list of ticker nodes. E2::Ticker holds its own default list, but extremely paranoid clients can call load_interface to make sure it's using the up-to-date list of ticker interfaces.

The loaded list can be accessed by calling interfaces.

This method returns true on success.

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

$ticker->interfaces

This method returns the list of xml interfaces used to load xml tickers. It returns a hashref with keys corresponding to the names of the interfaces and values corresponding to the node title of the corresponding ticker.

$ticker->random_nodes_wit

This method returns the ``random wit'' that was fetched by the last call to random_nodes. Returns undef if none have been fetched.

$ticker->time_since_now

This method returns the ``now'' value returned by the last call to time_since. Returns undef if that method has not been called.

$ticker->use_string STRING

This method can be used to load a ticker from an XML string rather than the everything2.com server. It's used internally for debugging the tickers, and can be used to cache ticker pages (see E2::Interface::document).

use_string only affects the next ticker-loading method called. Example usage:

        my $xml_string = ... ;
        $ticker->use_string( $xml_string );

        my @w = $ticker->new_writeups;  # loaded from $xml_string

        my @w2 = $ticker->new_writeups; # This time it's loaded from the
                                        # e2 servers.

use_string does not check whether the string is of the proper type for that particular ticker-loading method, nor does it check whether or not the string is valid XML. If you use this method, it is assumed you know what you are doing.

AUTHOR

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

COPYRIGHT

This software is public domain.