.\" $Id: datecalc.man,v 1.11 2012/07/06 20:00:35 ksb Exp $
.\" by Kevin Braunsdorf and Mike MacKenzie
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f ${DESTDIR}/usr/local/man/man1/datecalc.1
.\" $Deinstall: ${rm-rm} -f ${DESTDIR}/usr/local/man/[cm]a[nt]1/datecalc.1*
.TH DATECALC 1 LOCAL
.SH NAME
datecalc - compute with times
.SH SYNOPSIS
.ds PN "datecalc
\fI\*(PN\fP [\fB\-v\fP] [\fB\-o\fP\~\fIformat\fP] \fB\-a\fP \fIdate\fP \fItime\fP
.br
\fI\*(PN\fP [\fB\-v\fP] \fB\-c\fP \fIdate\fP \fIdate\fP
.br
\fI\*(PN\fP [\fB\-v\fP] \fB\-c\fP \fItime\fP \fItime\fP
.br
\fI\*(PN\fP [\fB\-v\fP] \fB\-d\fP \fItime\fP \fIscalar\fP
.br
\fI\*(PN\fP [\fB\-v\fP] [\fB\-o\fP\~\fIformat\fP] \fB\-e\fP \fIscalar\fP
.br
\fI\*(PN\fP [\fB\-v\fP] [\fB\-o\fP\~\fIformat\fP] \fB\-f\fP \fIdate\fP
.br
\fI\*(PN\fP [\fB\-v\fP] \fB\-m\fP \fItime\fP \fIscalar\fP
.br
\fI\*(PN\fP [\fB\-v\fP] \fB\-n\fP \fItime\fP
.br
\fI\*(PN\fP [\fB\-v\fP] [\fB\-o\fP\~\fIformat\fP] \fB\-p\fP \fIdate\fP
.br
\fI\*(PN\fP [\fB\-v\fP] [\fB\-o\fP\~\fIformat\fP] \fB\-s\fP \fIdate\fP \fItime\fP
.br
\fI\*(PN\fP [\fB\-v\fP] \fB\-t\fP \fIdate\fP
.br
\fI\*(PN\fP [\fB\-v\fP] \fB\-y\fP \fItime\fP
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
\fIDatecalc\fP outputs a value computed from the command line expression.
There are three different specifications allowed in an expresssion:
.TP
\fIdate\fP
A \fIdate\fP is either the output of the \fBdate\fP(1) command, or one
of the words \fBnow\fP, \fBtoday\fP, \fByesterday\fP, or \fBtomorrow\fP.  Some
other representaions of a date are parsed: all of them must be
contained in a single shell word.  For example ctime(3) output is
a valid \fIdate\fP.
.TP
\fItimes\fP
A \fItimeu\fP is an  integer number followed by a unit.  Units
are \fBhours\fP, \fBminutes\fP, \fBdays\fP, \fBweeks\fP,
\fBfortnights\fP, \fByears\fP, or \fBleapyears\fP
and may be abreviated to thier first letter.
A \fItime\fP can be followed by another \fItime\fP, as a shell word;
the result is the sum of the times (e.g. "2y1w" is 2 years 1 week).
.TP
\fIscaler\fP
A \fIscaler\fP is an integer with no \fItime\fP unit on the end.
.P
In addition to these types the output may simply be an exit code
(0 for success, 1 for failure).

.SH OPTIONS
.TP
\fB\-a\fP
Add a \fItime\fP to a \fIdate\fP [to get a \fIdate\fP].
.TP
\fB\-c\fP
Compare two \fIdates\fP or \fItimes\fP [to get an exit code].
.TP
\fB\-d\fP
Divide a \fItime\fP by a \fIscalar\fP [to get a \fItime\fP].
.TP
\fB\-e\fP
Convert seconds since the epoch to a \fIdate\fP.
.TP
\fB\-f\fP
Convert a free format \fIdate\fP to fixed format \fIdate\fP.
.TP
\fB\-h\fP
Print a brief help message.
.TP
\fB\-m\fP
Multiply a \fItime\fP by a \fIscalar\fP [to get a \fItime\fP].
.TP
\fB\-n\fP
Convert a \fItime\fP to scalar seconds.
.TP
\fB\-o\fP \fIformat\fP
Specify the output format for any computed \fIdate\fP (as per \fBstrftime\fP(3)).
.TP
\fB\-p\fP
Convert a \fIdate\fP to scalar seconds since the epoch.
.TP
\fB\-s\fP
Subtract a \fItime\fP from a \fIdate\fP [to get a \fIdate\fP].
.TP
\fB\-t\fP
Convert a free format date to \fBat\fP(1) format.
.TP
\fB\-v\fP
Be verbose by announcing what operatoin we are about to do.
.TP
\fB\-y\fP
Convert a \fItime\fP to years days hours minutes seconds [to get a \fItime\fP with units as English words].

.SH EXAMPLES
.TP
\fI\*(PN\fP \-o %Y \-a 1d "`date`"
Output tomorrow's year.
.TP
\fI\*(PN\fP \-o %Y tomorrow
Output tomorrow's year, a little faster.
.TP
\fI\*(PN\fP yesterday
Output what \fBdate\fP(1) might have output yesterday.
.TP
\fI\*(PN\fP "15 Feb 2009"
Output the given \fIdate\fP in the standard format.
.TP
\fI\*(PN\fP \-y "2y1l2f6h"
Output "3 Years 29 Days 6 Hours", which is more legible, and more
accurate than "3 years 1 month".  \" yeah, kinda -- ksb

.SH BUGS
Poorly documented (to say the least).  Infix or prefix command line
options would be far more useful.
.P
It usually takes more than one
\fI\*(PN\fP command to get what you want.

.SH AUTHOR
Mike MacKenzie and KS Braunsdorf
.br
NPC Guild, rpm at ksb.npcguild.org.nospam

.SH "SEE ALSO"
.hlm 0
sh(1), strftime(3), at(1), date(1), ctime(3)