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 newE2::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 totime_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
. Returnsundef
if none have been fetched. - $ticker->time_since_now
-
This method returns the "now" value returned by the last call to
time_since
. Returnsundef
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.
SEE ALSO
E2::Interface, E2::Search, E2::Usersearch, E2::Message, E2::Session, E2::ClientVersion, E2::Scratchpad, http://everything2.com, http://everything2.com/?node=clientdev
AUTHOR
Jose M. Weeks <jose@joseweeks.com> (Simpleton on E2)
COPYRIGHT
This software is public domain.