Permalink
Browse files

Bumps version to 1.41 and updates docs

  • Loading branch information...
1 parent 0fff7ba commit 7fd66875e4955e3195929f1b6af6c0953a5ec041 @oalders oalders committed Jun 27, 2012
Showing with 115 additions and 76 deletions.
  1. +5 −2 Changes
  2. +70 −27 README
  3. +15 −12 dist.ini
  4. +25 −35 lib/WWW/Mechanize/Cached.pm
View
@@ -1,12 +1,15 @@
Revision history for Perl extension WWW::Mechanize::Cached
+1.41 2012-06-27
+ - Account for content length when deciding whether to cache (Kent Fredric)
+
1.40 2010-10-18
- Fixed file prefix in cache_key.t when run under Windows
1.39 2010-10-09
- live tests now skip if we can't connect to the live URL
- Storable now has a specific version prerequisite
-
+
1.38 2010-10-07
- cache_key test should now be portable to Windows
- Critic test removed as Dist::Zilla runs this test automatically
@@ -32,7 +35,7 @@ Revision history for Perl extension WWW::Mechanize::Cached
- Added first example script
- Expanded documentation re: custom caches
- Removed some outdated files from distro
-
+
1.33 2009-07-13
- Now maintained by Olaf Alders. Thanks to Andy Lester for offering
to let me take this on.
View
@@ -2,7 +2,7 @@ NAME
WWW::Mechanize::Cached - Cache response to be polite
VERSION
- version 1.40
+ version 1.41
SYNOPSIS
use WWW::Mechanize::Cached;
@@ -13,20 +13,22 @@ SYNOPSIS
# or, with your own Cache object
use CHI;
use WWW::Mechanize::Cached;
-
+
my $cache = CHI->new(
driver => 'File',
root_dir => '/tmp/mech-example'
);
-
+
my $mech = WWW::Mechanize::Cached->new( cache => $cache );
- $mech->get("http://www.google.com");
+ $mech->get("http://www.wikipedia.org");
DESCRIPTION
- Uses the Cache::Cache hierarchy to implement a caching Mech. This lets
- one perform repeated requests without hammering a server impolitely.
-
- Repository: <http://github.com/oalders/www-mechanize-cached/tree/master>
+ Uses the Cache::Cache hierarchy by default to implement a caching Mech.
+ This lets one perform repeated requests without hammering a server
+ impolitely. Please note that Cache::Cache has been superceded by CHI,
+ but the default has not been changed here for reasons of backwards
+ compatibility. For this reason, you are encouraged to provide your own
+ CHI caching object to override the default.
CONSTRUCTOR
new
@@ -43,7 +45,7 @@ CONSTRUCTOR
my $cache_params = {
default_expires_in => "1d", namespace => 'www-mechanize-cached',
};
-
+
$cache = Cache::FileCache->new( $cache_params );
This should be fine if you only want to use a disk-based cache, you only
@@ -56,14 +58,14 @@ CONSTRUCTOR
use WWW::Mechanize::Cached;
use CHI;
-
+
my $cache = CHI->new(
driver => 'File',
root_dir => '/tmp/mech-example'
);
-
+
my $mech = WWW::Mechanize::Cached->new( cache => $cache );
- $mech->get("http://www.google.com");
+ $mech->get("http://www.wikipedia.org");
METHODS
Most methods are provided by WWW::Mechanize. See that module's
@@ -106,34 +108,75 @@ METHODS
See RT #56757 for a detailed example of the bugs this functionality can
trigger.
-THANKS
- Iain Truskett for writing this in the first place.
+ cache_undef_content_length( 0 | 'warn' | 1 )
+ This is configuration option which adjusts how caching behaviour
+ performs when the Content-Length header is not specified by the server.
-SUPPORT
- You can find documentation for this module with the perldoc command.
+ Default behaviour is 0, which is not to cache.
- perldoc WWW::Mechanize::Cached
+ Setting this value to 1, will cache pages even if the Content-Length
+ header is missing, which was the default behaviour prior to the addition
+ of this feature.
+
+ And thirdly, you can set the value to the string 'warn', to warn if this
+ scenario occurs, and then not cache it.
- You can also look for information at:
+ cache_zero_content_length( 0 | 'warn' | 1 )
+ This is configuration option which adjusts how caching behaviour
+ performs when the Content-Length header is equal to 0.
- * AnnoCPAN: Annotated CPAN documentation
+ Default behaviour is 0, which is not to cache.
- <http://annocpan.org/dist/WWW-Mechanize-Cached>
+ Setting this value to 1, will cache pages even if the Content-Length
+ header is 0, which was the default behaviour prior to the addition of
+ this feature.
- * CPAN Ratings
+ And thirdly, you can set the value to the string 'warn', to warn if this
+ scenario occurs, and then not cache it.
- <http://cpanratings.perl.org/d/WWW-Mechanize-Cached>
+ cache_mismatch_content_length( 0 | 'warn' | 1 )
+ This is configuration option which adjusts how caching behaviour
+ performs when the Content-Length header differs from the length of the
+ content itself. ( Which usually indicates a transmission error )
- * RT: CPAN's request tracker
+ Setting this value to 0, will silenly not cache pages with a
+ Content-Length mismatch.
- <http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Mechanize-Cached>
+ Setting this value to 1, will cache pages even if the Content-Length
+ header conflicts with the content length, which was the default
+ behaviour prior to the addition of this feature.
+
+ And thirdly, you can set the value to the string 'warn', to warn if this
+ scenario occurs, and then not cache it. ( This is the default behaviour
+ )
+
+UPGRADING FROM 1.40 OR EARLIER
+ Caching behaviour has changed since 1.40, and this may result in pages
+ that were previously cached start failing to cache, and in some cases,
+ emit warnings.
+
+ To return to the 1.40 behaviour:
+
+ $mech->cache_undef_content_length(1); # Default is 0
+ $mech->cache_zero_content_length(1); # Default is 0
+ $mech->cache_mismatch_content_length(1); # Default is 'warn'
+
+THANKS
+ Iain Truskett for writing this in the first place. Andy Lester for
+ graciously handing over maintainership. Kent Fredric for adding content
+ length handling.
+
+SUPPORT
+ You can find documentation for this module with the perldoc command.
+
+ perldoc WWW::Mechanize::Cached
* Search CPAN
- <http://search.cpan.org/dist/WWW-Mechanize-Cached>
+ <https://metacpan.org/module/WWW::Mechanize::Cached>
SEE ALSO
- WWW::Mechanize.
+ WWW::Mechanize, WWW::Mechanize::Cached::GZip.
AUTHORS
* Iain Truskett (original author)
@@ -143,7 +186,7 @@ AUTHORS
* Olaf Alders <olaf@wundercounter.com> (current maintainer)
COPYRIGHT AND LICENSE
- This software is copyright (c) 2010 by Iain Truskett and Andy Lester.
+ This software is copyright (c) 2012 by Iain Truskett and Andy Lester.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
View
@@ -1,20 +1,19 @@
-name = WWW-Mechanize-Cached
-
+name = WWW-Mechanize-Cached
author = Iain Truskett (original author)
-author = Andy Lester <petdance@cpan.org> (2004 - July 2009)
+author = Andy Lester <petdance@cpan.org> (2004 - July 2009)
author = Olaf Alders <olaf@wundercounter.com> (current maintainer)
license = Perl_5
-copyright_holder = Iain Truskett and Andy Lester
-copyright_year = 2010
-version = 1.40
+copyright_holder = Iain Truskett and Andy Lester
+copyright_year = 2012
+version = 1.41
main_module = lib/WWW/Mechanize/Cached.pm
[GatherDir]
[PruneCruft]
[ManifestSkip]
-[MetaYAML]
[License]
+[PodCoverageTests]
[ExtraTests]
[ExecDir]
[ShareDir]
@@ -28,18 +27,22 @@ main_module = lib/WWW/Mechanize/Cached.pm
[UploadToCPAN]
[MetaResources]
+[MetaJSON]
[Bugtracker]
+web = http://github.com/oalders/www-mechanize-cached/issues
[GithubMeta]
[AutoPrereqs]
-[CriticTests]
+[RemovePrereqs]
+ remove = TestCache
+[Prereqs]
+ Storable = 2.21
+
+[Test::Perl::Critic]
[ReadmeFromPod]
[InstallGuide]
[ModuleBuild]
[PodWeaver]
[CopyReadmeFromBuild]
-[RemovePrereqs]
- remove = TestCache
-[Prereqs]
- Storable = 2.21
+
@@ -24,7 +24,7 @@ sub new {
my $cache = delete $mech_args{cache};
if ( $cache ) {
- my $ok
+ my $ok
= ( ref( $cache ) ne "HASH" )
&& $cache->can( "get" )
&& $cache->can( "set" );
@@ -242,22 +242,24 @@ __PACKAGE__->meta->make_immutable( inline_constructor => 0 );
# or, with your own Cache object
use CHI;
use WWW::Mechanize::Cached;
-
+
my $cache = CHI->new(
driver => 'File',
root_dir => '/tmp/mech-example'
);
-
+
my $mech = WWW::Mechanize::Cached->new( cache => $cache );
- $mech->get("http://www.google.com");
-
+ $mech->get("http://www.wikipedia.org");
-=head1 DESCRIPTION
-Uses the L<Cache::Cache> hierarchy to implement a caching Mech. This lets one
-perform repeated requests without hammering a server impolitely.
+=head1 DESCRIPTION
-Repository: L<http://github.com/oalders/www-mechanize-cached/tree/master>
+Uses the L<Cache::Cache> hierarchy by default to implement a caching Mech. This
+lets one perform repeated requests without hammering a server impolitely.
+Please note that L<Cache::Cache> has been superceded by L<CHI>, but the default
+has not been changed here for reasons of backwards compatibility. For this
+reason, you are encouraged to provide your own L<CHI> caching object to
+override the default.
=head1 CONSTRUCTOR
@@ -276,28 +278,28 @@ The default Cache object is set up with the following params:
my $cache_params = {
default_expires_in => "1d", namespace => 'www-mechanize-cached',
};
-
+
$cache = Cache::FileCache->new( $cache_params );
-
-
+
+
This should be fine if you only want to use a disk-based cache, you only want
to cache results for 1 day and you're not in a shared hosting environment.
If any of this presents a problem for you, you should pass in your own Cache
object. These defaults will remain unchanged in order to maintain backwards
-compatibility.
+compatibility.
For example, you may want to try something like this:
use WWW::Mechanize::Cached;
use CHI;
-
+
my $cache = CHI->new(
driver => 'File',
root_dir => '/tmp/mech-example'
);
-
+
my $mech = WWW::Mechanize::Cached->new( cache => $cache );
- $mech->get("http://www.google.com");
+ $mech->get("http://www.wikipedia.org");
=head1 METHODS
@@ -325,13 +327,13 @@ negative cache quite easily:
# cache everything (404s, all 300s etc)
$mech->positive_cache( 0 );
-
+
=head2 ref_in_cache_key( 0|1 )
Allow the referring URL to be used when creating the cache key. This is off
by default. In almost all cases, you will not want to enable this, but it is
available to you for reasons of backwards compatibility and giving you enough
-rope to hang yourself.
+rope to hang yourself.
Previous to v1.36 the following was in the "BUGS AND LIMITATIONS" section:
@@ -400,37 +402,25 @@ To return to the 1.40 behaviour:
=head1 THANKS
Iain Truskett for writing this in the first place.
+Andy Lester for graciously handing over maintainership.
+Kent Fredric for adding content length handling.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WWW::Mechanize::Cached
-You can also look for information at:
-
-=over 4
-
-=item * AnnoCPAN: Annotated CPAN documentation
-
-L<http://annocpan.org/dist/WWW-Mechanize-Cached>
-
-=item * CPAN Ratings
-
-L<http://cpanratings.perl.org/d/WWW-Mechanize-Cached>
-
-=item * RT: CPAN's request tracker
-
-L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Mechanize-Cached>
+=over
=item * Search CPAN
-L<http://search.cpan.org/dist/WWW-Mechanize-Cached>
+L<https://metacpan.org/module/WWW::Mechanize::Cached>
=back
=head1 SEE ALSO
-L<WWW::Mechanize>.
+L<WWW::Mechanize>, L<WWW::Mechanize::Cached::GZip>.
=cut

0 comments on commit 7fd6687

Please sign in to comment.