.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "Mail::SpamAssassin::Util::Progress 3"
.TH Mail::SpamAssassin::Util::Progress 3 2024-09-01 "perl v5.40.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
Mail::SpamAssassin::Util::Progress \- Progress bar support for SpamAssassin
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  my $progress = Mail::SpamAssassin::Util::Progress\->new({total => 100});
\&
\&  $msgcount = 0;
\&  foreach my $message (@messages) {
\&    # do something here
\&    $msgcount++;
\&    $progress\->update($msgcount);
\&  }
\&
\&  $progress\->final();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module implements a progress bar for use in SpamAssassin scripts and
modules.  It allows you to create the progress bar, update it and print
out the final results of a particular run.
.SS new
.IX Subsection "new"
public class (Mail::SpamAssassin::Util::Progress) new (\e% \f(CW$args\fR)
.PP
Description:
Creates a new Mail::SpamAssassin::Util::Progress object, valid values for
the \f(CW$args\fR hashref are:
.IP "total (required)" 4
.IX Item "total (required)"
The total number of messages expected to be processed.  This item is
required.
.IP "fh [optional]" 4
.IX Item "fh [optional]"
An optional filehandle may be passed in, otherwise STDERR will be used by
default.
.IP "term [optional]" 4
.IX Item "term [optional]"
The module will attempt to determine if a valid terminal exists on the
STDIN filehandle.  This item allows you to override that value.
.SS init_bar
.IX Subsection "init_bar"
public instance () \fBinit_bar()\fR
.PP
Description:
This method creates the initial progress bar and is called automatically from new.  In addition
you can call init_bar on an existing object to reset the bar to it's original state.
.SS update
.IX Subsection "update"
public instance () update ([Integer \f(CW$num_done\fR])
.PP
Description:
This method is what gets called to update the progress bar.  You may optionally pass in
an integer value that indicates how many messages have been processed.  If you do not pass
anything in then the num_done value will be incremented by one.
.SS final
.IX Subsection "final"
public instance () final ([Integer \f(CW$num_done\fR])
.PP
Description:
This method should be called once all processing has finished.
It will print out the final msgs per sec calculation and the total time taken.
You can optionally pass in a num_done value, otherwise it will use the value
calculated from the last call to update.