NAME

E2::Writeup - A module for accessing, updating, and cooling writeups.

SYNOPSIS

        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"
        );

DESCRIPTION

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.

CONSTRUCTOR

new

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.

METHODS

$writeup->clear

clear clears all the information currently stored in $writeup. It returns true.

$writeup->wrtype

$writeup->parent

$writeup->parent_id

$writeup->marked

$writeup->cool_count

$writeup->text

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.

$writeup->cools

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

$writeup->rep

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)

$writeup->cool [ NODE_ID ]

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'

$writeup->vote -1 | 1

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:'

$writeup->reply TEXT [, CC ]

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'

$writeup->update TEXT [ , TYPE ]

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:'

SEE ALSO

E2::Interface, E2::Node, E2::E2Node, http://everything2.com, http://everything2.com/?node=clientdev

AUTHOR

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

COPYRIGHT

This software is public domain.