NAME

E2::E2Node - A module for fetching, accessing, and manipulating e2nodes on http://everything2.com.

SYNOPSIS

        use E2::E2Node;

        my $node = new E2::E2Node;
        $node->login( "username", "password" ); # See E2::Interface

        if( $node->load( "Butterfinger McFlurry" ) ) { # See E2::Node
                print $node->title . " :\n\n";         # See E2::Node
                while( my $w = $node->get_writeup ) {
                        print $w->title . " by ";      # See E2::Writeup
                        print $w->author;              # See E2::Writeup
                        print "\n" . $w->text . "\n";  # See E2::Writeup
                }
        }

        # List softlinks
        
        print "\nSoftlinks:\n";
        foreach my $s ($node->list_softlinks) {
                print $s->{title} . "\n";
        }

DESCRIPTION

This module provides an interface to http://everything2.com's e2nodes and writeups. It inherits E2::Node.

E2::E2Node is used by loading an entire node (via E2::Node's load or load_by_id) and then operating upon the writeups within that node. It is capable of listing and retrieving the writeups in a node, creating nodes, adding writeups to a node, and voting upon writeups in a node.

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 what information it can fetch and which operations it can perform.

METHODS

$node->clear

clear clears all the information currently stored in $node.

$node->has_mine

$node->is_locked

Boolean: "Does this node have a writeup by me in it?"; "Is this node softlocked?"

is_locked is actually a string value, if true, consisting of the text of the softlock.

$node->list_softlinks

$node->list_firmlinks

$node->list_sametitles

These methods return a list of softlinks, firmlinks, or sametitles.

They each return a list of hashrefs. list_softlinks and list_firmlinks return hashrefs with the keys "title" and "id". list_sametitles, which deals with the "'x' is also a: user / room / etc.", has the additional key of "type".

These return empty lists if the current node has none of the respective softlinks, firmlinks, or sametitles, or undef if there is no node currently loaded.

$node->list_writeups

list_writeups returns a list of E2::Writeups corresponding to the writeups in the currently-loaded node. It returns an empty list if this node contains no writeups, and undef if there is no node currently loaded.

NOTE: All E2::Writeups returned by these methods are cloned from $node, and therefore share the same login cookie, background threads, etc.

$node->get_writeup [ NUM ]

$node->get_writeup_by_author AUTHOR

$node->get_my_writeup

These methods return references to E2::Writeup objects. get_writeup returns the NUM'th writeup in the current node (or, if NUM is not specified, the writeup immediately succeeding the last writeup returned by get_writeup). get_writeup_by_author returns the writeup in the current node that was written by AUTHOR. get_my_writeup returns the writeup in the current node written by the currently-logged-in user. See the E2::Writeup manpage for information about accessing writeup data.

NOTE: All E2::Writeups returned by these methods are cloned from $node, and therefore share the same login cookie, background threads, etc.

These methods return undef if they cannot return a writeup.

$node->get_writeup_count

get_writeup_count returns the number of writeups in the current node. Returns undef if there is no node currently loaded.

$node->get_writeup_number

get_writeup_number returns the number of the next writeup that get_writeup will, by default, return. Returns undef if there is no node currently loaded.

$node->vote NODE_ID => VOTE [ , NODE_ID2 => VOTE2 [ , ... ] ]

vote votes on a list of writeups. There should be a NODE_ID => VOTE pair for each writeup to vote upon. NODE_ID is the node_id of the writeup, and VOTE is either -1 or 1, (downvote or upvote, respectively).

This method returns undef if there is no node currently loaded, otherwise it returns true. THIS DOES NOT NECESSARILY MEAN THE VOTES WENT THROUGH.

In the process of voting, the current node is re-fetched and re-loaded, and if the caller wishes to determine whether each vote "caught" (as opposed to just refreshing the display or file or whatever output he is using, which will reflect the changes), he must do so manually.

Exceptions: 'Unable to process request', 'Invalid document'

$node->add_writeup TEXT, TYPE [ , NODISPLAY ]

add_writeup adds a new writeup to the current node. TEXT is the text of the writeup, TYPE is the type of writeup it is (one of: "person", "place", "thing", or "idea"), and NODISPLAY, if true (it defaults to false), tells E2 not to display this writeup in "New Writeups". It returns true on success and undef on failure.

Exceptions: 'Unable to process request'

$node->create TITLE

create creates a new node (a "nodeshell") of title TITLE, then loads this new node.

It returns true if the created node now exists. Otherwise returns undef.

Exceptions: 'Unable to process request', 'Invalid document'

SEE ALSO

E2::Interface, E2::Node, 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.