| 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 |