This file is indexed.

/usr/share/perl5/Weather/Com.pod is in libweather-com-perl 0.5.3-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
package Weather::Com;

our $VERSION = sprintf "%d.%03d", q$Revision: 1.14 $ =~ /(\d+)/g;

1;

__END__

=pod

=head1 NAME

Weather::Com - fetching weather information from I<weather.com>

=head1 SYNOPSIS

  #!/usr/bin/perl -w
  use Weather::Com::Finder;

  # you have to fill in your ids from weather.com here
  my $PartnerId  = 'somepartnerid';
  my $LicenseKey = 'mylicense';

  my %weatherargs = (
	'partner_id' => $PartnerId,
	'license'    => $LicenseKey,
	'language'   => 'de',
  );

  my $weather_finder = Weather::Com::Finder->new(%weatherargs);
  
  my @locations = $weather_finder->find('Heidelberg');
  
  foreach my $location (@locations) {
    print "Found weather for city: ", $location->name(), "\n";
    print "Current Conditions are ", 
      $location->current_conditions()->description(), "\n";
  }

=head1 DESCRIPTION

I<Weather::Com> provides three interfaces to access weather
information from I<weather.com>. 

Except from the main high level interface, there is also
a simple, very easy to use one called I<Weather::Com::Simple>.
And if you want, you can also use the low level
interface that is the basis for the two high level interfaces,
directly (I<Weather::Com::Cached> or even I<Weather::Com::Base>).

Please refer to the POD of these modules directly for detailed
information.

The data provided by I<weather.com> and made accessible by this OO
interface can be used for free under special terms. Please have a look 
at the application programming guide of I<weather.com> 
L<http://www.weather.com/services/xmloap.html>

=head1 LOCALIZATION

Weather-Com uses I<Locale::Maketext> for the l10n. Foreach language there
has to be package I<Weather::Com::L10N::[langcode]> (e.g. I<Weather::Com::L10N::de>).

Localization is new with version 0.4 of Weather-Com. Therefore, there are not too
many languages supported, yet. If one wants to create such a language definition package
for a language that is not part of this module, please do the following:

=over 4

=item 1.

check my homepage to verify that the language package has not been created by someone
else, yet (L<http://www.schnuecker.org/index.php?weather-com>).

=item 2.

contact me to verify if anybody else already is already translating into this language

=item 3.

just do it and send me your new language package. It then will be first put onto my
website for download and then it will be part of the next release.

=back

=head2 Dynamic Language Support

With version 0.5 of Weather-Com I have introduced a new feature called 
I<dynamic language support>.

The language for all textual attributes that usually are translated in your default 
language you chose while creating your C<Weather::Com::Finder> instance can now
dynamically be changed on a I<per-method-call basis>.

Have a look at this example:

  #!/usr/bin/perl -w
  use Weather::Com::Finder;

  # you have to fill in your ids from weather.com here
  my $PartnerId  = 'somepartnerid';
  my $LicenseKey = 'mylicense';

  my %weatherargs = (
	'partner_id' => $PartnerId,
	'license'    => $LicenseKey,
	'language'   => 'en',
  );

  my $weather_finder = Weather::Com::Finder->new(%weatherargs);
  
  my @locations = $weather_finder->find('Heidelberg');
  
  foreach my $location (@locations) {
    print "Found weather for city: ", $location->name(), "\n";
    print "Current Conditions are ", 
      $location->current_conditions()->description(), "\n";
      
    # HERE WE USE DYNAMIC LANGUAGE SUPPORT
    print "That is in German: ",
      $location->current_conditions()->description('de'), "\n";
  }

As you can see in this example, you can provide a language tag to
a method that returns textual information.

If you want to find out if the I<dynamic language support> is already
implemented for a specific attribute of one Weather-Com class, have
a look at the corresponding packages POD.

=head1 TUTORIAL

The usual way to use the I<Weather::Com> module would be to instantiate
a I<Weather::Com::Finder> that allows you to search for a location
by a search string or postal code or whatever I<weather.com> may
understand.

The finder returns an arrayref or an array of locations (depending on 
how you call the C<find()> method). Each location is an object of
I<Weather::Com::Location>. 

The locations consist of location specific data, 
a I<Weather::Com::CurrentConditions> object, a I<Weather::Com::Forecast>
object and a I<Weather::Com::Units> object. 

=head2 Configuration parameters

You will need a configuration hash to instantiate a I<Weather::Com::Finder>
object. Except of the I<partner_id> and the I<license> all parameters are
optional and have sensible defaults. 

  use Weather::Com::Finder;

  my %config = (
  	partner_id => 'somepartnerid',	# mandatory
  	license    => 'somelicensekey'	# mandatory
  	language   => 'de',
  	units      => 's',
   	cache      => '/tmp/weather',
   	timeout    => 300,
   	debug      => 1,
  	proxy      => 'http://some.proxy.de:8080',
  	proxy_user => 'myaccount',
  	proxy_pass => 'myproxy_pass'
  );

The valid parameters are:

=over 4

=item partner_id => 'somepartnerid'

To be allowed to fetch weather information from I<weather.com> you need to
register (free of charge) to get a so called I<Partner Id> and a 
I<License Key>. 

=item license => 'somelicensekey'

See I<partner_id>.

=item language => 'somelanguagecode'

I<weather.com> returns some textual data to describe the weather
conditions, uv index, moon phase, wind direction, etc.

If one specifies a valid language as configuration parameter, this
textual descriptions are translated into that language. If one specifies
a language for that there's no translation, the objects will return the
english texts.

=item cache => '/any/path'

Maybe you want to define a special path to put the cache files into.
The cache directory defaults to ".".

=item units => s | m

This parameter defines whether to fetch information in metric (m) or 
US (s) format. 

Defaults to 'm'.

=item timeout => some integer (in seconds)

The timeout for I<LWP::UserAgent> to get an HTTP request done usually is set to
180s. If you need a longer timeout or for some reasons a shorter one you can
set this here.

Defaults to 180 seconds.

=item debug => 0 | 1

Set debugging on/off.

Defaults to 0 (off).

=item proxy => 'none' | 'http://some.proxy.de:8080'

Usually no proxy is used by the I<LWP::UserAgent> module used to communicate
with I<weather.com>. If you want to use an HTTP proxy you can specify one here.

=item proxy_user => undef | 'myuser'

If specified, this parameter is provided to the proxy for authentication
purposes.

Defaults to I<undef>.

=item proxy_pass => undef | 'mypassword'

If specified, this parameter is provided to the proxy for authentication
purposes.

Defaults to I<undef>.

=back 

=head2 Weather::Com::Finder

Usually one would start by searching for a location. This is done by
instantiating a I<Weather::Com::Finder> object providing all necessary
information about the I<weather.com> license, the proxy if one is needed,
etc.  

  my $finder = Weather::Com::Finder->new(%config);

Then you call the finders C<find()> method to search for locations whose
name or whose postal code matches against the searchstring. The finder then
returns an array (or arrayref) of I<Weather::Com::Location> objects.

  # if you want an array of locations:
  my @locations = $finder->find('Heidelberg');
  
  # or if you prefer an arrayref:
  my $locations = $finder->find('Heidelberg');

For further information please refer to L<Weather::Com::Finder>.

=head2 Weather::Com::Location

The I<Weather::Com::Location> object contains information about the location
itself (longitude, latitude, current local time, etc.), a I<Weather::Com::Units> 
object that contains all information about the units of messures currently used with
this location, and a I<Weather::Com::CurrentConditions> object containing the
current weather conditions of the location.

  foreach my $location (@locations) {
  	print "Found location with name: ", $location->name(), "\n";
  	print "The longitude of this location is: ", $location->longitude(), "\n";
  }

All information in the I<Weather::Com::Location> object is updated with each single
call of one of its methods corresponding to the caching rules implemented in
I<Weather::Com::Cached>.

For detailed information about the I<Weather::Com::Location> class please refer to
L<Weather::Com::Location>.

=head2 Weather::Com::Units

The units class provides all units of measure corresponding to the data of the
location object. You'll get an instance of this class by calling the C<units()>
method of your location object.

For detailed information about the I<Weather::Com::Units> class please refer to
L<Weather::Com::Units>.

=head2 Weather::Com::CurrentConditions

Each location has a I<Weather::Com::CurrentConditions> object accessible via
its C<current_conditions()> method.

  my $conditions = $location->current_conditions();
  print "Current temperature is ", $conditions->temperature(), "°C\n";
  print "but it feels like ", $conditions->windchill(), "°C!\n";

Anytime you call a method of your I<Weather::Com::CurrentConditions> object,
its data is refreshed automatically if needed according to the caching rules.

For detailed information about this class please refer to
L<Weather::Com::CurrentConditions>.

=head2 Weather::Com::Forecast

Each location has a I<Weather::Com::Forecast> object to access weather
forecasts. I<weather.com> provides up to 9 days of forecast - or 10 days
if one wants to count day 0 which is I<today> in most cases.

  my $forecast = $location->forecast();
  print "Max. temperature tomorrow will be ", $forecast->day(1)->high(), "°C\n";

Any time you call a method of your I<Weather::Com::Forecast> object, forecast data
is updated if necessary.

For detailed information about this class please refer to
L<Weather::Com::Forecast>.

=head2 Other classes

There are a some other classes that are used to represent groups of
weather data like wind (speed, direction, etc.), UV index, air pressure, etc.

Objects of these classes belong to objects of class I<Weather::Com::CurrentConditions> or
I<Weather::Com::Forecast> that will be introduced with the next release. These
objects data will only refresh when you call the corresponding method of the parent object.

For detailed information about these classes please refer to their own POD.

Classes available with this version are:

=head3 Weather::Com::AirPressure

Provides access to the barometric pressure data.

For detailed information about this class please refer to
L<Weather::Com::AirPressure>.

=head3 Weather::Com::UVIndex

Provides access to the uv index of the parent object.

For detailed information about this class please refer to
L<Weather::Com::UVIndex>.

=head3 Weather::Com::Wind

Provides access to wind speed, maximum gust, direction in degrees, etc.

=head1 EXTENSIONS

If you plan to extend these module, e.g. with some other caching mechanisms,
please contact me. Perhaps we can add your stuff to this module.

=head1 SEE ALSO

=head2 Detailed documentation of the main interface

L<Weather::Com::Finder>, L<Weather::Com::Location>, L<Weather::Com::Units>,
L<Weather::Com::CurrentConditions>, L<Weather::Com::AirPressure>,
L<Weather::Com::UVIndex>, L<Weather::Com::Wind>

=head2 Detailed documentation of the I<Simple> API

L<Weather::Com::Simple>

=head2 Detailed documentation of the low level interface

L<Weather::Com::Cached> and L<Weather::Com::Base>

=head1 BUGS/SUPPORT/PRE-RELEASES

If you want to report a bug, please use the CPAN bug reporting tool.

If you have any question, suggestion, feature request, etc. please use the
CPAN forum.

If you are looking for fixes, pre-releases, etc. have a look at my website
L<http://www.schnuecker.org/index.php?weather-com>.

=head1 AUTHOR

Thomas Schnuecker, E<lt>thomas@schnuecker.deE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2004-2007 by Thomas Schnuecker

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

The data provided by I<weather.com> and made accessible by this OO
interface can be used for free under special terms. 
Please have a look at the application programming guide of
I<weather.com> (L<http://www.weather.com/services/xmloap.html>)

=cut