.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Debbugs::Log 3pm"
.TH Debbugs::Log 3pm "2010-08-06" "perl v5.10.0" "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"
Debbugs::Log \- an interface to debbugs .log files
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Debbugs::Log module provides a convenient way for scripts to read and
write the .log files used by debbugs to store the complete textual records
of all bug transactions.
.SS "The .log File Format"
.IX Subsection "The .log File Format"
\&.log files consist of a sequence of records, of one of the following four
types. ^A, ^B, etc. represent those control characters.
.IP "incoming-recv" 4
.IX Item "incoming-recv"
.Vb 3
\&  ^G
\&  [mail]
\&  ^C
.Ve
.Sp
\&\f(CW\*(C`[mail]\*(C'\fR must start with /^Received: \e(at \eS+\e) by \eS+;/, and is copied to
the output.
.IP "autocheck" 4
.IX Item "autocheck"
Auto-forwarded messages are recorded like this:
.Sp
.Vb 3
\&  ^A
\&  [mail]
\&  ^C
.Ve
.Sp
\&\f(CW\*(C`[mail]\*(C'\fR must contain /^X\-Debian\-Bugs(\-\ew+)?: This is an autoforward from
\&\eS+/. The first line matching that is removed; all lines in the message body
that begin with 'X' will be copied to the output, minus the 'X'.
.Sp
Nothing in debbugs actually generates this record type any more, but it may
still be in old .logs at some sites.
.IP "recips" 4
.IX Item "recips"
.Vb 5
\&  ^B
\&  [recip]^D[recip]^D[...] OR \-t
\&  ^E
\&  [mail]
\&  ^C
.Ve
.Sp
Each [recip] is output after \*(L"Message sent\*(R"; \f(CW\*(C`\-t\*(C'\fR represents the same
sendmail option, indicating that the recipients are taken from the headers
of the message itself.
.IP "html" 4
.IX Item "html"
.Vb 3
\&  ^F
\&  [html]
\&  ^C
.Ve
.Sp
[html] is copied unescaped to the output. The record immediately following
this one is considered \*(L"boring\*(R" and only shown in certain output modes.
.Sp
(This is a design flaw in the log format, since it makes it difficult to
change the \s-1HTML\s0 presentation later, or to present the data in an entirely
different format.)
.PP
No other types of records are permitted, and the file must end with a ^C
line.
.SS "Perl Record Representation"
.IX Subsection "Perl Record Representation"
Each record is a hash. The \f(CW\*(C`type\*(C'\fR field is \f(CW\*(C`incoming\-recv\*(C'\fR, \f(CW\*(C`autocheck\*(C'\fR,
\&\f(CW\*(C`recips\*(C'\fR, or \f(CW\*(C`html\*(C'\fR as above; \f(CW\*(C`text\*(C'\fR contains text from \f(CW\*(C`[mail]\*(C'\fR or
\&\f(CW\*(C`[html]\*(C'\fR as above; \f(CW\*(C`recips\*(C'\fR is a reference to an array of recipients
(strings), or undef for \f(CW\*(C`\-t\*(C'\fR.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "new" 4
.IX Item "new"
Creates a new log reader based on a .log filehandle.
.Sp
.Vb 3
\&      my $log = Debbugs::Log\->new($logfh);
\&      my $log = Debbugs::Log\->new(bug_num => $nnn);
\&      my $log = Debbugs::Log\->new(logfh => $logfh);
.Ve
.Sp
Parameters
.RS 4
.IP "bug_num \*(-- bug number" 4
.IX Item "bug_num  bug number"
.PD 0
.IP "logfh \*(-- log filehandle" 4
.IX Item "logfh  log filehandle"
.IP "log_name \*(-- name of log" 4
.IX Item "log_name  name of log"
.RE
.RS 4
.PD
.Sp
One of the above options must be passed.
.RE
.IP "read_record" 4
.IX Item "read_record"
Reads and returns a single record from a log reader object. At end of file,
returns undef. Throws exceptions using \fIdie()\fR, so you may want to wrap this
in an \fIeval()\fR.
.IP "read_log_records" 4
.IX Item "read_log_records"
Takes a .log filehandle as input, and returns an array of all records in
that file. Throws exceptions using \fIdie()\fR, so you may want to wrap this in an
\&\fIeval()\fR.
.Sp
Uses exactly the same options as Debbugs::Log::new
.IP "write_log_records" 4
.IX Item "write_log_records"
Takes a filehandle and a list of records as input, and prints the .log
format representation of those records to that filehandle.
.SS "escape_log"
.IX Subsection "escape_log"
.Vb 1
\&     print {$log} escape_log(@log)
.Ve
.PP
Applies the log escape regex to the passed logfile.
.SH "CAVEATS"
.IX Header "CAVEATS"
This module does none of the formatting that bugreport.cgi et al do. It's
simply a means for extracting and rewriting raw records.