clock-rs

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

Table of Contents

• Introduction
• Installation
• Usage
• Configuration
  • Fields
  • Example
• Contributing
• License

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.

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.

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.