NAME

E2::Interface - A client interface to the everything2.com collaborative database

SYNOPSIS

        use E2::Interface;

        my $e2 = new E2::Interface;
        $e2->set_cookie_file( "cookies.txt" );
        $e2->login( "username", "password" );

        my $page = $e2->process_request( node_id => 124, display_type => "xmltrue" );

        $e2->logout;

DESCRIPTION

Introduction

This module is the base class for e2interface, a set of modules that interface with everything2.com. It maintains an agent that connects to E2 via HTTP and that holds a persistent state (a cookie) that can be cloned to allow multiple descendants of E2::Interface to act a single, consistent client. It also contains a few convenience methods.

e2interface

The modules that compose e2interface are listed below and indented to show their inheritance structure.

        E2::Interface - The base module

                E2::Node        - Loads regular (non-ticker) nodes

                        E2::E2Node      - Loads and manipulates e2nodes
                        E2::Writeup     - Loads and manipulates writeups
                        E2::User        - Loads user information
                        E2::Superdoc    - Loads superdocs
                        E2::Room        - Loads rooms

                E2::Ticker      - Modules for loading ticker nodes

                        E2::Message     - Loads, stores, and posts messages
                        E2::Search      - Title-based searches
                        E2::Usersearch  - Lists and sorts writeups by a user

See the manpages of each module for information on how to use that particular module.

Error handling

e2interface uses Perl's exception-handling system, Carp::croak and eval. An example:

        my $int = new E2::Interface;

        print "Enter username:";
        my $name = <>; chomp $name;
        print "Enter password:";
        my $pass = <>; chomp $pass;

        eval {
                if( $int->login( $name, $pass ) ) {
                        print "$name successfully logged in.";
                } else {
                        print "Unable to login.";
                }
        }
        if( $@ ) {
                if $@ =~ /Unable to process request/ {
                        print "Network exception: $@\n";
                } else {
                        print "Unknown exception: $@\n";
                }
        }

In this case, login may generate an "Unable to process request" exception if is unable to communicate with or receives a server error from everything2.com. This exception may be raised by any method in any package in e2interface that attempts to communicate with the everything2.com server.

Common exceptions include the following (those ending in ':' contain more specific data after that ':'):

        'Unable to process request' - HTTP communication error.
        'Invalid document'          - Invalid document received.
        'Parse error:'              - Exception raised while parsing
                                      document (the error output of
                                      XML::Twig::parse is placed after
                                      the ':'
        'Usage:'                    - Usage error (method called with
                                      improper parameters)

I'd suggest not trying to catch 'Usage:' exceptions: they can be raised by any method in e2interface and if they are triggered it is almost certainly due to a bug in the calling code.

All methods list which exceptions (besides 'Usage:') that they may potentially throw.

CONSTRUCTOR

new

new creates an E2::Interface object. It defaults to using 'Guest User' until either login or cookie is used to log in a user.

METHODS

$e2->login USERNAME, PASSWORD

This method attempts to login to Everything2.com with the specified USERNAME and PASSWORD.

This method returns true on success and undef on failure.

Exceptions: 'Unable to process request'

$e2->logout

logout attempts to log the user out of Everything2.com. If a cookie file has been specified (with set_cookie_file), the cookie file will be updated on success.

Returns true on success and undef on failure.

$e2->process_request ATTR1 => VAL1 [, ATTR2 => VAL2 [, ...]]

process_request assembles a URL based upon the specified ATTR and VAL pairs (example: process_request( node_id => 124 ) would translate to "http://everything2.com/?node_id=124" (well, technically, a POST is used rather than a GET, but you get the idea)). It requests that page via HTTP and returns the text of the response (stripped of HTTP headers and with smart quotes and other MS weirdness replaced by the plaintext equivalents). It returns undef on failure.

For those pages that may be retrieved with or without link parsing (conversion of "[link]" to a markup tag), this method uses this object's parse_links setting.

All necessary character escaping is handled by process_request.

Exceptions: 'Unable to process request'

$e2->clone OBJECT

clone copies various members from the E2::Interface-derived object OBJECT to this object so that both objects will use the same agent to process requests to Everything2.com. This is useful if, for example, one wants to use both an E2::Node and an E2::Message object to communicate with Everything2.com as the same user. This would work as follows:

        $msg = new E2::Message;
        $msg->login( $username, $password );

        $node = new E2::Node;
        $node->clone( $msg )

clone returns $self if successful, otherwise returns undef.

$e2->client_name

client_name return the name of this client, "e2interface-perl".

$e2->client_version

client_version returns the version of this client.

$e2->this_username

this_username returns the username currently being used by this agent.

$e2->this_user_id

this_user_id returns the user_id of the current user.

$e2->domain [ DOMAIN ]

If DOMAIN is specified, domain sets the domain used to fetch pages to DOMAIN. DOMAIN should contain neither an "http://" or a trailing "/".

domain returns the currently-used domain.

$e2->cookie [ COOKIE ]

cookie returns the current everything2.com cookie (used to maintain login). If COOKIE is specified, cookie sets everything2.com's cookie to "COOKIE" and returns that value.

"COOKIE" is a string representing a key/value pair. Example: an account with the username "willie" and password "S3KRet" would have a cookie of "userpass=willie%257CwirQfxAfmq8I6". The implementation of the login method describes how to generate a cookie... but general use requires no knowledge of this.

This is how cookie would normally be used:

        # Store the cookie so we can save it to a file

        if( $e2->login( $user, $pass ) ) {
                $cookies{$user} = $e2->cookie;
        }

        ...

        print CONFIG_FILE "[cookies]\n";
        foreach my $c (keys %cookies) {
                print CONFIG_FILE "$c = $cookies{$c}\n";
        }

Or:

        # Load the appropriate cookie
        
        while( $_ = <CONFIG_FILE> ) {
                chomp;
                if( /^$username = (.*)$/ ) {
                        $e2->cookie( $1 );
                        last;
                }
        }

If COOKIE is not valid, this function returns undef and the login cookie remains unchanged.

$e2->logged_in

logged_in returns a boolean value, true if the user is logged in and undef if not.

Exceptions: 'Unable to process request', 'Parse error:'

$e2->find_node_id TITLE [, TYPE]

find_node_id fetches the node_id of the node TITLE, which is of type TYPE ('e2node' by default). Returns the node_id on success and undef on failure.

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

$e2->parse_links [BOOL]

parse_links returns (and optionally sets to BOOL) an internal flag that determines, when fetching a page, whether links are parsed (converted to HTML anchor tags).

SEE ALSO

E2::Node, E2::E2Node, E2::User, E2::Superdoc E2::Ticker, E2::Message, E2::Search, E2::UserSearch, E2::Code, E2::Nodetrack, http://everything2.com, http://everything2.com/?node=clientdev

AUTHOR

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

COPYRIGHT

This software is public domain.