.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Weather::Com 3pm" .TH Weather::Com 3pm "2007-07-09" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" Weather::Com \- fetching weather information from \fIweather.com\fR .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& #!/usr/bin/perl \-w \& use Weather::Com::Finder; .Ve .PP .Vb 3 \& # you have to fill in your ids from weather.com here \& my $PartnerId = \(aqsomepartnerid\(aq; \& my $LicenseKey = \(aqmylicense\(aq; .Ve .PP .Vb 5 \& my %weatherargs = ( \& \(aqpartner_id\(aq => $PartnerId, \& \(aqlicense\(aq => $LicenseKey, \& \(aqlanguage\(aq => \(aqde\(aq, \& ); .Ve .PP .Vb 1 \& my $weather_finder = Weather::Com::Finder\->new(%weatherargs); .Ve .PP .Vb 1 \& my @locations = $weather_finder\->find(\(aqHeidelberg\(aq); .Ve .PP .Vb 5 \& foreach my $location (@locations) { \& print "Found weather for city: ", $location\->name(), "\en"; \& print "Current Conditions are ", \& $location\->current_conditions()\->description(), "\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIWeather::Com\fR provides three interfaces to access weather information from \fIweather.com\fR. .PP Except from the main high level interface, there is also a simple, very easy to use one called \fIWeather::Com::Simple\fR. And if you want, you can also use the low level interface that is the basis for the two high level interfaces, directly (\fIWeather::Com::Cached\fR or even \fIWeather::Com::Base\fR). .PP Please refer to the \s-1POD\s0 of these modules directly for detailed information. .PP The data provided by \fIweather.com\fR and made accessible by this \s-1OO\s0 interface can be used for free under special terms. Please have a look at the application programming guide of \fIweather.com\fR .SH "LOCALIZATION" .IX Header "LOCALIZATION" Weather-Com uses \fILocale::Maketext\fR for the l10n. Foreach language there has to be package \fIWeather::Com::L10N::[langcode]\fR (e.g. \fIWeather::Com::L10N::de\fR). .PP 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: .IP "1." 4 check my homepage to verify that the language package has not been created by someone else, yet (). .IP "2." 4 contact me to verify if anybody else already is already translating into this language .IP "3." 4 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. .Sh "Dynamic Language Support" .IX Subsection "Dynamic Language Support" With version 0.5 of Weather-Com I have introduced a new feature called \&\fIdynamic language support\fR. .PP The language for all textual attributes that usually are translated in your default language you chose while creating your \f(CW\*(C`Weather::Com::Finder\*(C'\fR instance can now dynamically be changed on a \fIper-method-call basis\fR. .PP Have a look at this example: .PP .Vb 2 \& #!/usr/bin/perl \-w \& use Weather::Com::Finder; .Ve .PP .Vb 3 \& # you have to fill in your ids from weather.com here \& my $PartnerId = \(aqsomepartnerid\(aq; \& my $LicenseKey = \(aqmylicense\(aq; .Ve .PP .Vb 5 \& my %weatherargs = ( \& \(aqpartner_id\(aq => $PartnerId, \& \(aqlicense\(aq => $LicenseKey, \& \(aqlanguage\(aq => \(aqen\(aq, \& ); .Ve .PP .Vb 1 \& my $weather_finder = Weather::Com::Finder\->new(%weatherargs); .Ve .PP .Vb 1 \& my @locations = $weather_finder\->find(\(aqHeidelberg\(aq); .Ve .PP .Vb 4 \& foreach my $location (@locations) { \& print "Found weather for city: ", $location\->name(), "\en"; \& print "Current Conditions are ", \& $location\->current_conditions()\->description(), "\en"; .Ve .PP .Vb 4 \& # HERE WE USE DYNAMIC LANGUAGE SUPPORT \& print "That is in German: ", \& $location\->current_conditions()\->description(\(aqde\(aq), "\en"; \& } .Ve .PP As you can see in this example, you can provide a language tag to a method that returns textual information. .PP If you want to find out if the \fIdynamic language support\fR is already implemented for a specific attribute of one Weather-Com class, have a look at the corresponding packages \s-1POD\s0. .SH "TUTORIAL" .IX Header "TUTORIAL" The usual way to use the \fIWeather::Com\fR module would be to instantiate a \fIWeather::Com::Finder\fR that allows you to search for a location by a search string or postal code or whatever \fIweather.com\fR may understand. .PP The finder returns an arrayref or an array of locations (depending on how you call the \f(CW\*(C`find()\*(C'\fR method). Each location is an object of \&\fIWeather::Com::Location\fR. .PP The locations consist of location specific data, a \fIWeather::Com::CurrentConditions\fR object, a \fIWeather::Com::Forecast\fR object and a \fIWeather::Com::Units\fR object. .Sh "Configuration parameters" .IX Subsection "Configuration parameters" You will need a configuration hash to instantiate a \fIWeather::Com::Finder\fR object. Except of the \fIpartner_id\fR and the \fIlicense\fR all parameters are optional and have sensible defaults. .PP .Vb 1 \& use Weather::Com::Finder; .Ve .PP .Vb 12 \& my %config = ( \& partner_id => \(aqsomepartnerid\(aq, # mandatory \& license => \(aqsomelicensekey\(aq # mandatory \& language => \(aqde\(aq, \& units => \(aqs\(aq, \& cache => \(aq/tmp/weather\(aq, \& timeout => 300, \& debug => 1, \& proxy => \(aqhttp://some.proxy.de:8080\(aq, \& proxy_user => \(aqmyaccount\(aq, \& proxy_pass => \(aqmyproxy_pass\(aq \& ); .Ve .PP The valid parameters are: .IP "partner_id => 'somepartnerid'" 4 .IX Item "partner_id => 'somepartnerid'" To be allowed to fetch weather information from \fIweather.com\fR you need to register (free of charge) to get a so called \fIPartner Id\fR and a \&\fILicense Key\fR. .IP "license => 'somelicensekey'" 4 .IX Item "license => 'somelicensekey'" See \fIpartner_id\fR. .IP "language => 'somelanguagecode'" 4 .IX Item "language => 'somelanguagecode'" \&\fIweather.com\fR returns some textual data to describe the weather conditions, uv index, moon phase, wind direction, etc. .Sp 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. .IP "cache => '/any/path'" 4 .IX Item "cache => '/any/path'" Maybe you want to define a special path to put the cache files into. The cache directory defaults to \*(L".\*(R". .IP "units => s | m" 4 .IX Item "units => s | m" This parameter defines whether to fetch information in metric (m) or \&\s-1US\s0 (s) format. .Sp Defaults to 'm'. .IP "timeout => some integer (in seconds)" 4 .IX Item "timeout => some integer (in seconds)" The timeout for \fILWP::UserAgent\fR to get an \s-1HTTP\s0 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. .Sp Defaults to 180 seconds. .IP "debug => 0 | 1" 4 .IX Item "debug => 0 | 1" Set debugging on/off. .Sp Defaults to 0 (off). .IP "proxy => 'none' | 'http://some.proxy.de:8080'" 4 .IX Item "proxy => 'none' | 'http://some.proxy.de:8080'" Usually no proxy is used by the \fILWP::UserAgent\fR module used to communicate with \fIweather.com\fR. If you want to use an \s-1HTTP\s0 proxy you can specify one here. .IP "proxy_user => undef | 'myuser'" 4 .IX Item "proxy_user => undef | 'myuser'" If specified, this parameter is provided to the proxy for authentication purposes. .Sp Defaults to \fIundef\fR. .IP "proxy_pass => undef | 'mypassword'" 4 .IX Item "proxy_pass => undef | 'mypassword'" If specified, this parameter is provided to the proxy for authentication purposes. .Sp Defaults to \fIundef\fR. .Sh "Weather::Com::Finder" .IX Subsection "Weather::Com::Finder" Usually one would start by searching for a location. This is done by instantiating a \fIWeather::Com::Finder\fR object providing all necessary information about the \fIweather.com\fR license, the proxy if one is needed, etc. .PP .Vb 1 \& my $finder = Weather::Com::Finder\->new(%config); .Ve .PP Then you call the finders \f(CW\*(C`find()\*(C'\fR method to search for locations whose name or whose postal code matches against the searchstring. The finder then returns an array (or arrayref) of \fIWeather::Com::Location\fR objects. .PP .Vb 2 \& # if you want an array of locations: \& my @locations = $finder\->find(\(aqHeidelberg\(aq); .Ve .PP .Vb 2 \& # or if you prefer an arrayref: \& my $locations = $finder\->find(\(aqHeidelberg\(aq); .Ve .PP For further information please refer to Weather::Com::Finder. .Sh "Weather::Com::Location" .IX Subsection "Weather::Com::Location" The \fIWeather::Com::Location\fR object contains information about the location itself (longitude, latitude, current local time, etc.), a \fIWeather::Com::Units\fR object that contains all information about the units of messures currently used with this location, and a \fIWeather::Com::CurrentConditions\fR object containing the current weather conditions of the location. .PP .Vb 4 \& foreach my $location (@locations) { \& print "Found location with name: ", $location\->name(), "\en"; \& print "The longitude of this location is: ", $location\->longitude(), "\en"; \& } .Ve .PP All information in the \fIWeather::Com::Location\fR object is updated with each single call of one of its methods corresponding to the caching rules implemented in \&\fIWeather::Com::Cached\fR. .PP For detailed information about the \fIWeather::Com::Location\fR class please refer to Weather::Com::Location. .Sh "Weather::Com::Units" .IX Subsection "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 \f(CW\*(C`units()\*(C'\fR method of your location object. .PP For detailed information about the \fIWeather::Com::Units\fR class please refer to Weather::Com::Units. .Sh "Weather::Com::CurrentConditions" .IX Subsection "Weather::Com::CurrentConditions" Each location has a \fIWeather::Com::CurrentConditions\fR object accessible via its \f(CW\*(C`current_conditions()\*(C'\fR method. .PP .Vb 3 \& my $conditions = $location\->current_conditions(); \& print "Current temperature is ", $conditions\->temperature(), "°C\en"; \& print "but it feels like ", $conditions\->windchill(), "°C!\en"; .Ve .PP Anytime you call a method of your \fIWeather::Com::CurrentConditions\fR object, its data is refreshed automatically if needed according to the caching rules. .PP For detailed information about this class please refer to Weather::Com::CurrentConditions. .Sh "Weather::Com::Forecast" .IX Subsection "Weather::Com::Forecast" Each location has a \fIWeather::Com::Forecast\fR object to access weather forecasts. \fIweather.com\fR provides up to 9 days of forecast \- or 10 days if one wants to count day 0 which is \fItoday\fR in most cases. .PP .Vb 2 \& my $forecast = $location\->forecast(); \& print "Max. temperature tomorrow will be ", $forecast\->day(1)\->high(), "°C\en"; .Ve .PP Any time you call a method of your \fIWeather::Com::Forecast\fR object, forecast data is updated if necessary. .PP For detailed information about this class please refer to Weather::Com::Forecast. .Sh "Other classes" .IX Subsection "Other classes" There are a some other classes that are used to represent groups of weather data like wind (speed, direction, etc.), \s-1UV\s0 index, air pressure, etc. .PP Objects of these classes belong to objects of class \fIWeather::Com::CurrentConditions\fR or \&\fIWeather::Com::Forecast\fR that will be introduced with the next release. These objects data will only refresh when you call the corresponding method of the parent object. .PP For detailed information about these classes please refer to their own \s-1POD\s0. .PP Classes available with this version are: .PP \fIWeather::Com::AirPressure\fR .IX Subsection "Weather::Com::AirPressure" .PP Provides access to the barometric pressure data. .PP For detailed information about this class please refer to Weather::Com::AirPressure. .PP \fIWeather::Com::UVIndex\fR .IX Subsection "Weather::Com::UVIndex" .PP Provides access to the uv index of the parent object. .PP For detailed information about this class please refer to Weather::Com::UVIndex. .PP \fIWeather::Com::Wind\fR .IX Subsection "Weather::Com::Wind" .PP Provides access to wind speed, maximum gust, direction in degrees, etc. .SH "EXTENSIONS" .IX Header "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. .SH "SEE ALSO" .IX Header "SEE ALSO" .Sh "Detailed documentation of the main interface" .IX Subsection "Detailed documentation of the main interface" Weather::Com::Finder, Weather::Com::Location, Weather::Com::Units, Weather::Com::CurrentConditions, Weather::Com::AirPressure, Weather::Com::UVIndex, Weather::Com::Wind .Sh "Detailed documentation of the \fISimple\fP \s-1API\s0" .IX Subsection "Detailed documentation of the Simple API" Weather::Com::Simple .Sh "Detailed documentation of the low level interface" .IX Subsection "Detailed documentation of the low level interface" Weather::Com::Cached and Weather::Com::Base .SH "BUGS/SUPPORT/PRE\-RELEASES" .IX Header "BUGS/SUPPORT/PRE-RELEASES" If you want to report a bug, please use the \s-1CPAN\s0 bug reporting tool. .PP If you have any question, suggestion, feature request, etc. please use the \&\s-1CPAN\s0 forum. .PP If you are looking for fixes, pre\-releases, etc. have a look at my website . .SH "AUTHOR" .IX Header "AUTHOR" Thomas Schnuecker, .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2004\-2007 by Thomas Schnuecker .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The data provided by \fIweather.com\fR and made accessible by this \s-1OO\s0 interface can be used for free under special terms. Please have a look at the application programming guide of \&\fIweather.com\fR ()