.\" 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::Cached 3pm" .TH Weather::Com::Cached 3pm "2007-07-09" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" Weather::Com::Cached \- Perl extension for getting weather information from \fIweather.com\fR .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Data::Dumper; \& use Weather::Com::Cached; .Ve .PP .Vb 13 \& # define parameters for weather search \& my %params = ( \& \(aqcache\(aq => \(aq/tmp/weathercache\(aq, \& \(aqcurrent\(aq => 1, \& \(aqforecast\(aq => 3, \& \(aqlinks\(aq => 1, \& \(aqunits\(aq => \(aqs\(aq, \& \(aqproxy\(aq => \(aqhttp://proxy.sonstwo.de\(aq, \& \(aqtimeout\(aq => 250, \& \(aqdebug\(aq => 1, \& \(aqpartner_id\(aq => \(aqsomepartnerid\(aq, \& \(aqlicense\(aq => \(aq12345678\(aq, \& ); .Ve .PP .Vb 2 \& # instantiate a new weather.com object \& my $cached_weather = Weather::Com::Cached\->new(%params); .Ve .PP .Vb 3 \& # search for locations called \(aqHeidelberg\(aq \& my $locations = $cached_weather\->search(\(aqHeidelberg\(aq) \& or die "No location found!\en"; .Ve .PP .Vb 5 \& # and then get the weather for each location found \& foreach (keys %{$locations}) { \& my $weather = $cached_weather\->get_weather($_); \& print Dumper($weather); \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIWeather::Com::Cached\fR is a Perl module that provides low level \s-1OO\s0 interface to gather all weather information that is provided by \fIweather.com\fR. .PP Please refer to Weather::Com for the high level interfaces. .PP This module implements the caching business rules that apply to all applications programmed against the \fIxoap\fR \s-1API\s0 of \fIweather.com\fR. Except from the \fIcache\fR parameter to be used while instantiating a new object instance, this module has the same \s-1API\s0 than \fIWeather::Com::Base\fR. It's only a simple caching wrapper around it. .PP The caching mechanism for location searches is very simple. We assume that location codes on \fIweather.com\fR will never change. Therefore, a search string that has been successfully used once to search for locations will never cause another search on the web. Each location search results will be stored in the file \f(CW\*(C`locations.dat\*(C'\fR. If you want to refresh your locations cache, simply delete this file. .PP Although it's really simple, the module uses \fIStorable\fR methods \&\fIlock_store\fR and \fIlock_retrieve\fR to implement shared locking for reading cache files and exclusive locking for writing to chache files. By this way the same cache files should be able to be used by several application instances using \fIWeather::Com::Cached\fR. .PP You'll need to register at \fIweather.com\fR to to get a free partner id and a license key to be used within all applications that you want to write against \fIweather.com\fR's \fIxoap\fR interface. .PP .SH "CHANGES" .IX Header "CHANGES" The location caching mechanism has been extended with version 0.4. Up to V0.4 searches were stored this way: .PP .Vb 8 \& $locations_cache = { \& \(aqNew York\(aq => { \& \(aqUSNY1000\(aq => \(aqNew York/La Guardia Arpt, NY\(aq, \& \(aqUSNY0998\(aq => \(aqNew York/Central Park, NY\(aq, \& \(aqUSNY0999\(aq => \(aqNew York/JFK Intl Arpt, NY\(aq, \& \(aqUSNY0996\(aq => \(aqNew York, NY\(aq \& }, \& } .Ve .PP This has changed the way it does not only store a .PP .Vb 1 \& search_string => locations .Ve .PP hash. The cache now also stores a hash for \fBeach\fR location name found: .PP .Vb 20 \& $locations_cache => { \& \(aqnew york\(aq => { \& \(aqUSNY1000\(aq => \(aqNew York/La Guardia Arpt, NY\(aq, \& \(aqUSNY0998\(aq => \(aqNew York/Central Park, NY\(aq, \& \(aqUSNY0999\(aq => \(aqNew York/JFK Intl Arpt, NY\(aq, \& \(aqUSNY0996\(aq => \(aqNew York, NY\(aq \& }, \& \(aqnew york/central park, ny\(aq => { \& \(aqUSNY0998\(aq => \(aqNew York/Central Park, NY\(aq \& }, \& \(aqnew york/la guardia arpt, ny\(aq => { \& \(aqUSNY1000\(aq => \(aqNew York/La Guardia Arpt, NY\(aq \& }, \& \(aqnew york, ny\(aq => { \& \(aqUSNY0996\(aq => \(aqNew York, NY\(aq \& }, \& \(aqnew york/jfk intl arpt, ny\(aq => { \& \(aqUSNY0999\(aq => \(aqNew York/JFK Intl Arpt, NY\(aq \& }, \& } .Ve .PP The new mechanism has the following advantages: .IP "1." 4 The new chaching mechanism is \fBcase insensitive\fR .IP "2." 4 This caching mechanism is a workaround one problem with \fIweather.com\fR's \&\s-1XOAP\s0 \s-1API\s0. .Sp Their server does not understand any search string with a '/' in it \- no matter wether the '/' is \s-1URL\s0 encoded or not! .Sp This way, if you have searched for \fINew York\fR once, you'll then also get a result for direct calls to \fINew York/Jfk Intl Arpt, \s-1NY\s0\fR. .IP "3." 4 The new mechanism also allows searches for \fIslashed\fR substrings. A search for \fIYork/Central\fR will return the \fINew York/Central Park, \s-1NY\s0\fR location and if you simply search \fIYork\fR, you'll get anything containing \fIYork\fR. No matter if it's in the cache or not. .Sp Only if you specify \fBexactly\fR the name of a location in the cache, only this location is shown. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .Sh "new(hash or hashref)" .IX Subsection "new(hash or hashref)" This constructor takes the same hash or hashref as \fIWeather::Com::Base\fR does. Please refer to that documentation for further details. .PP Except from the \fIWeather::Com::Base\fR's parameters this constructor takes a parameter \fIcache\fR which defines the path to a directory into which all cache files will be put. .PP The cache directory defaults to '.'. .SH "METHODS" .IX Header "METHODS" .Sh "search(search string)" .IX Subsection "search(search string)" The \f(CW\*(C`search()\*(C'\fR method has the same interface as the one of \&\fIWeather::Com::Base\fR. The difference is made by the caching. .PP The search is performed in the following order: .IP "1." 4 If there's a direct match in the locations cache, return the locations from the cache. .IP "2." 4 If not, if there's a direct match on the web, return the locations found on the web and write the search result to the cache. .IP "3." 4 If not, try a regexp search over all cached search strings and location names. This will return each location that matches the search string. .PP The rest is all the same as for \fIWeather::Com::Base\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" See also documentation of Weather::Com and Weather::Com::Base. .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! .PP