.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "App::Cache 3pm"
.TH App::Cache 3pm "2009-12-08" "perl v5.18.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::Cache \- Easy application\-level caching
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  # in your class:
\&  my $cache = App::Cache\->new({ ttl => 60*60 });
\&  $cache\->delete(\*(Aqtest\*(Aq);
\&  my $data = $cache\->get(\*(Aqtest\*(Aq);
\&  my $code = $cache\->get_code("code", sub { $self\->calculate() });
\&  my $html = $cache\->get_url("http://www.google.com/");
\&  $cache\->set(\*(Aqtest\*(Aq, \*(Aqone\*(Aq);
\&  $cache\->set(\*(Aqtest\*(Aq, { foo => \*(Aqbar\*(Aq });
\&  my $scratch = $cache\->scratch;
\&  $cache\->clear;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The App::Cache module lets an application cache data locally. There
are a few times an application would need to cache data: when it is
retrieving information from the network or when it has to complete a
large calculation.
.PP
For example, the Parse::BACKPAN::Packages module downloads a file off
the net and parses it, creating a data structure. Only then can it
actually provide any useful information for the programmer.
Parse::BACKPAN::Packages uses App::Cache to cache both the file
download and data structures, providing much faster use when the data is
cached.
.PP
This module stores data in the home directory of the user, in a dot
directory. For example, the Parse::BACKPAN::Packages cache is
actually stored underneath \*(L"~/.parse_backpan_packages/cache/\*(R". This is
so that permisssions are not a problem \- it is a per-user,
per-application cache.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
The constructor creates an App::Cache object. It takes three optional
parameters:
.IP "\(bu" 4
ttl contains the number of seconds in which a cache entry expires. The default
is 30 minutes.
.Sp
.Vb 1
\&  my $cache = App::Cache\->new({ ttl => 30*60 });
.Ve
.IP "\(bu" 4
application sets the application name. If you are calling \fInew()\fR from a class,
the application is automagically set to the calling class, so you should rarely
need to pass it in:
.Sp
.Vb 1
\&  my $cache = App::Cache\->new({ application => \*(AqYour::Module\*(Aq });
.Ve
.IP "\(bu" 4
directory sets the directory to be used for the cache. Normally this is just
set for you and will be based on the application name and be created in the
users home directory. Sometimes for testing, it can be useful to set this.
.Sp
.Vb 1
\&  my $cache = App::Cache\->new({ directory => \*(Aq/tmp/your/cache/dir\*(Aq });
.Ve
.IP "\(bu" 4
enabled can be set to 0 for testing, in which case you will always get
cache misses:
.Sp
.Vb 1
\&  my $cache = App::Cache\->new({ enabled => 0 });
.Ve
.SS "clear"
.IX Subsection "clear"
Clears the cache:
.PP
.Vb 1
\&  $cache\->clear;
.Ve
.SS "delete"
.IX Subsection "delete"
Deletes an entry in the cache:
.PP
.Vb 1
\&  $cache\->delete(\*(Aqtest\*(Aq);
.Ve
.SS "get"
.IX Subsection "get"
Gets an entry from the cache. Returns undef if the entry does not exist
or if it has expired:
.PP
.Vb 1
\&  my $data = $cache\->get(\*(Aqtest\*(Aq);
.Ve
.SS "get_code"
.IX Subsection "get_code"
This is a convenience method. Gets an entry from the cache, but if the
entry does not exist, set the entry to the value of the code reference
passed:
.PP
.Vb 1
\&  my $code = $cache\->get_code("code", sub { $self\->calculate() });
.Ve
.SS "get_url"
.IX Subsection "get_url"
This is a convenience method. Gets the content of a \s-1URL\s0 from the cache,
but if the entry does not exist, set the entry to the content of the \s-1URL\s0
passed:
.PP
.Vb 1
\&  my $html = $cache\->get_url("http://www.google.com/");
.Ve
.SS "scratch"
.IX Subsection "scratch"
Returns a directory in the cache that the application may use for
scratch files:
.PP
.Vb 1
\&  my $scratch = $cache\->scratch;
.Ve
.SS "set"
.IX Subsection "set"
Set an entry in the cache. Note that an entry value may be an arbitrary
Perl data structure:
.PP
.Vb 2
\&  $cache\->set(\*(Aqtest\*(Aq, \*(Aqone\*(Aq);
\&  $cache\->set(\*(Aqtest\*(Aq, { foo => \*(Aqbar\*(Aq });
.Ve
.SS "directory"
.IX Subsection "directory"
Returns the full path to the cache directory. Primarily useful for when you
are writing tests that use App::Cache and want to clean up after yourself. If
you are doing that you may want to explicitly set the 'application' constructor
parameter to avoid later cleaning up a cache dir that was already in use.
.PP
.Vb 1
\&  my $dir = $cache\->directory;
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Leon Brocard <acme@astray.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2005\-7, Leon Brocard
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it or modify it under
the same terms as Perl itself.