=================================================================== RCS file: /cvs/HOPE/Net-OpenAMD/lib/Net/OpenAMD.pm,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- HOPE/Net-OpenAMD/lib/Net/OpenAMD.pm 2010/06/27 01:52:33 1.6 +++ HOPE/Net-OpenAMD/lib/Net/OpenAMD.pm 2010/06/27 04:11:22 1.7 @@ -1,6 +1,6 @@ package Net::OpenAMD; -# $AFresh1: OpenAMD.pm,v 1.5 2010/06/24 22:57:42 andrew Exp $ +# $AFresh1: OpenAMD.pm,v 1.6 2010/06/27 00:52:33 andrew Exp $ use warnings; use strict; @@ -38,7 +38,7 @@ return $self; } - sub _get { + sub get { my ( $self, $action, $query ) = @_; my $ident = ident($self); @@ -54,11 +54,11 @@ return JSON::Any->jsonToObj( $response->decoded_content ); } - sub location { my $self = shift; return $self->_get( 'location', @_ ) } - sub speakers { my $self = shift; return $self->_get( 'speakers', @_ ) } - sub talks { my $self = shift; return $self->_get( 'talks', @_ ) } - sub interests { my $self = shift; return $self->_get( 'interests', @_ ) } - sub users { my $self = shift; return $self->_get( 'users', @_ ) } + sub location { my $self = shift; return $self->get( 'location', @_ ) } + sub speakers { my $self = shift; return $self->get( 'speakers', @_ ) } + sub talks { my $self = shift; return $self->get( 'talks', @_ ) } + sub interests { my $self = shift; return $self->get( 'interests', @_ ) } + sub users { my $self = shift; return $self->get( 'users', @_ ) } sub stats { croak 'Unused feature' } sub DESTROY { @@ -76,7 +76,6 @@ 1; # Magic true value required at end of module __END__ - =head1 NAME Net::OpenAMD - Perl interface to the OpenAMD API @@ -91,12 +90,11 @@ use Net::OpenAMD; -=for author to fill in: - Brief code example(s) here showing commonest usage(s). - This section will be as far as many users bother reading - so make it as educational and exeplary as possible. + my $amd = Net::OpenAMD->new(); + + my $location = $amd->location({ area => 'Engressia' }); + - =head1 DESCRIPTION This module is to make it easy to grab information from the OpenAMD project at @@ -112,84 +110,104 @@ =head1 INTERFACE -=for author to fill in: - Write a separate section listing the public components of the modules - interface. These normally consist of either subroutines that may be - exported, or methods that may be called on objects belonging to the - classes provided by the module. +=head2 new +Create a new object for accessing the OpenAMD API. -=head1 DIAGNOSTICS + my $amd = Net::OpenAMD->new( $options ); -=for author to fill in: - List every single error and warning message that the module can - generate (even the ones that will "never happen"), with a full - explanation of each problem, one or more likely causes, and any - suggested remedies. +$options is a hashref with configuration options. +Current options are + =over -=item C<< Error message here, perhaps with %s placeholders >> +=item base_url -[Description of error here] +A URL to the API, currently defaults to https://api.hope.net/api -=item C<< Another error message here >> +=item ua -[Description of error here] +Should be a pre-configured LWP::UserAgent or similar that returns a +HTTP::Response object when its get method is called with a URI. -[Et cetera, et cetera] +=back +=head2 get + +This is the main method, although probably never used. It has better/easier +ways to access the different actions of the API. + + my $data = $amd->get( $action, $params ); + +$params are anything that are supported by URI->query, they will get passed +on the request. + +Here $data is a the JSON returned by the API converted to Perl reference. + +Helper methods you can call as $amd->method($params) are: + +=over + +=item interests + +=item location + +=item new + +=item speakers + +=item stats + +=item talks + +=item users + =back +Unless specified, there is nothing different about any of the helper methods +than just calling get($action) instead. Depending on API changes, this may +not always be the case. +=head1 DIAGNOSTICS + +All methods should croak when an error occours. +If the remote API returns a successful response that contains valid JSON, that +will be decoded and returned. + =head1 CONFIGURATION AND ENVIRONMENT -=for author to fill in: - A full explanation of any configuration system(s) used by the - module, including the names and locations of any configuration - files, and the meaning of any environment variables or properties - that can be set. These descriptions must also include details of any - configuration language used. - Net::OpenAMD requires no configuration files or environment variables. +Net::OpenAMD uses LWP::UserAgent for requests and environment for that is +not cleared. =head1 DEPENDENCIES -=over +=head3 L -=item LWP::UserAgent +=head3 L -=item Net::OAuth +=head3 L -=item JSON::Any +=head3 L -=back =head1 INCOMPATIBILITIES -=for author to fill in: - A list of any modules that this module cannot be used in conjunction - with. This may be due to name conflicts in the interface, or - competition for system or program resources, or due to internal - limitations of Perl (for example, many modules that use source code - filters are mutually incompatible). - None reported. =head1 BUGS AND LIMITATIONS -=for author to fill in: - A list of known problems with the module, together with some - indication Whether they are likely to be fixed in an upcoming - release. Also a list of restrictions on the features the module - does provide: data types that cannot be handled, performance issues - and the circumstances in which they may arise, practical - limitations on the size of data sets, special cases that are not - (yet) handled, etc. - No bugs have been reported. + +=over + +=item Currently it does not support the OAuth that is required to log into the +API and get information. + +=back Please report any bugs or feature requests to C, or through the web interface at