NAME
E2::UserSearch - A module for listing and sorting a user's writeups
SYNOPSIS
use E2::UserSearch;
# Display homenode info
my $user = new E2::UserSearch;
$user->login( "Simpleton", "passwd" ); # Login so I can
# load reps too
# Load all writeups, unsorted.
my @w = $user->writeups( "Simpleton", undef, -1 );
# List the writeups
print "All Simpleton's writeups:\n";
print "-------------------------\n";
foreach( @w ) {
print $_->title . " : " . $_->rep->{total};
print " : " . $_->cool_count . "C!" if $_->cool_count;
print "\n";
}
# Now sort them by cools
@w = $user->sort_results( 'cools' );
# List the writeups
print "\nAll Simpleton's writeups, sorted by cools:\n";
print "------------------------------------------\n";
foreach( @w ) {
print $_->title . " : " . $_->rep->{total};
print " : " . $_->cool_count . "C!" if $_->cool_count;
print "\n";
}
DESCRIPTION
This module provides an interface to E2's user search (search for writeups by user). It inherits E2::Ticker.
CONSTRUCTOR
- new
-
new
creates anE2::UserSearch
object.
METHODS
- $user->writeups [ USERNAME ] [, SORT_BY ] [, COUNT ] [, START_AT ]
-
writeups
does a "writeups by user" search on the user (USERNAME defaults the username of the currently-logged-in user; if no user is logged in, USERNAME must be specified or a "No username specified" error is thrown) for COUNT number of writeups (defualt is 50), starting at START_AT (which is an offset from the highest writeup as ranked by SORT_BY--more on that later), which defaults to 0. If -1 is passed as the COUNT, this method will fetch ALL writeups by the specified user. For many users, this would be a pretty big hit on the database. The suggested method is to space calls towriteups
over a period of time, perhaps only displaying a page at a time/etc. When you receive less writeups than you asked for, you'll have hit the final page of the writeups search.SORT_BY can be any of 'rep', 'title', 'creation', or
undef
(in which case, the writeups are not in any particular order). Nowsort_results
will do client-side sorting, which at first glance would make SORT_BY =undef
seem the most consciencious choice (which I suppose it is), but client-side searching can not replicate all the functionality of server-side sorting for two reasons: 1) We can only sort what we have, so if we fetch the fifty most-recent writeups by a noder who's written 500, sorting them by title will yield, well, the fifty most-recent writeups by this user, sorted by title. This is quite different from whatwriteups( 'title', 50 )
would yield. And 2) most users can't sort by 'rep' client-side for any users other than themselves (they have no access to other users' reps without voting on all the writeups and then loading those writeups to fetch their rep).writeups
, for all those searches called with SORT_BY = 'rep', will remember the reputation order of all writeups that it can, so if you wish to sort by 'rep' at all, I suggest you do all your searching ordered by 'rep'. I also suggest that SORT_BY =undef
will yield meaningless results on any client-side sorting unless a search of all the user's writeups has taken place (all at once, or over multiple calls).writeups
returns a list of E2::Writeup. These do not contain doctext ($writeup->text
), hold a value for$writeup->cool_count
but not the (list)$writeup->cools
, and may or may not have any$writeup->rep
or$writeup->marked
information.Exceptions: 'Unable to process request', 'Parse error:'
- $user->sort_results [ SORT_BY ] [, COUNT ] [, START_AT ]
-
sort_results
sorts and returns a list of writeups (E2::Writeups) fetched from e2 bywriteups
. COUNT is the maximum number of writeups to fetch (-1 for ALL, which is the default), START_AT is an offset from the highest ranked writeup (ranked by SORT_BY), which defaults to 0.SORT_BY can be one of 'rep', 'title', 'creation', 'cools', or 'random', as well as 'rep_reverse', 'title_reverse', and 'creation_reverse'. It can also be a code reference which will be passed to perl's
sort
function. A number of aliases are provided bysort_results
, to define particular sorting orders. For example, a 'cools' search is actually a call to( sort_by_cools || sort_by_rep || sort_by_rep_position )
. Each test is executed only if the test to its left returns an 'is equal' result (0). The aliases that can be used are as follows:sort_by_creation; sort_by_creation_reverse; sort_by_title; sort_by_title_reverse; sort_by_rep; # Sorts by known rep sort_by_rep_reverse; sort_by_rep_position; # Sorts by implied rep (from sort_by_rep_position_reverse; # server-side 'rep' sort) sort_by_cools; sort_by_cools_reverse; sort_by_random; # Example: Sorts by cools, then title my @list = $user->sort_results( sub { sort_by_cools || sort_by_title } ); # Or, sort by writeup type, then creation time. my @list = $user->sort_results( sub { $a->wrtype cmp $b->wrtype || sort_by_creation } );
sort_results
returns a list of E2::Writeup. These do not contain doctext ($writeup->text
), hold dummy values for C! (so$writeup->cools
returns the correct value only in a scalar context), and may not have any$writeup->rep
information.Exceptions: 'Invalid sort type:'
- $user->compare OLD_USER_SEARCH
-
This method compares this E2::UserSearch with another, returning a list of hashrefs corresponding to each writeup that differs between the two. Each element of the list may have the following keys:
title # Title of the writeup node_id # node_id of the writeup parent # Title of the writeup's parent parent_id # node_id of the writeup's parent rep # Hashref with the keys: up, down, total, and cast cools # C! count change_up # Number of additional upvotes change_down # Number of additional downvotes change_cools # Number of additional C!s old_title # Former title of the writeup (if title has changed) new # Boolean: Is this writeup new? removed # Boolean: Has this writeup been removed (nuked)?
compare
also has the side-effect of storing various statistical information about the usersearch, which is then available by callingstats
. - $user->stats
-
This method returns statistical information about this usersearch. This is loaded by calling
compare
. It returns a hashref with the folowing keys:max_rep # The highest reputation of any of this user's writeups min_rep # The lowest reputation of any of this user's writeups total_cools # The accumulated number of C!s this user has received person # The number of writeups this user has of type 'person' place # ditto for 'place' thing # and 'thing' idea # and 'idea'
SEE ALSO
E2::Interface, E2::Ticker, E2::User, E2::Writeup, http://everything2.com, http://everything2.com/?node=clientdev
AUTHOR
Jose M. Weeks <jose@joseweeks.com> (Simpleton on E2)
COPYRIGHT
This software is public domain.