.\" As its sole author, I explicitly place this file in the public domain.
.\" It may be used by anyone in any way for any purpose, though I would
.\" appreciate credit where it's due.
.\"		der Mouse, mouse@rodents-montreal.org, 2023-05-03
.Dd May 3, 2023
.Dt PREDICT 1
.Os NetBSD 1.4T
.Sh NAME
.Nm predict
.Nd predict when a long-running thing will finish
.Sh SYNOPSIS
.Nm
.Op Fl each Ar CMD
.Op Fl one Ar STRING Ar CMD
.Op Fl shell Ar SHELL
.Op Fl grep Ar PATTERN
.Op Fl fgrep Ar STRING
.Op Fl field Ar N
.Op Fl time Ar SECONDS
.Op Fl sync
.Op Fl target Ar VALUE
.Op Fl scroll
.Op Fl over
.Sh DESCRIPTION
.Nm
is designed to predict when a long-running thing will finish, given
some way to get a
.Sq progress so far
figure and a target for that value to reach.  Examples might include
copying the contents of a disk drive to another drive or
.Xr bzip2 1 Ap ing
a large file.  The progress-so-far values may come directly from the
long-running process (if it's designed for it) or be obtained with
other tools, such as
.Xr fstat 1 Ap s
.Fl o
option.
.Pp
At a minimum, two flags must be given:
.Fl target ,
to specify the target value, the value which represents
.Sq done
when the progress sample reaches it, and either
.Fl each
or
.Fl one
to specify how to get samples.  There are numerous other flags,
controlling various aspects of operation, but they all have defaults.
(Progress sample may increase or decrease; normally, if they increase
then the target value will be larger than the samples and if they
decrease then the target value will be smaller than the samples.  If
this is not true then
.Nm
may print estimated completion times in the past or, if the current
sample exactly equals the first sample, produce no estimate at all.)
.Pp
Flags understood:
.Bl -tag -width indent
.It Fl each Ar CMD
This specifies one of the possible ways to get a new progress sample
value.  When this is given,
.Nm
forks an instance of
.Ar CMD
each time it wants a sample and expects the child process to produce
the sample value on its standard output (but see also
.Fl grep ,
.Fl fgrep ,
and
.Fl field ) .
With most shells (see the
.Fl shell
option), using
.Fl each
is roughly equivalent to using
.Fl one
with the command as the first argument and the shell as the second, but
using
.Fl each
better handles some error cases, such as a command which does not
always produce a sample value.
.It Fl one Ar STRING Ar CMD
This specifies one of the possible ways to get a new preogress sample
value.  When this is given,
.Nm
forks an instance of
.Ar CMD
at startup, with its standard input and output connected to
.Nm
through pipes.  When
.Nm
wants a new sample value, it writes
.Ar STRING
(followed by a newline) to the pipe to
.Ar CMD Ap s
standard input; it then expects it to produce a sample value on its
standard output (but see also
.Fl grep ,
.Fl fgrep ,
and
.Fl field ) .
It is a fatal error for
.Ar CMD
to exit.
.It Fl shell Ar SHELL
Normally,
.Nm
uses
.Pa /bin/sh
as the shell for the
.Ar CMD
argument to
.Fl each
or
.Fl one .
This specifies an alternative shell.
.Pf ( Nm predict
always uses the
.Fl c
convention to pass
.Ar CMD
to the shell.)
.It Fl grep Ar PATTERN
Specifies an extended regular expression
.Ar PATTERN
which output lines from the
.Ar CMD
subprocess are matched against.  Non-matching lines are silently
discarded.  By default, no lines are discarded.
.It Fl fgrep Ar STRING
Just like
.Fl grep
except that the argument, instead of being a regular expression, is a
fixed string.
.It Fl field Ar N
Without this, the entire line of output from
.Ar CMD
is taken as the sample value.  With this, the
.Ar N Ns No th
whitespace-delimited field is used as the sample value.
.It Fl time Ar SECONDS
By default,
.Nm
requests a sample every sixty seconds.  This changes that, with
.Ar SECONDS
being the inter-sample interval in seconds.  (The argument must be a
strictly positive integer;
.Nm
is not designed for use cases that want samples more often than once a
second.)
.It Fl sync
Normally, samples are taken on a periodic schedule, every 60 seconds or
the
.Fl time
value, starting with one sample immediately after startup.  With
.Fl sync ,
instead, samples are taken when the time is a multiple of the
inter-sample interval.  For example,
.Fl time Ar 60
takes samples once a minute, synchronized with startup;
.Fl time Ar 60 Fl sync
takes samples once a minute on the minute.  (Even with
.Fl sync ,
one sample is always taken at startup.)
.It Fl target Ar VALUE
Specifies the target
.Ar VALUE ,
the value which the sample values are considered to be trending
towards.  This must be specified.
.It Fl scroll
.Nm
can either print each new estimate on a new line or it can keep an
updated estimate on a single line, overwriting it as new estimates are
computed.  This specifies the scrolling behaviour, which is the
default; the flag exists to override a potential earlier
.Fl over .
.It Fl over
As described under
.Fl scroll ,
above,
.Nm
can either scroll estimates or display each one by overwriting the
last.  This specifies the one-line overwriting behaviour, which is not
the default.
.El
.Pp
When using
.Fl each ,
if a run produces no sample value, that iteration is skipped.  When
using
.Fl one ,
.Nm
will wait indefinitely for
.Ar CMD
to produce sample when requested.  If it doesn't produce any (whether
due to bugs or because of incorrect use of
.Fl grep
or
.Fl field ) ,
.Nm
will stop producing estimates entirely.
.Pp
When idle,
.Nm
displays some information: the timestamp of the last sample (this is
omitted if no samples have been retrieved yet), the inter-sample
interval in seconds, the word
.Sq sync
if
.Fl sync
mode is in effect, and the word
.Sq scroll
or
.Sq over
according as
.Fl scroll
or
.Fl over
mode is in effect.  There is a command line; typing commands causes the
idle information to be erased for as long as the command line has
anything on it.  The commands supported are:
.Bl -tag -width indent
.It \&? (also help)
Prints brief help on the available commands.
.It q (also quit)
Quits
.Nm predict .
.It over
If in
.Fl scroll
mode, switches to
.Fl over
mode; if already in
.Fl over
mode, does nothing.
.It scroll
If in
.Fl scroll
mode, switches to
.Fl over
mode; if already in
.Fl over
mode, does nothing.
.It sync
Takes an argument, which must be
.Sq on
or
.Sq off ;
turns
.Fl sync
mode on or off accordingly.
.It time
Takes an argument, which must be an integer number of seconds; this
replaces the inter-sample interval.  When not in
.Fl sync
mode, future samples are taken synchronized with the time the command
is issued.
.It sample
Immediately provokes taking a data sample and computing an estimate.
The estimate is treated as usual (scrolling or overwriting).  This does
not disrupt the regular sample schedule.
.It scroll
If in
.Fl over
mode, switches to
.Fl scroll
mode; if already in
.Fl scroll
mode, does nothing.
.It target
Takes an argument, which replaces the target value specified with
.Fl target
at startup.
.It reset
Resets history, running as if the most recent sample were the first
sample of a new run.  This is appropriate when you know (or suspect)
that something environmental has changed which affects the operation's
speed.  (If you see the estimates drifting approximately linearly, it
is reasonably likely this is what's happened.)
.El
.Sh BUGS
There is no way to select part of a line other than a
whitespace-delimited field.  This could and perhaps should be done as a
reference to a subexpression in a
.Fl grep
pattern.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents-montreal.org .