File Coverage

blib/lib/Weather/Underground/StationHistory.pm
Criterion Covered Total %
statement 32 32 100.0
branch 2 2 100.0
condition n/a
subroutine 9 9 100.0
pod 2 2 100.0
total 45 45 100.0


line stmt bran cond sub pod time code
1             package Weather::Underground::StationHistory;
2              
3 3     3   53986 use 5.006000;
  3         12  
  3         126  
4              
5 3     3   19 use strict;
  3         6  
  3         111  
6 3     3   27 use warnings;
  3         7  
  3         100  
7              
8 3     3   3390 use version; our $VERSION = qv('v1.0.5');
  3         8032  
  3         20  
9              
10 3     3   289 use Exporter;
  3         6  
  3         149  
11 3     3   17 use base 'Exporter';
  3         6  
  3         388  
12              
13 3     3   82235 use Regexp::Common;
  3         16685  
  3         99  
14              
15             our @EXPORT_OK =
16             qw{
17             &generate_single_day_station_history_url
18             &strip_garbage_from_station_history
19             };
20             our %EXPORT_TAGS = (
21             all => [@EXPORT_OK],
22             );
23              
24             my $EMPTY_STRING = q<>;
25              
26             sub generate_single_day_station_history_url {
27 2     2 1 15 my ($station_id, $year, $month_number, $day_of_month) = @_;
28              
29             return
30 2         25 sprintf
31             'http://www.wunderground.com/weatherstation/WXDailyHistory.asp?ID=%s&year=%d&month=%d&day=%d&graphspan=day&format=1',
32             $station_id,
33             $year,
34             $month_number,
35             $day_of_month,
36             ;
37             } # end generate_single_day_station_history_url()
38              
39             sub strip_garbage_from_station_history {
40 2     2 1 20344 my $original_contents = shift;
41 2         29 my @original_lines = split m/ [\r\n]+ /xms, $original_contents;
42 2         6 my $resulting_contents = $EMPTY_STRING;
43              
44 2         5 foreach my $original_line (@original_lines) {
45 20         93 $original_line =~ s/ $RE{balanced}{-parens => '<>'} //xmsg;
46 20         2728 $original_line =~ s/ $RE{ws}{crop} //xmsg;
47              
48 20 100       2146 if ($original_line ne $EMPTY_STRING) {
49 9         33 $resulting_contents .= "$original_line\n";
50             } # end if
51             } # end foreach
52              
53 2         13 return $resulting_contents;
54             } # end strip_garbage_from_station_history()
55              
56              
57             1; # Magic true value required at end of module
58             __END__
59              
60             =for stopwords CSV
61              
62             =head1 NAME
63              
64             Weather::Underground::StationHistory - Utility functions for dealing with weather station historical data from L<http://wunderground.com>.
65              
66              
67             =head1 VERSION
68              
69             This document describes Weather::Underground::StationHistory version 1.0.5.
70              
71              
72             =head1 SYNOPSIS
73              
74             use Weather::Underground::StationHistory qw{ :all };
75              
76             use LWP::Simple;
77              
78             print
79             strip_garbage_from_station_history(
80             get(
81             generate_single_day_station_history_url(
82             'KILCHICA52',
83             2006,
84             10,
85             27,
86             )
87             )
88             );
89              
90              
91             =head1 DESCRIPTION
92              
93             This module provides a URL generator function for retrieving historical data
94             for weather stations from Weather Underground (L<http://wunderground.com>).
95              
96             Additionally, a function to clean up the data retrieved from said URLs is
97             provided. Nominally, the content retrieved from the URLs is in CSV (Comma
98             Separated Values) format. If you enter these URLs into a web browser, the data
99             does appear to be in that format. However, the MIME type given for the data by
100             the web server is C<text/html> and the data contains C<< <br> >> tags and HTML
101             comments (though no C<< <html> >>, C<< <head> >>, or C<< <body> >> tags that
102             you would expect for an HTML document). Thus, if a user copies and pastes the
103             data from the web browser, the application receiving the data will get correct
104             CSV, but anything trying to directly parse the page content as CSV will
105             encounter problems.
106              
107              
108             =head1 INTERFACE
109              
110             =over
111              
112             =item C<generate_single_day_station_history_url($station_id, $year, $month_number, $day_of_month)>
113              
114             Returns the URL to use for retrieving data for the station on the specified
115             day.
116              
117             C<$year> needs to be the full year number; two digit years are not supported.
118              
119             C<$month_number> needs to be in the range 1 to 12.
120              
121              
122             =item C<strip_garbage_from_station_history($original_contents)>
123              
124             Takes a string containing the data retrieved from Weather Underground and
125             returns a string containing the same data, without the standard problematic
126             content.
127              
128             Note: this function B<does not> ensure that the data is in valid CSV format.
129             It merely removes extraneous text that usually causes problems in parsing.
130              
131             The returned value has lines delimited by whatever your platform translates
132             C<"\n"> to, which may be different from what Weather Underground is returning.
133              
134              
135             =back
136              
137              
138             =head1 DIAGNOSTICS
139              
140             None.
141              
142              
143             =head1 CONFIGURATION AND ENVIRONMENT
144              
145             Weather::Underground::StationHistory requires no configuration files or
146             environment variables.
147              
148              
149             =head1 DEPENDENCIES
150              
151             L<Regexp::Common>
152              
153              
154             =head1 INCOMPATIBILITIES
155              
156             None reported.
157              
158              
159             =head1 BUGS AND LIMITATIONS
160              
161             No bugs have been reported.
162              
163             Please report any bugs or feature requests to
164             C<bug-weather-underground-stationhistory@rt.cpan.org>, or through the web
165             interface at L<http://rt.cpan.org>.
166              
167              
168             =head1 SEE ALSO
169              
170             L<Weather::Underground> for retrieving current conditions.
171              
172              
173             =head1 AUTHOR
174              
175             Elliot Shank C<< <perl@galumph.com> >>
176              
177              
178             =head1 LICENSE AND COPYRIGHT
179              
180             Copyright (c) 2006-2008, Elliot Shank C<< <perl@galumph.com> >>. All rights
181             reserved.
182              
183             This module is free software; you can redistribute it and/or modify it under
184             the same terms as Perl itself. See L<perlartistic>.
185              
186              
187             =head1 DISCLAIMER OF WARRANTY
188              
189             BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
190             SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
191             STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
192             SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
193             INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
194             FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
195             PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE,
196             YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
197              
198             IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
199             COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
200             SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES,
201             INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
202             OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO
203             LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR
204             THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE),
205             EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
206             DAMAGES.
207              
208             =cut
209              
210             # setup vim: set filetype=perl tabstop=4 softtabstop=4 expandtab :
211             # setup vim: set shiftwidth=4 shiftround textwidth=0 nowrap autoindent :
212             # setup vim: set foldmethod=indent foldlevel=0 :