14 releases
0.1.210 | Sep 22, 2024 |
---|---|
0.1.209 | Sep 14, 2024 |
0.1.207 | Aug 30, 2024 |
0.1.1 | Jul 27, 2024 |
#31 in Date and time
531 downloads per month
33KB
759 lines
clock-rs
A modern, digital clock that effortlessly runs in your terminal.
Table of Contents
Introduction
clock-rs
is a terminal-based clock written in Rust, designed to be a new alternative to tty-clock. It offers several improvements, which include:
- The use of a single configuration file to manage its settings, with the ability to overwrite them through the command line,
- Many additional features such as a timer and a stopwatch,
- And greater flexibility as well as better user experience!
Installation
To install clock-rs
globally using Cargo, simply run $ cargo install clock-rs
.
You can then run the executable via the clock-rs
command.
Usage
Usage: clock-rs [OPTIONS] [COMMAND]
Commands:
clock Display the current time (default)
timer Create a timer
stopwatch Start a stopwatch
help Print this message or the help of the given subcommand(s)
Options:
-c, --color <COLOR> Specify the clock color
-x, --x-pos <X_POS> Set the position along the horizontal axis
-y, --y-pos <Y_POS> Set the position along the vertical axis
--fmt <FMT> Set the date format
-t Use the 12h format
-i, --interval <INTERVAL> Set the polling interval in milliseconds
--utc Use UTC time
-s, --hide-seconds Do not show seconds
-B, --blink Set the colon to blink
-b, --bold Use bold text
-h, --help Print help
-V, --version Print version
Usage: clock-rs timer [OPTIONS] <SECS>
Arguments:
<SECS> Specify the timer duration in seconds
Options:
-k, --kill Terminate the application when the timer finishes
-h, --help Print help
To exit the application, press either Escape
, q
, or Ctrl-C
.
[!NOTE] If no command is specified, the
clock
command is used by default.
Therefore, running$ clock-rs clock
or simply$ clock-rs
will both display the current time.
Configuration
clock-rs
uses the TOML file format for its settings.
By default, the configuration file is named conf.toml
and is stored in the OS configuration directory, within the clock-rs
subdirectory.
Platform | Configuration file path |
---|---|
Linux | ~/.config/clock-rs/conf.toml |
MacOS | ~/Library/Application Support/clock-rs/conf.toml |
Windows | C:\Users\%USERNAME%\AppData\Local\clock-rs\conf.toml |
You can change this path by setting the CONF_PATH
environment variable.
If you wish to run the application without automatically using the existing conf.toml
file, you can set CONF_PATH
to None
.
Any argument passed in the command line will overwrite the settings inside the conf.toml
file.
Fields
Here's a list of the available fields inside the conf.toml
file.
Field | Description | Possible values | Default |
---|---|---|---|
general.color |
Specify the color of the clock | "black" , "red" , "green" , "yellow" , "blue" , "magenta" , "cyan" , or "white" . Optionally, prefix them with bright- . |
"white" |
general.interval |
Set the polling interval in milliseconds | An unsigned integer, e.g. 250 . |
200 |
general.blink |
Set the colon to blink | true or false . |
false |
general.bold |
Use bold text | true or false . |
false |
position.horizontal |
Set the position along the horizontal axis | "start" , "center" , or "end" . |
"center" |
position.vertical |
Set the position along the vertical axis | "start" , "center" , or "end" . |
"center" |
date.fmt |
Specify the date format | A string, e.g. %A, %B %d, %Y . |
"%d-%m-%Y" |
date.use_12h |
Use the 12h format | true or false . |
false |
date.utc |
Use UTC time | true or false . |
false |
date.hide_seconds |
Do not show seconds | true or false . |
false |
Example
The conf.toml
file could look like this:
[general]
color = "magenta"
interval = 250
blink = true
bold = true
[position]
horizontal = "start"
vertical = "end"
[date]
fmt = "%A, %B %d, %Y"
use_12h = true
utc = true
hide_seconds = true
The default configuration can be found here.
Contributing
Feel free to report bugs, suggest features or contribute code.
Any help is appreciated!
License
Copyright © 2024 Oughie
This repository is licensed under the Apache License 2.0 - See here for more information.
Dependencies
~5–14MB
~190K SLoC