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 an E2::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 to writeups 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). Now sort_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 what writeups( '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 by writeups. 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 by sort_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 calling stats.

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