path: root/timer.1

.TH TIMER 1 "ttym 2.0"
.SH NAME
timer \- terminal countdown and stopwatch
.SH SYNOPSIS
.B timer
.RB [ \-qs ]
.RB [ \-c
.IR text ]
.RB [ \-\-no\-persist ]
.RB [ \-\-flash
.BR on | off ]
.RB [ \-\-bar
.IR style ]
.RB [ \-\- ]
.RI [ duration ]
.RI [ message
.IR ... ]
.PP
.B timer \-r
.RB [ \-n
.IR N ]
.RB [ \-\-raw ]
.PP
.B timer \-\-stats
.RB [ today | week | month | all ]
.SH DESCRIPTION
.B timer
is a small terminal countdown timer and stopwatch inspired by suckless philosophy.
A single argument is parsed as a duration and the program counts down.
With no duration argument it runs as a stopwatch.
The progress bar, current elapsed time and time remaining
are redrawn on the same line ten times per second.
.PP
The binary is intentionally small and modular.
Beyond the base build (countdown, stopwatch, ASCII progress bar,
pause/resume, one\-shot terminal bell on completion) every feature is
an optional patch under
.IR patches/ .
Each section below describing a non\-base feature is annotated with
.RI [patch: name ];
those options and behaviours are only present if the corresponding
patch has been applied at build time.
.B timer \-h
always reflects the actual build.
.SH OPTIONS
.SS Base
.TP
.B \-q
Suppress the one\-shot completion bell.
Persistent alert loops, if enabled by a patch, still ring the bell.
.TP
.B \-s
Silent. No bell, no notification, no alert loop.
Equivalent to combining every silencing flag.
.TP
.B \-h
Print usage and exit. Reflects the actual build.
.TP
.B \-\-
End of options. Subsequent arguments are treated as positional even if
they begin with
.BR \- .
.SS Optional, added by patches
.TP
.BR \-c \ \fItext\fR
.RI [patch: logging,
.RI hooks]
Comment associated with this session. With the
.B logging
patch, it is written as the third TSV field and any
.BI + tag
tokens within it are picked up by
.BR "timer \-\-stats" .
With the
.B hooks
patch, it is passed as the fourth argument to each hook script.
.TP
.B \-\-no\-persist
.RI [patch: persist\-alert]
Skip the alert\-until\-keypress loop.
.B timer
emits one bell and one notification, then exits.
.TP
.BR \-\-flash \ \fBon\fR | \fBoff\fR
.RI [patch: flash]
Toggle the reverse\-video terminal flash that runs during the
persistent alert loop. Accepts
.BR on / off / true / false / 1 / 0 / yes / no .
Default is build\-dependent.
.TP
.BR \-\-bar \ \fIstyle\fR
.RI [patch: bar\-styles]
Progress bar style. One of
.BR unicode ,
.BR ascii ,
.BR hash ,
.BR dots ,
.BR line ,
.BR block ,
.BR arrow ,
.BR minimal .
With no patch applied the bar uses the compile\-time
.B BAR_FILL
and
.B BAR_EMPTY
glyphs from
.IR config.h .
.SH SUBCOMMANDS
.SS timer \-r [\-n N] [\-\-raw]
.RI [patch: logging]
Read the session log.
.B \-n N
limits output to the last
.I N
entries.
.B \-\-raw
prints the underlying TSV instead of the formatted table, suitable for
piping through
.BR awk (1),
.BR grep (1)
or
.BR sort (1).
.SS timer \-\-stats [\fIperiod\fR]
.RI [patch: logging]
Print aggregate statistics. Period is one of
.BR today
(default),
.BR week ,
.BR month ,
.BR all .
Entries are summed in total and broken down by
.BI + tag
tokens extracted from comments. Untagged sessions are reported as
.BR (untagged) .
.SH DURATION FORMAT
A duration is either a colon notation or a unit notation. Examples:
.PP
.RS
.nf
25m         twenty\-five minutes
90s         ninety seconds
2h          two hours
1h30m       one and a half hours
01:30:00    one and a half hours
25:00       twenty\-five minutes
.fi
.RE
.PP
Colon notation expects
.IR H:M:S
or
.IR M:S .
Unit notation is a concatenation of one or more
.IR Nh ,
.IR Nm ,
.IR Ns
groups in any order.
.SH MESSAGE
.RI [patch: notify]
Any positional arguments after
.I duration
are joined into the message used for the one\-shot completion
notification. The message is expanded into the
.B notify_cmd
template via the
.B {msg}
placeholder.
.SH KEYS
While the timer is running:
.TP
.B space
Pause or resume the countdown or stopwatch.
.TP
.B q
Quit immediately. Logs the partial session if logging is enabled.
.TP
.B Ctrl+C
Same as
.BR q .
.SH ALERT LOOP
.RI [patch: persist\-alert]
When a countdown reaches zero, instead of emitting one bell and
exiting, the program rings the bell every \(ti1.5 s and polls for a
keypress. Any key acknowledges and exits.
.PP
The loop runs only when
.B timer
is in the foreground.
Background jobs
.RB ( timer
.IR ... \ &)
get one bell and exit normally, leaving the shell quiet.
.PP
If the
.B flash
patch is also applied, each beat of the loop briefly inverts the
terminal colours (reverse\-video). The flash can be suppressed without
disabling the loop via
.BR "\-\-flash off" .
.SH HOOKS
.RI [patch: hooks]
On state transitions
.B timer
invokes optional executables under
.IR ~/.config/ttym/hooks/ :
.TP
.B on_start
Called when a session begins.
.TP
.B on_done
Called when a countdown completes normally.
.TP
.B on_quit
Called when a session is interrupted with
.BR q
or
.BR Ctrl+C ,
or when a stopwatch is stopped.
.PP
Each hook is executed synchronously with three arguments:
.IR mode ,
.IR duration_seconds ,
.IR comment .
The first is
.BR countdown
or
.BR stopwatch ;
the others come from the running session. Hooks must be marked
executable. Standard streams are redirected to
.IR /dev/null .
.SH FILES
.TP
.I ~/.config/ttym/config
.RI [patch: config\-file]
Runtime configuration. Auto\-generated on first run with all keys
commented out.
.TP
.I ~/.config/ttym/ttym.log
.RI [patch: logging]
Session log. TSV with three fields per line:
.RS
.PP
.RS
.nf
YYYY\-MM\-DD HH:MM:SS<TAB>SECONDS<TAB>COMMENT
.fi
.RE
.PP
Designed to be processed with
.BR awk (1)
and
.BR grep (1)
rather than re\-rendered by the binary.
.RE
.TP
.I ~/.config/ttym/hooks/
.RI [patch: hooks]
Directory containing the
.BR on_start ,
.BR on_done ,
.B on_quit
executables described in
.BR HOOKS .
.SH EXAMPLES
A twenty\-five minute work session, tagged for later stats:
.PP
.RS
.nf
timer \-c "+work coding" 25m
.fi
.RE
.PP
A countdown that pops a notification with custom text:
.PP
.RS
.nf
timer 10m Lunch
.fi
.RE
.PP
Total hours logged this week:
.PP
.RS
.nf
timer \-r \-\-raw | awk \-F'\\t' '{s+=$2} END {printf "%dh\\n", s/3600}'
.fi
.RE
.PP
Count
.BR +work
sessions ever:
.PP
.RS
.nf
timer \-r \-\-raw | grep '+work' | wc \-l
.fi
.RE
.PP
Stopwatch with no notifications:
.PP
.RS
.nf
timer \-s
.fi
.RE
.SH DESIGN
The binary does one thing: time intervals and, optionally, log them.
Reports
.RB ( "timer \-r" ,
.BR "timer \-\-stats" )
are read\-only views over the same TSV log. For any other view, pipe
.B "timer \-r \-\-raw"
through
.BR awk (1),
.BR grep (1)
or
.BR sort (1).
No daemon, no IPC, no plugin system, no embedded TUI. Hooks are
git\-style: executables you write yourself.
.PP
Compile\-time options live in
.IR config.h ;
runtime overrides (when the
.B config\-file
patch is applied) live in
.IR ~/.config/ttym/config .
.SH AUTHORS
.B timer
is maintained by \(/Lukasz Kasprzak.
Distributed under the MIT license; see
.B LICENSE
in the source tree.
.SH SEE ALSO
.BR awk (1),
.BR grep (1),
.BR notify\-send (1),
.BR paplay (1),
.BR patch (1)