/ 
Mac-Apps-Seasonality-LoadICAOHistory-v0.0.4
/ Mac::Apps::Seasonality::LoadICAOHistory

NAME

Mac::Apps::Seasonality::LoadICAOHistory -- load data into an SQLite2 database with the Seasonality weather.db schema.

VERSION

This document describes Mac::Apps::Seasonality::LoadICAOHistory version 0.0.4.

SYNOPSIS

use English qw{ -no_match_vars };
use DBI;
use Mac::Apps::Seasonality::LoadICAOHistory qw{ load_icao_history };
use Mac::Apps::Seasonality::Exceptions;

my $data =
    [
        [
            'blah_blah_blah',   # icao
            '200609201751',     # date
            330,                # wind_direction
            8,                  # wind_speed_knots
            0,                  # gust_speed_knots
            10.000000,          # visibility_miles
            16.000000,          # temperature_c
            1.000000,           # dewpoint_c
            1018,               # pressure_hpa
            25,                 # relative_humidity
        ],
        [
            'boing',            # icao
            '200610150918',     # date
            2,                  # wind_direction
            57,                 # wind_speed_knots
            59,                 # gust_speed_knots
            0.000000,           # visibility_miles
            31.5    ,           # temperature_c
            15.000000,          # dewpoint_c
            939,                # pressure_hpa
            19,                 # relative_humidity
        ],
        [
            'keep_music_evil',  # icao
            '200512161530',     # date
            -1,                 # wind_direction
            -1000,              # wind_speed_knots
            -1000,              # gust_speed_knots
            -1000.000000,       # visibility_miles
            -1000.000000,       # temperature_c
            -1000.000000,       # dewpoint_c
            -1000,              # pressure_hpa
            -1000,              # relative_humidity
        ],
    ];

my $database_connection =
    DBI->connect(
        "dbi:SQLite2:$database_file_name",
        q{},
        q{},
        {
            AutoCommit => 0,
            RaiseError => 1,
        }
    );

eval { load_icao_history($database_connection, $data) };

my $exception
if ($exception = Mac::Apps::Seasonality::InvalidDatumException->caught()) {
    ...
} elsif ($EVAL_ERROR) {
    ...
} # end if

DESCRIPTION

Seasonality http://gauchosoft.com/Software/Seasonality/ is a weather tracking and display application for Mac OS X. This module provides a means of getting data into Seasonality that it cannot retrieve on its own.

INTERFACE

Data loading.

load_icao_history($database_connection, $icao_history_ref)

Takes a reference to a DBI handle and to a reference to a set of ICAO metrics and loads the data into the database.

$database_connection must be an open handle to an SQLite2 database with Seasonality's schema. This handle must have the RaiseError option set on it; this module does no error checking of database actions on its own.

$icao_history_ref must be a reference to an array of ICAO data points, where each data point is represented as a reference to an array of values in the following order:

Observation location identifier
Date and time of observation
Wind direction in degrees
Wind speed in knots
Gust speed in knots
Visibility in miles
Temperature in degrees Celsius
Dew point in degrees Celsius
Atmospheric pressure in hectopascals
Relative humidity in percent

If the attempt to load data is successful, no useful data is returned. All failures result in exceptions.

Input data validation

validate_icao_history_set($icao_history_ref)

Takes a reference to an array of references to arrays containing values representing a single data point. The values in the second level arrays are expected to be in the icao_history table's schema column order. In other words, the parameter is a table that matches the icao_history database table's layout.

If the data is valid, no useful value is returned.

If the data is invalid, an instance of Mac::Apps::Seasonality::InvalidDatumException describing the problem is thrown.

validate_icao_history_point($icao_history_point_ref, $line_number)

Takes a reference to an array of values representing a single data point and the original line number this data was found on in the input source. The values are expected to be in the icao_history table's schema column order.

If the data is valid, no useful value is returned.

If the data is invalid, an instance of Mac::Apps::Seasonality::InvalidDatumException describing the problem is thrown.

Individual column validation

validate_icao( $icao_history_point_ref, $line_number) =item validate_date( $icao_history_point_ref, $line_number) =item validate_wind_direction( $icao_history_point_ref, $line_number) =item validate_wind_speed_knots( $icao_history_point_ref, $line_number) =item validate_gust_speed_knots( $icao_history_point_ref, $line_number) =item validate_visibility_miles( $icao_history_point_ref, $line_number) =item validate_temperature_c( $icao_history_point_ref, $line_number) =item validate_dewpoint_c( $icao_history_point_ref, $line_number) =item validate_pressure_hpa( $icao_history_point_ref, $line_number) =item validate_relative_humidity( $icao_history_point_ref, $line_number)

Each of these takes a reference to an array of values representing a single data point and the original line number this data was found on in the input source. They pick out the datum that they are concerned about from the array and check whether it conforms to the restrictions of that particular column.

If the datum is valid, no useful value is returned.

If the datum is invalid, an instance of Mac::Apps::Seasonality::InvalidDatumException describing the problem is thrown.

DIAGNOSTICS

Error message here, perhaps with %s placeholders

[Description of error here]

Another error message here

[Description of error here]

[Et cetera, et cetera]

CONFIGURATION AND ENVIRONMENT

This module assumes that it is running against a database in the format used by Seasonality versions 1.3 and 1.4.

DEPENDENCIES

DBD::SQLite2 Regexp::Common Mac::Apps::Seasonality::Constants

INCOMPATIBILITIES

This module will not work on databases used by versions of Seasonality earlier than version 1.3.

BUGS AND LIMITATIONS

· The interface to this module is not frozen yet.
· Dates are only checked that they consist of twelve digits and are not yet checked to see whether they are valid in the Gregorian calendar.
· The boilerplate for the DIAGNOSTICS section above has not been replaced.

Please report any bugs or feature requests to bug-mac-apps-seasonality-loadicaohistory@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Elliot Shank <perl@galumph.com>

LICENSE AND COPYRIGHT

Copyright ©2006-2007, Elliot Shank <perl@galumph.com>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.