NAME

Weewar - get data from the weewar.com XML API

SYNOPSIS

   use Weewar;

   # get all users
   my @users = Weewar->all_users;     # all active players on weewar

   # get a single user
   my $me = Weewar->user('jrockway'); # one user only (as a Weewar::User)
   my $me = Weewar::User->new({ name => 'jrockway }); # lazy-loaded

   # get a game
   my $game = Weewar->game('27056');  # get game (as a Weewar::Game)
   my $game = Weewar::Game->new({ id => '27056' });
   
   # access headquarters
   my $hq = Weewar->hq('jrockway' => $jrockways_api_key);
   my $hq = Weewar::HQ->new({ user => 'jrockway',
                              key  => $jrockways_api_key,
                            });

DESCRIPTION

This module lets you interact with the (Weewar) API. See Weewar::User, Weewar::Game, and Weewar::HQ for details about what data you can get from the API.

METHODS

Right now, everything is a class method since the weewar API is public for everything except the HQ (and no state needs to be kept between requests). If this changes, then this API will change a bit.

all_users

Return a list of all active Weewar users as Weewar::User objects. The objects are loaded lazily, so this method only causes one request to be sent to the server. When you start accessing the returned children, they will be populated on-demand from the server.

An exception will be thrown if something goes wrong.

user($username)

Returns a Weewar::User object representing $username. If there is no user by that name, and exception is thrown.

game($id)

Returns a Weewar::Game object representing the game with id $id. If there is no game with that id, an exception is thrown.

hq($username => $apikey)

Returns a Weewar::HQ object representing $username's "headquarters". If there is an error getting the data (bad API key, etc.), an exception is thrown.

ENVIRONMENT

You can use different weewar servers by changing these environment variables. I doubt there are other weewar servers that speak this API, though.

WEEWAR_SERVER

The hostname of the Weewar server, defaulting to weewar.com

WEEWAR_BASE

The base URL of the API, defaulting to api1.

BUGS

If the Weewar API changes, this module will need an update. Let me know if something is broken so I can fix it.

The combination of Weewar's odd XML, XML::LibXML, and the fact that I had very little sleep before writing this makes for some very ugly code. Feel free to clean it up and send me a patch.

Bugs should be reported through RT, but you can email me directly too.

AUTHOR

Jonathan Rockway <jrockway@cpan.org>

COPYRIGHT

This module is copyright (c) 2007 Jonathan Rockway.

You can distribute, modify, and use this module under the same terms as Perl itself.