[BACK]Return to OpenAMD.pm CVS log [TXT][DIR] Up to [local] / HOPE / Net-OpenAMD / lib / Net

Annotation of HOPE/Net-OpenAMD/lib/Net/OpenAMD.pm, Revision 1.18

1.1       andrew      1: package Net::OpenAMD;
                      2:
1.18    ! andrew      3: # $AFresh1: OpenAMD.pm,v 1.17 2010/07/13 00:13:22 andrew Exp $
1.1       andrew      4:
                      5: use warnings;
                      6: use strict;
                      7: use Carp;
                      8:
1.18    ! andrew      9: use version; our $VERSION = qv('0.0.3');
1.14      andrew     10: my $BASE_URI = 'https://api.hope.net/api/';
                     11:
1.8       andrew     12: use Scalar::Util qw( refaddr );
                     13: *_ident = \&refaddr;
1.1       andrew     14:
1.2       andrew     15: use LWP::UserAgent;
1.6       andrew     16: use URI;
1.2       andrew     17: use Net::OAuth;
1.17      andrew     18: use JSON;
1.1       andrew     19:
1.2       andrew     20: {
1.1       andrew     21:
1.17      andrew     22:     my @attr_refs = \(
                     23:         my %base_uri_of,
                     24:         my %ua_of, my %auth_of, my %actions_of,
                     25:         my %json_of,
                     26:     );
1.2       andrew     27:
                     28:     sub new {
                     29:         my ( $class, $options ) = @_;
1.8       andrew     30:         my $self = bless do { \my $x }, $class;
                     31:         my $ident = _ident($self);
1.2       andrew     32:
1.12      andrew     33:         $options ||= {};
1.6       andrew     34:
                     35:         croak 'Options should be a hashref' if ref $options ne 'HASH';
                     36:
1.10      andrew     37:         $base_uri_of{$ident} = $options->{base_uri} || $BASE_URI;
1.6       andrew     38:         $ua_of{$ident}       = $options->{ua}       || LWP::UserAgent->new();
1.17      andrew     39:         $json_of{$ident}     = $options->{json}     || JSON->new();
1.15      andrew     40:         $actions_of{$ident}  = $options->{actions}
1.14      andrew     41:             || [qw( location speakers talks interests users )];
                     42:
1.15      andrew     43:         foreach my $action ( @{ $actions_of{$ident} } ) {
1.14      andrew     44:             ## no critic
                     45:             no strict 'refs';
1.15      andrew     46:             *{$action} = sub { shift->get( $action, @_ ) };
1.14      andrew     47:         }
1.6       andrew     48:
                     49:         # XXX Authenticate
                     50:
1.2       andrew     51:         return $self;
                     52:     }
                     53:
1.7       andrew     54:     sub get {
1.6       andrew     55:         my ( $self, $action, $query ) = @_;
1.8       andrew     56:         my $ident = _ident($self);
1.6       andrew     57:
1.17      andrew     58:         my $uri = URI->new_abs( $action . '/', $base_uri_of{$ident} );
                     59:         $uri->query_form($query);
1.6       andrew     60:
                     61:         my $response = $ua_of{$ident}->get($uri);
1.12      andrew     62:         croak $response->status_line if !$response->is_success;
1.6       andrew     63:
1.17      andrew     64:         my $data;
                     65:         eval {
                     66:             $data = $json_of{$ident}->decode( $response->decoded_content );
                     67:         };
                     68:         croak "Invalid JSON from [$uri]" if $@;
1.13      andrew     69:
1.17      andrew     70:         return $data;
1.6       andrew     71:     }
1.2       andrew     72:
1.14      andrew     73:     sub stats { croak 'Unused feature' }
1.6       andrew     74:
                     75:     sub DESTROY {
                     76:         my ($self) = @_;
1.8       andrew     77:         my $ident = _ident $self;
1.6       andrew     78:
                     79:         foreach my $attr_ref (@attr_refs) {
                     80:             delete $attr_ref->{$ident};
                     81:         }
                     82:
                     83:         return;
                     84:     }
                     85:
1.2       andrew     86: }
                     87:
                     88: 1;    # Magic true value required at end of module
1.1       andrew     89: __END__
1.12      andrew     90:
1.1       andrew     91: =head1 NAME
                     92:
1.2       andrew     93: Net::OpenAMD - Perl interface to the OpenAMD API
1.1       andrew     94:
                     95:
                     96: =head1 VERSION
                     97:
1.18    ! andrew     98: This document describes Net::OpenAMD version 0.0.3
1.1       andrew     99:
                    100:
                    101: =head1 SYNOPSIS
                    102:
                    103:     use Net::OpenAMD;
                    104:
1.7       andrew    105:     my $amd = Net::OpenAMD->new();
                    106:
                    107:     my $location = $amd->location({ area => 'Engressia' });
                    108:
1.1       andrew    109:
                    110: =head1 DESCRIPTION
                    111:
1.2       andrew    112: This module is to make it easy to grab information from the OpenAMD project at
                    113: The Next Hope.
1.4       andrew    114:
                    115: http://wiki.hope.net/Attendee_Meta-Data
1.1       andrew    116:
1.2       andrew    117: http://amd.hope.net/
1.3       andrew    118:
                    119: http://amd.hope.net/2010/05/openamd-api-released-v1-1-1/
1.5       andrew    120:
                    121: http://travisgoodspeed.blogspot.com/2010/06/hacking-next-hope-badge.html
1.1       andrew    122:
                    123: =head1 INTERFACE
                    124:
1.7       andrew    125: =head2 new
                    126:
                    127: Create a new object for accessing the OpenAMD API.
                    128:
                    129:     my $amd = Net::OpenAMD->new( $options );
                    130:
                    131: $options is a hashref with configuration options.
                    132:
                    133: Current options are
                    134:
                    135: =over
                    136:
1.10      andrew    137: =item base_uri
1.7       andrew    138:
1.9       andrew    139: A URL to the API, currently defaults to https://api.hope.net/api/
                    140:
                    141: Most likely it should end with a / to make URI happy, so notice that if you
1.16      andrew    142: are having 404 errors you don't expect.
1.7       andrew    143:
                    144: =item ua
                    145:
                    146: Should be a pre-configured LWP::UserAgent or similar that returns a
                    147: HTTP::Response object when its get method is called with a URI.
                    148:
                    149: =back
                    150:
                    151: =head2 get
1.1       andrew    152:
1.7       andrew    153: This is the main method, although probably never used.  It has better/easier
                    154: ways to access the different actions of the API.
1.1       andrew    155:
1.7       andrew    156:     my $data = $amd->get( $action, $params );
                    157:
                    158: $params are anything that are supported by URI->query, they will get passed
                    159: on the request.
                    160:
                    161: Here $data is a the JSON returned by the API converted to Perl reference.
1.1       andrew    162:
1.7       andrew    163: Helper methods you can call as $amd->method($params) are:
1.1       andrew    164:
                    165: =over
                    166:
1.7       andrew    167: =item interests
                    168:
                    169: =item location
                    170:
                    171: =item new
1.1       andrew    172:
1.7       andrew    173: =item speakers
1.1       andrew    174:
1.7       andrew    175: =item stats
1.1       andrew    176:
1.7       andrew    177: =item talks
1.1       andrew    178:
1.7       andrew    179: =item users
1.1       andrew    180:
                    181: =back
                    182:
1.15      andrew    183: Unless specified, there is nothing different about any of the action methods
1.7       andrew    184: than just calling get($action) instead.  Depending on API changes, this may
                    185: not always be the case.
                    186:
                    187: =head1 DIAGNOSTICS
                    188:
1.11      andrew    189: All methods should croak when an error occurs.
1.7       andrew    190: If the remote API returns a successful response that contains valid JSON, that
                    191: will be decoded and returned.
1.1       andrew    192:
                    193: =head1 CONFIGURATION AND ENVIRONMENT
                    194:
                    195: Net::OpenAMD requires no configuration files or environment variables.
                    196:
1.7       andrew    197: Net::OpenAMD uses LWP::UserAgent for requests and environment for that is
                    198: not cleared.
1.1       andrew    199:
                    200: =head1 DEPENDENCIES
                    201:
1.7       andrew    202: =head3 L<LWP::UserAgent>
1.2       andrew    203:
1.7       andrew    204: =head3 L<URI>
1.2       andrew    205:
1.7       andrew    206: =head3 L<Net::OAuth>
1.1       andrew    207:
1.7       andrew    208: =head3 L<JSON::Any>
1.1       andrew    209:
                    210:
                    211: =head1 INCOMPATIBILITIES
                    212:
                    213: None reported.
                    214:
                    215:
                    216: =head1 BUGS AND LIMITATIONS
                    217:
1.7       andrew    218: No bugs have been reported.
                    219:
                    220: =over
                    221:
                    222: =item Currently it does not support the OAuth that is required to log into the
                    223: API and get information.
1.1       andrew    224:
1.7       andrew    225: =back
1.1       andrew    226:
                    227: Please report any bugs or feature requests to
                    228: C<bug-net-openamd@rt.cpan.org>, or through the web interface at
                    229: L<http://rt.cpan.org>.
                    230:
                    231:
                    232: =head1 AUTHOR
                    233:
                    234: Andrew Fresh  C<< <andrew@cpan.org> >>
                    235:
                    236:
                    237: =head1 LICENSE AND COPYRIGHT
                    238:
                    239: Copyright (c) 2010, Andrew Fresh C<< <andrew@cpan.org> >>. All rights reserved.
                    240:
                    241: This module is free software; you can redistribute it and/or
                    242: modify it under the same terms as Perl itself. See L<perlartistic>.
                    243:
                    244:
                    245: =head1 DISCLAIMER OF WARRANTY
                    246:
                    247: BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
                    248: FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
                    249: OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
                    250: PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
                    251: EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
                    252: WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
                    253: ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
                    254: YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
                    255: NECESSARY SERVICING, REPAIR, OR CORRECTION.
                    256:
                    257: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
                    258: WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
                    259: REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
                    260: LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
                    261: OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
                    262: THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
                    263: RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
                    264: FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
                    265: SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
                    266: SUCH DAMAGES.

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>