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

Download history 181/week @ 2024-07-22 66/week @ 2024-07-29 251/week @ 2024-08-05 254/week @ 2024-08-12 316/week @ 2024-08-19 428/week @ 2024-08-26 15/week @ 2024-09-02 231/week @ 2024-09-09 189/week @ 2024-09-16 67/week @ 2024-09-23

531 downloads per month

Apache-2.0

33KB
759 lines

clock-rs

crates.io License Stars

A modern, digital clock that effortlessly runs in your terminal.

Presentation

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