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

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

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