[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.16

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

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