API reference

clock()
clock(t::Dates.Time) -> String
clock(dt::Dates.DateTime) -> String

Display the current local wall-clock time as HH:MM:SS until Ctrl+C. The live display refreshes approximately every 0.5 seconds.

The live display redraws in place from the top-left corner on every refresh (each row is overwritten and leftover text is erased), so run it in a pane of its own. If the terminal is too small for the dial, it switches to the next candidate (down to plain text) automatically. The last frame stays on screen after exit.

Passing a Time or DateTime instead returns one dial frame without printing or sleeping; the date and subsecond fields are ignored.

Examples

julia> using Dates

julia> clock(Time(12, 34, 56)) == clock(DateTime(2026, 1, 1, 12, 34, 56))
true

stopwatch(refresh_interval::AbstractFloat=0.01)
stopwatch(t::Dates.Time) -> String

Display elapsed time as MM:SS:mmm until Ctrl+C. The interval is in seconds and must be finite and positive. Elapsed time uses a monotonic clock, and rendering time is deducted from the wait before the next refresh.

Passing a Time returns a single frame without printing or waiting. Only its minute, second, and millisecond fields are shown: the visible minute counter wraps after 59. Millisecond digits indicate resolution, not a guarantee that the screen updates every millisecond. See Timer accuracy.

Examples

julia> using Dates

julia> stopwatch(Time(1, 2, 3, 456)) == stopwatch(Time(0, 2, 3, 456))
true

countdown(; hour=nothing, minute=nothing, second=nothing)
countdown(t::Dates.Time)

Run a countdown displaying HH:MM:SS, then return nothing after printing zero. With no arguments, count down three minutes. If any keyword is supplied, omitted components are zero. Components follow Dates.Time ranges: hours 0–23, minutes 0–59, and seconds 0–59.

A Time is interpreted as a duration since midnight, including its subsecond part. Remaining seconds are rounded up. A monotonic clock prevents rendering and scheduler delays from accumulating; a slow terminal can delay an update. There is no extra sleep after zero. Press Ctrl+C to stop early.

The live display redraws in place from the top-left corner on every refresh (each row is overwritten and leftover text is erased), so run it in a pane of its own. If the terminal is too small for the dial, it switches to the next candidate (down to plain text) automatically. The last frame stays on screen after exit.

Examples

These calls block while the timer runs:

countdown(minute=10)
countdown(hour=1, minute=30)
countdown(Dates.Time(0, 0, 0, 500)) # half a second

TerminalClock.set_dials(tomlfile::AbstractString)

Save the path to a TOML dial file in the active environment's preferences. Use an absolute path and restart Julia to load the new dials. The file must contain a complete [Large] table; [Small] is optional.

The file is loaded on the next import, so an invalid path or TOML file can prevent using TerminalClock. This also removes any saved list of candidate dials: the most recent set_dials call wins. See Custom dials.

TerminalClock.set_dials(tomlfiles::AbstractVector{<:AbstractString})

Save several TOML dial files as candidates, in order. From the first, the first dial that fits the terminal is used. The bundled Keycap.toml and Text.toml dials follow the registered ones. Use absolute paths and restart Julia to load the new dials. This also removes any saved single dial file: the most recent set_dials call wins.

TerminalClock.clear_dials()

Clear the saved dial preferences (tomlfile and tomlfiles). Restart Julia to load the bundled ASCII dials. This changes preferences for the active environment, not the current display.