E2::Writeup - A module for accessing, updating, and cooling writeups.
use E2::Writeup;
use E2::E2Node; # Used to load the writeup.
my $e2node = new E2::E2node;
$e2node->load( "test" ) or die "Unable to load test.";
my $writeup = $e2node->get_writeup; # Returns an E2::Writeup
# Print writeup info (See E2::Node for these)
print "Title: . $writeup->title;
print "\nAuthor: " . $writeup->author;
print "\nDoctext: " . $writeup->text;
# Downvote the writeup
$writeup->vote( -1 );
# Cool the writeup
$writeup->cool;
# Reply to the writeup's author
$writeup->reply( "I just downvoted and cooled your writeup" );
# Update the writeup
$writeup->update(
$writeup->text . "THIS TEXT APPENDED TO WRITEUP"
);
This module is used to load, access, and manipulate writeups on E2. It is probably best used in conjunction with E2::E2Node. It inherits E2::Node.
The relationship between writeups and e2nodes is such that e2nodes contain writeups (0 or more writeups, specifically). E2::Writeup defines the operations that can be performed on writeups contained within e2nodes. Technically, we could load a writeup without loading its enclosing e2node (just pass load_by_id the id of a writeup), but doing so would discard much of the information passed to us (softlinks, firmlinks, etc.). If you want access to this sort of information, use E2::E2Node to load the node, then access the writeup using on of its get_writeup methods.
new creates a new E2::E2Node object. Until that object is logged in in one way or another (see E2::Interface), it will use the "Guest User" account, and will be limited in which operations it can perform.
clear clears all the information currently stored in $writeup. It returns true.
These methods return, respectively, the writeup's type, its parent's title, its parent's node_id, its "marked for destruction" status (boolean: is it marked for destruction?), the number of C!s it has received, and the text of the writeup.
This method returns a list of the users who've cooled this writeup. Each item in the list is a hashref with the following keys:
name
id
This method returns a hashref concerning the reputation of this writeup. It contains the following keys:
up # Upvotes
down # Downvotes
total # Total rep (should be == to upvotes - downvotes)
cast # Have you already cast your vote? (boolean)
This method attempts to cool (C!) a writeup. If NODE_ID is specified, it attempts to cool the writeup with that id, otherwise it attempts to cool the currently-loaded writeup.
Exceptions: 'Unable to process request'
This method attempts to vote on this writeup (-1 for a downvote, 1 for an upvote).
This method returns undef if unable to vote (if the user is trying to vote on his own writeup, if a writeup hasn't been loaded to vote on, or if the user has already voted on this writeup). It also returns undef if it encounters a server error.
This method returns 1 if the vote "caught," and 0 if it did not (which probably means the user is out of votes).
Exceptions: 'Unable to process request', 'Invalid document', 'Parse error:'
This method sends a "blab" message reply to the author of the currently-loaded writeup. If CC is true, it sends a copy of the message to you, the sender.
This method returns undef if no writeup is loaded or if we're currently not logged in (Guest User can't send messages). It returns true on success and 0 on failure (0 means it didn't get the response confirmation it expected--the message may have gone through anyway).
There is no guarantee, if either an exception is raised or this method returns 0, that the message didn't go through. There is, however, a guarantee that if it returns undef, it did not.
One strategy for determining success absolutely would be to (1) always set CC as true, (2) after replying, use E2::Message::list_private to list received messages, and check to make sure the message made it through, and (3) delete the cc'd message.
This, of course, may be a bit drastic.
Exceptions: 'Unable to process request'
update updates the currently-loaded writeup. TYPE, which defaults to the type the writeup was prior to the update, is the type of writeup this is (one of: "person", "place", "thing", or "idea"). During the update, the writeup is re-loaded, so any changes should be immediately visible in this object.
This method returns true on success and undef on failure.
Exceptions: 'Unable to process request', 'Invalid document', 'Parse error:'
E2::Interface, E2::Node, E2::E2Node, http://everything2.com, http://everything2.com/?node=clientdev
Jose M. Weeks <jose@joseweeks.com> (Simpleton on E2)
This software is public domain.
