Com.pm untested

filter: Statementstmt 0.0% 0 / 19 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 6 Podpod n/a totaltotal 0.0% 0 / 25 CC 1 SCAR 6.9
CC
1
Cov
0%
BEGIN
2.0
BEGIN
2.0
BEGIN
2.0
CRAP 2.0
1 package Weather::Com;
2  
3 use 5.006;
4 use strict;
5 use warnings;
6 use Carp;
7 use Weather::Com::Cached;
8 use Weather::Com::Location;
9  
10 our $VERSION = sprintf "%d.%03d", q$Revision: 1.8 $ =~ /(\d+)/g;
11  
12  
13 #--------------------------------------------------------------------
14 # This is just a dummy package containing POD
15 #
16 # Weather::Com.pod has been removed and this package has been added
17 # to make Weather-Com work with CPAN shell.
18 #
19 # Therefore, the whole tutorial went into this file.
20 # Weather::Com.pod is no longer maintained.
21 #--------------------------------------------------------------------
22  
23  
24 1;
25  
26 =pod
27  
28 =head1 NAME
29  
30 Weather::Com - fetching weather information from I<weather.com>
31  
32 =head1 SYNOPSIS
33  
34 #!/usr/bin/perl -w
35 use Weather::Com::Finder;
36  
37 # you have to fill in your ids from weather.com here
38 my $PartnerId = 'somepartnerid';
39 my $LicenseKey = 'mylicense';
40  
41 my %weatherargs = (
42 'partner_id' => $PartnerId,
43 'license' => $LicenseKey,
44 'language' => 'de',
45 );
46  
47 my $weather_finder = Weather::Com::Finder->new(%weatherargs);
48
49 my @locations = $weather_finder->find('Heidelberg');
50
51 foreach my $location (@locations) {
52 print "Found weather for city: ", $location->name(), "\n";
53 print "Current Conditions are ",
54 $location->current_conditions()->description(), "\n";
55 }
56  
57 =head1 DESCRIPTION
58  
59 I<Weather::Com> provides three interfaces to access weather
60 information from I<weather.com>.
61  
62 Except from the main high level interface, there is also
63 a simple, very easy to use one called I<Weather::Com::Simple>.
64 And if you want, you can also use the low level
65 interface that is the basis for the two high level interfaces,
66 directly (I<Weather::Com::Cached> or even I<Weather::Com::Base>).
67  
68 Please refer to the POD of these modules directly for detailed
69 information.
70  
71 The data provided by I<weather.com> and made accessible by this OO
72 interface can be used for free under special terms. Please have a look
73 at the application programming guide of I<weather.com>
74 L<http://www.weather.com/services/xmloap.html>
75  
76 =head1 LOCALIZATION
77  
78 Weather-Com uses I<Locale::Maketext> for the l10n. Foreach language there
79 has to be package I<Weather::Com::L10N::[langcode]> (e.g. I<Weather::Com::L10N::de>).
80  
81 Localization is new with version 0.4 of Weather-Com. Therefore, there are not too
82 many languages supported, yet. If one wants to create such a language definition package
83 for a language that is not part of this module, please do the following:
84  
85 =over 4
86  
87 =item 1.
88  
89 check my homepage to verify that the language package has not been created by someone
90 else, yet (L<http://www.schnuecker.org/index.php?weather-com>).
91  
92 =item 2.
93  
94 contact me to verify if anybody else already is already translating into this language
95  
96 =item 3.
97  
98 just do it and send me your new language package. It then will be first put onto my
99 website for download and then it will be part of the next release.
100  
101 =back
102  
103 =head2 Dynamic Language Support
104  
105 With version 0.5 of Weather-Com I have introduced a new feature called
106 I<dynamic language support>.
107  
108 The language for all textual attributes that usually are translated in your default
109 language you chose while creating your C<Weather::Com::Finder> instance can now
110 dynamically be changed on a I<per-method-call basis>.
111  
112 Have a look at this example:
113  
114 #!/usr/bin/perl -w
115 use Weather::Com::Finder;
116  
117 # you have to fill in your ids from weather.com here
118 my $PartnerId = 'somepartnerid';
119 my $LicenseKey = 'mylicense';
120  
121 my %weatherargs = (
122 'partner_id' => $PartnerId,
123 'license' => $LicenseKey,
124 'language' => 'en',
125 );
126  
127 my $weather_finder = Weather::Com::Finder->new(%weatherargs);
128
129 my @locations = $weather_finder->find('Heidelberg');
130
131 foreach my $location (@locations) {
132 print "Found weather for city: ", $location->name(), "\n";
133 print "Current Conditions are ",
134 $location->current_conditions()->description(), "\n";
135
136 # HERE WE USE DYNAMIC LANGUAGE SUPPORT
137 print "That is in German: ",
138 $location->current_conditions()->description('de'), "\n";
139 }
140  
141 As you can see in this example, you can provide a language tag to
142 a method that returns textual information.
143  
144 If you want to find out if the I<dynamic language support> is already
145 implemented for a specific attribute of one Weather-Com class, have
146 a look at the corresponding packages POD.
147  
148 =head1 TUTORIAL
149  
150 The usual way to use the I<Weather::Com> module would be to instantiate
151 a I<Weather::Com::Finder> that allows you to search for a location
152 by a search string or postal code or whatever I<weather.com> may
153 understand.
154  
155 The finder returns an arrayref or an array of locations (depending on
156 how you call the C<find()> method). Each location is an object of
157 I<Weather::Com::Location>.
158  
159 The locations consist of location specific data,
160 a I<Weather::Com::CurrentConditions> object, a I<Weather::Com::Forecast>
161 object and a I<Weather::Com::Units> object.
162  
163 =head2 Configuration parameters
164  
165 You will need a configuration hash to instantiate a I<Weather::Com::Finder>
166 object. Except of the I<partner_id> and the I<license> all parameters are
167 optional and have sensible defaults.
168  
169 use Weather::Com::Finder;
170  
171 my %config = (
172 partner_id => 'somepartnerid', # mandatory
173 license => 'somelicensekey' # mandatory
174 language => 'de',
175 units => 's',
176 cache => '/tmp/weather',
177 timeout => 300,
178 debug => 1,
179 proxy => 'http://some.proxy.de:8080',
180 proxy_user => 'myaccount',
181 proxy_pass => 'myproxy_pass'
182 );
183  
184 The valid parameters are:
185  
186 =over 4
187  
188 =item partner_id => 'somepartnerid'
189  
190 To be allowed to fetch weather information from I<weather.com> you need to
191 register (free of charge) to get a so called I<Partner Id> and a
192 I<License Key>.
193  
194 =item license => 'somelicensekey'
195  
196 See I<partner_id>.
197  
198 =item language => 'somelanguagecode'
199  
200 I<weather.com> returns some textual data to describe the weather
201 conditions, uv index, moon phase, wind direction, etc.
202  
203 If one specifies a valid language as configuration parameter, this
204 textual descriptions are translated into that language. If one specifies
205 a language for that there's no translation, the objects will return the
206 english texts.
207  
208 =item cache => '/any/path'
209  
210 Maybe you want to define a special path to put the cache files into.
211 The cache directory defaults to ".".
212  
213 =item units => s | m
214  
215 This parameter defines whether to fetch information in metric (m) or
216 US (s) format.
217  
218 Defaults to 'm'.
219  
220 =item timeout => some integer (in seconds)
221  
222 The timeout for I<LWP::UserAgent> to get an HTTP request done usually is set to
223 180s. If you need a longer timeout or for some reasons a shorter one you can
224 set this here.
225  
226 Defaults to 180 seconds.
227  
228 =item debug => 0 | 1
229  
230 Set debugging on/off.
231  
232 Defaults to 0 (off).
233  
234 =item proxy => 'none' | 'http://some.proxy.de:8080'
235  
236 Usually no proxy is used by the I<LWP::UserAgent> module used to communicate
237 with I<weather.com>. If you want to use an HTTP proxy you can specify one here.
238  
239 =item proxy_user => undef | 'myuser'
240  
241 If specified, this parameter is provided to the proxy for authentication
242 purposes.
243  
244 Defaults to I<undef>.
245  
246 =item proxy_pass => undef | 'mypassword'
247  
248 If specified, this parameter is provided to the proxy for authentication
249 purposes.
250  
251 Defaults to I<undef>.
252  
253 =back
254  
255 =head2 Weather::Com::Finder
256  
257 Usually one would start by searching for a location. This is done by
258 instantiating a I<Weather::Com::Finder> object providing all necessary
259 information about the I<weather.com> license, the proxy if one is needed,
260 etc.
261  
262 my $finder = Weather::Com::Finder->new(%config);
263  
264 Then you call the finders C<find()> method to search for locations whose
265 name or whose postal code matches against the searchstring. The finder then
266 returns an array (or arrayref) of I<Weather::Com::Location> objects.
267  
268 # if you want an array of locations:
269 my @locations = $finder->find('Heidelberg');
270
271 # or if you prefer an arrayref:
272 my $locations = $finder->find('Heidelberg');
273  
274 For further information please refer to L<Weather::Com::Finder>.
275  
276 =head2 Weather::Com::Location
277  
278 The I<Weather::Com::Location> object contains information about the location
279 itself (longitude, latitude, current local time, etc.), a I<Weather::Com::Units>
280 object that contains all information about the units of messures currently used with
281 this location, and a I<Weather::Com::CurrentConditions> object containing the
282 current weather conditions of the location.
283  
284 foreach my $location (@locations) {
285 print "Found location with name: ", $location->name(), "\n";
286 print "The longitude of this location is: ", $location->longitude(), "\n";
287 }
288  
289 All information in the I<Weather::Com::Location> object is updated with each single
290 call of one of its methods corresponding to the caching rules implemented in
291 I<Weather::Com::Cached>.
292  
293 For detailed information about the I<Weather::Com::Location> class please refer to
294 L<Weather::Com::Location>.
295  
296 =head2 Weather::Com::Units
297  
298 The units class provides all units of measure corresponding to the data of the
299 location object. You'll get an instance of this class by calling the C<units()>
300 method of your location object.
301  
302 For detailed information about the I<Weather::Com::Units> class please refer to
303 L<Weather::Com::Units>.
304  
305 =head2 Weather::Com::CurrentConditions
306  
307 Each location has a I<Weather::Com::CurrentConditions> object accessible via
308 its C<current_conditions()> method.
309  
310 my $conditions = $location->current_conditions();
311 print "Current temperature is ", $conditions->temperature(), "°C\n";
312 print "but it feels like ", $conditions->windchill(), "°C!\n";
313  
314 Anytime you call a method of your I<Weather::Com::CurrentConditions> object,
315 its data is refreshed automatically if needed according to the caching rules.
316  
317 For detailed information about this class please refer to
318 L<Weather::Com::CurrentConditions>.
319  
320 =head2 Weather::Com::Forecast
321  
322 Each location has a I<Weather::Com::Forecast> object to access weather
323 forecasts. I<weather.com> provides up to 9 days of forecast - or 10 days
324 if one wants to count day 0 which is I<today> in most cases.
325  
326 my $forecast = $location->forecast();
327 print "Max. temperature tomorrow will be ", $forecast->day(1)->high(), "°C\n";
328  
329 Any time you call a method of your I<Weather::Com::Forecast> object, forecast data
330 is updated if necessary.
331  
332 For detailed information about this class please refer to
333 L<Weather::Com::Forecast>.
334  
335 =head2 Other classes
336  
337 There are a some other classes that are used to represent groups of
338 weather data like wind (speed, direction, etc.), UV index, air pressure, etc.
339  
340 Objects of these classes belong to objects of class I<Weather::Com::CurrentConditions> or
341 I<Weather::Com::Forecast> that will be introduced with the next release. These
342 objects data will only refresh when you call the corresponding method of the parent object.
343  
344 For detailed information about these classes please refer to their own POD.
345  
346 Classes available with this version are:
347  
348 =head3 Weather::Com::AirPressure
349  
350 Provides access to the barometric pressure data.
351  
352 For detailed information about this class please refer to
353 L<Weather::Com::AirPressure>.
354  
355 =head3 Weather::Com::UVIndex
356  
357 Provides access to the uv index of the parent object.
358  
359 For detailed information about this class please refer to
360 L<Weather::Com::UVIndex>.
361  
362 =head3 Weather::Com::Wind
363  
364 Provides access to wind speed, maximum gust, direction in degrees, etc.
365  
366 =head1 EXTENSIONS
367  
368 If you plan to extend these module, e.g. with some other caching mechanisms,
369 please contact me. Perhaps we can add your stuff to this module.
370  
371 =head1 SEE ALSO
372  
373 =head2 Detailed documentation of the main interface
374  
375 L<Weather::Com::Finder>, L<Weather::Com::Location>, L<Weather::Com::Units>,
376 L<Weather::Com::CurrentConditions>, L<Weather::Com::AirPressure>,
377 L<Weather::Com::UVIndex>, L<Weather::Com::Wind>
378  
379 =head2 Detailed documentation of the I<Simple> API
380  
381 L<Weather::Com::Simple>
382  
383 =head2 Detailed documentation of the low level interface
384  
385 L<Weather::Com::Cached> and L<Weather::Com::Base>
386  
387 =head1 BUGS/SUPPORT/PRE-RELEASES
388  
389 If you want to report a bug, please use the CPAN bug reporting tool.
390  
391 If you have any question, suggestion, feature request, etc. please use the
392 CPAN forum.
393  
394 If you are looking for fixes, pre-releases, etc. have a look at my website
395 L<http://www.schnuecker.org/index.php?weather-com>.
396  
397 =head1 AUTHOR
398  
399 Thomas Schnuecker, E<lt>thomas@schnuecker.deE<gt>
400  
401 =head1 COPYRIGHT AND LICENSE
402  
403 Copyright (C) 2004-2007 by Thomas Schnuecker
404  
405 This library is free software; you can redistribute it and/or modify
406 it under the same terms as Perl itself.
407  
408 The data provided by I<weather.com> and made accessible by this OO
409 interface can be used for free under special terms.
410 Please have a look at the application programming guide of
411 I<weather.com> (L<http://www.weather.com/services/xmloap.html>)
412  
413 =cut