Ham-Reference-Callook: A Perl repository from bradmc

NAME
    Ham::Reference::Callook - An object oriented front end for the
    Callook.info callsign API

VERSION
    Version 0.02

INSTALLATION
    To install this module, run the following commands:

    perl Makefile.PL
    make
    make test
    make install

SYNOPSIS
     use Ham::Reference::Callook;
     my $callook = Ham::Reference::Callook->new;

     # get the listing data for a callsign
     my $listing = $callook->listing('N8QQ');

     # print some info
     print "Name: $listing->{name}\n";

     # examine the entire hashref of callsign data
     use Data::Dumper;
     print Dumper($listing);

     # get data for another callsign in text format and print the block of text
     $callook->type('text');
     print $callook->listing('W8IRC');

DESCRIPTION
    The "Ham::Reference::Callook" module provides an easy object oriented
    front end to access Amateur Radio callsign data made available from the
    Callook.info web site.

    To help ensure foward compatibility with the data from the FCC provided
    by Callook.info, this module does not attempt to manage or filter
    individual data elements of a callsign. You will need to inspect the
    hash reference keys to see which elements are available for any given
    callsign, as demonstrated in the synopsis.

CONSTRUCTOR
  new()
     Usage    : my $callook = Ham::Reference::Callook->new;
     Function : creates a new Ham::Reference::Callook object
     Returns  : a Ham::Reference::Callook object
     Args     : a hash:

                key       required?   value
                -------   ---------   -----
                timeout   no          an integer of seconds to wait for
                                       the timeout of the xml site
                                       default = 10
                type      no          possible values are xml or text
                                       'xml' will cause the listing to be
                                       returned as a hash reference whose
                                       structure matches the XML returned
                                       from the Callook.info API.
                                       'text' will cause the listing to be
                                       returned as a single complete block
                                       of text in a scalar reference.
                                       default = xml

METHODS
  listing()
     Usage    : $hashref = $callook->listing($callsign) - OR - $scalar = $callook->listing($callsign}
     Function : retrieves data for the standard listing of a callsign from Callook.info
     Returns  : a hash reference if type is 'xml' (the default), or a scalar if type is 'text'
     Args     : a scalar (the callsign)

  type()
     Usage    : $callook->type($type}
     Function : sets the type of structure to retrieve when using the listing() method to get data 
     Returns  : n/a
     Args     : a scalar ('xml' or 'text')
     Notes    : 'xml' will cause the listing to be returned as a hash reference with a structure that
                  matches the XML returned from the Callook.info API.
                'text' will cause the listing to be returned as a single complete block of text in a
                  scalar reference.
                defaults to 'xml'

  timeout()
     Usage    : $callook->timeout($seconds);
     Function : sets the number of seconds to wait on the API server before timing out
     Returns  : n/a
     Args     : an integer

  is_error()
     Usage    : if ( $callook->is_error )
     Function : test for an error if one was returned from the call to the API site
     Returns  : a true value if there has been an error
     Args     : n/a

  error_message()
     Usage    : $err_msg = $callook->error_message;
     Function : if there was an error message when trying to call the API site, this is it
     Returns  : a string (the error message)
     Args     : n/a

DEPENDENCIES
    *   XML::Simple

    *   LWP::UserAgent

    *   An Internet connection

TODO
    *   Add ARRL section info.

    *   Improve this documentation.

ACKNOWLEDGEMENTS
    This module accesses data from the Callook.info site provided by Joshua
    Dick, W1JDD. See http://callook.info

SEE ALSO
    For more information about the data provided by Callook.info, see the
    API reference at http://callook.info/api_reference.php

AUTHOR
    Brad McConahay N8QQ, "<brad at n8qq.com>"

COPYRIGHT AND LICENSE
    "Ham::Reference::Callook" is Copyright (C) 2010 Brad McConahay N8QQ.

    This module is free software; you can redistribute it and/or modify it
    under the terms of the Artistic License 2.0. For details, see the full
    text of the license in the file LICENSE.

    This program is distributed in the hope that it will be useful, but it
    is provided "as is" and without any express or implied warranties. For
    details, see the full text of the license in the file LICENSE.
bradmc/Ham-Reference-Callook
