.\" Automatically generated by Pod::Man 2.28 (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 "HTTP::Proxy::BodyFilter::save 3pm"
.TH HTTP::Proxy::BodyFilter::save 3pm "2017-06-28" "perl v5.20.2" "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"
HTTP::Proxy::BodyFilter::save \- A filter that saves transferred data to a file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use HTTP::Proxy;
\& use HTTP::Proxy::BodyFilter::save;
\&
\& my $proxy = HTTP::Proxy\->new;
\&
\& # save RFC files as we browse them
\& $proxy\->push_filter(
\& path => qr!/rfc\ed+.txt!,
\& mime => \*(Aqtext/plain\*(Aq,
\& response => HTTP::Proxy::BodyFilter::save\->new(
\& template => \*(Aq%f\*(Aq,
\& prefix => \*(Aqrfc\*(Aq,
\& keep_old => 1,
\& )
\& );
\&
\& $proxy\->start;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The HTTP::Proxy::BodyFilter::save filter can save \s-1HTTP\s0 messages (responses
or request) bodies to files. The name of the file is determined by a
template and the \s-1URI\s0 of the request.
.PP
Simply insert this filter in a filter stack, and it will save the data
as it flows through the proxy. Depending on where the filter is located
in the stack, the saved data can be more or less modified.
.PP
This filter \fIwill\fR create directories if it needs to!
.PP
\&\fINote:\fR Remember that the default \f(CW\*(C`mime\*(C'\fR parameter for \f(CW\*(C`push_filter()\*(C'\fR
is \f(CW\*(C`text/*\*(C'\fR and that you may need to change it for other \s-1MIME\s0 types.
.SS "Constructor"
.IX Subsection "Constructor"
The constructor accepts quite a few options. Most of them control
the construction of the filename that will be used to save the
response body. There are two options to compute this filename:
.IP "\(bu" 4
use a template
.IP "\(bu" 4
use your own filename creation routine
.PP
The template option uses the following options:
.IP "\fBtemplate\fR => \fIstring\fR" 4
.IX Item "template => string"
The file name is build from the \f(CW\*(C`template\*(C'\fR option. The following
placeholders are available:
.Sp
.Vb 8
\& %% a percent sign
\& %h the host
\& %p the path (no leading separator)
\& %d the path (filename removed)
\& %f the filename (or \*(Aqindex.html\*(Aq if absent)
\& %q the query string
\& %P the path and the query string,
\& separated by \*(Aq?\*(Aq (if the query string is not empty)
.Ve
.Sp
\&\f(CW\*(C`/\*(C'\fR in the \s-1URI\s0 path are replaced by the separator used by File::Spec.
.Sp
The result of the template is modified by the \fBno_host\fR, \fBno_dirs\fR
and \fBcut_dirs\fR.
.Sp
The default template is the local equivalent of the \f(CW\*(C`%h/%P\*(C'\fR Unix path.
.IP "\fBno_host\fR => \fIboolean\fR" 4
.IX Item "no_host => boolean"
The \f(CW\*(C`no_host\*(C'\fR option makes \f(CW%h\fR empty. Default is \fIfalse\fR.
.IP "\fBno_dirs\fR => \fIboolean\fR" 4
.IX Item "no_dirs => boolean"
The \f(CW\*(C`no_dirs\*(C'\fR option removes all directories from \f(CW%p\fR, \f(CW%P\fR and \f(CW%d\fR.
Default is \fIfalse\fR.
.IP "\fBcut_dirs\fR => \fInumber\fR" 4
.IX Item "cut_dirs => number"
The \f(CW\*(C`cut_dirs\*(C'\fR options removes the first \fIn\fR directories from the
content of \f(CW%p\fR, \f(CW%P\fR and \f(CW%d\fR. Default is \f(CW0\fR.
.IP "\fBprefix\fR => \fIstring\fR" 4
.IX Item "prefix => string"
The \fBprefix\fR option prepends the given prefix to the filename
created from the template. Default is \f(CW""\fR.
.PP
Using your own subroutine is also possible, with the following parameter:
.IP "\fBfilename\fR => \fIcoderef\fR" 4
.IX Item "filename => coderef"
When the \f(CW\*(C`filename\*(C'\fR option is used, the \f(CW\*(C`template\*(C'\fR option and the
other template-related options (\f(CW\*(C`no_host\*(C'\fR, \f(CW\*(C`no_dirs\*(C'\fR, \f(CW\*(C`cut_dirs\*(C'\fR
and \f(CW\*(C`prefix\*(C'\fR) are ignored.
.Sp
The \f(CW\*(C`filename\*(C'\fR option expects a reference to a subroutine. The subroutine
will receive the HTTP::Message object and must return a string which
is the path of the file to be created (an absolute path is recommended,
but a relative path is accepted).
.Sp
Returning \f(CW""\fR or \f(CW\*(C`undef\*(C'\fR will prevent the creation of the file.
This lets a filter decide even more precisely what to save or not,
even though this should be done in the match subroutine (see
HTTP::Proxy's \f(CW\*(C`push_filter()\*(C'\fR method).
.PP
Other options help the filter decide where and when to save:
.IP "\fBmultiple\fR => \fIboolean\fR" 4
.IX Item "multiple => boolean"
With the \fBmultiple\fR option, saving the same file in the same directory
will result in the original copy of file being preserved and the second
copy being named \fIfile.1\fR. If that a file is saved yet again with the same
name, the third copy will be named \fIfile.2\fR, and so on.
.Sp
Default is \fItrue\fR.
.Sp
If \fBmultiple\fR is set to \fIfalse\fR then a file will be overwritten
by the next one with the same name.
.IP "\fBtimestamp\fR => \fIboolean\fR" 4
.IX Item "timestamp => boolean"
With the \f(CW\*(C`timestamp\*(C'\fR option, the decision as to whether or not to save
a newer copy of a file depends on the local and remote timestamp and
size of the file.
.Sp
The file is saved only if the date given in the \f(CW\*(C`Last\-Modified\*(C'\fR is more
recent than the local file's timestamp.
.Sp
Default is \fIfalse\fR.
.Sp
\&\fBThis option is not implemented.\fR
.IP "\fBkeep_old\fR => \fIboolean\fR" 4
.IX Item "keep_old => boolean"
The \f(CW\*(C`keep_old\*(C'\fR option will prevent the file to be saved if a file
with the same name already exists. Default is \fIfalse\fR.
.Sp
No matter if \fBmultiple\fR is set or not, the file will \fInot\fR be saved
if \fBkeep_old\fR is set to true.
.IP "\fBstatus\fR => \e@codes" 4
.IX Item "status => @codes"
The \f(CW\*(C`status\*(C'\fR option limits the status codes for which a response body
will be saved. The default is \f(CW\*(C`[ 200 ]\*(C'\fR, which prevent saving error
pages (for 404 codes).
.SS "Examples"
.IX Subsection "Examples"
Given a request for the \s-1URI,\s0
the filename is computed as follows, depending on the constructor
options:
.PP
.Vb 1
\& No options \-> search.cpan.org/dist/HTTP\-Proxy/index.html
\&
\& no_host => 1 \-> dist/HTTP\-Proxy/index.html
\&
\& no_dirs => 1 \-> search.cpan.org/index.html
\&
\& no_host => 1,
\& no_dirs => 1,
\& prefix => \*(Aqdata\*(Aq \-> data/index.html
\&
\& cut_dirs => 1 \-> search.cpan.org/HTTP\-Proxy/index.html
\&
\& cut_dirs => 2 \-> search.cpan.org/index.html
.Ve
.SH "METHODS"
.IX Header "METHODS"
This filter implements several methods, which are all called atuomatically:
.IP "\fIinit()\fR" 4
.IX Item "init()"
Handle all the parameters passed to the constructor to define the
filter behaviour.
.IP "\fIbegin()\fR" 4
.IX Item "begin()"
Open the file to which the data will be saved.
.IP "\fIfilter()\fR" 4
.IX Item "filter()"
Save all the data that goes through to the opened file.
.IP "\fIend()\fR" 4
.IX Item "end()"
Close the file when the whole message body has been processed.
.IP "\fIwill_modify()\fR" 4
.IX Item "will_modify()"
This method returns a \fIfalse\fR value, thus indicating to the system
that it will not modify data passing through.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
HTTP::Proxy, HTTP::Proxy::BodyFilter.
.SH "AUTHOR"
.IX Header "AUTHOR"
Philippe \*(L"BooK\*(R" Bruhat, .
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
Thanks to Mat Proud for asking how to store all pages which go through
the proxy to disk, without any processing. The further discussion we
had led to the writing of this class.
.PP
\&\fIWget\fR\|(1) provided the inspiration for many of the file naming options.
.PP
Thanks to Nicolas Chuche for telling me about \f(CW\*(C`O_EXCL\*(C'\fR.
.PP
Thanks to RafaXl Garcia-Suarez and David Rigaudiere for their help on
irc while coding the nasty \f(CW\*(C`begin()\*(C'\fR method. \f(CW\*(C`;\-)\*(C'\fR
.PP
Thanks to Howard Jones for the inspiration and initial patch for the
\&\f(CW\*(C`filename\*(C'\fR option. Lucas Gonze provided a patch to make \f(CW\*(C`status\*(C'\fR
actually work.
.PP
Thanks to Max Maischein for detecting a bug in the parameter validation
for \f(CW\*(C`filename\*(C'\fR ().
.PP
Thanks to Mark Tilford, who found out that the
\&\f(CW\*(C`filename\*(C'\fR option was incorrectly used internally
().
.PP
Thanks to Roland Stigge and Gunnar Wolf for
reporting and forwarding Debian bug #433951 to \s-1CPAN RT
\&\s0(,
).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004\-2013, Philippe Bruhat.
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it or modify it under
the same terms as Perl itself.