Crate elmo_lib

Introduction

This library provides functionality for emitting, scheduling and listing notifications. It utilizes an SQLite database for storing regular events (notify at a given datetime) and recurring events (notify at a given pattern). Basically, it is a combination of services that communicate with the notification daemon of a UNIX system, play sounds via the sound output device of the system, and insert/fetch events from the database.

Public functions

Five public functions are available:

• set_event (Either insert a new entry in the database or emit a notification directly)
• emit_event (Sleep for a given duration in a separate thread or emit a notification directly)
• check_events (Check for entries within the database that should be emitted)
• list_events (List entries from the database)
• delete_event (Delete a recurring or regular event by ID)

set_event requires an SQlitepool from the sqlx library and needs to be called from an async function, while emit_event is the synchronous variation it doesn’t require a database connection. An event stored into the database by set_event can only be triggered by calling check_events.

The check_events function is designed to be used in combination with a cronjob or with a daemon, as it simply checks if an entry within the database matches the current datetime (or in case of recurring events, if we missed it within a range of 30 minutes).

The list_events function is utilized to pretty-print events to the terminal, with a fixed format, so its use case is quite specialized at the moment. In order to create a notification, you have to first establish a connection to an SQLite database pool and fill out an EventTemplate.

Example with a database

Here we create an in-memory SQLite database with the events table and insert a single event, this is not a very practical example as events stored in an in-memory database are lost when the main function exits, but it shows how the function should be used.

The function check_events can be used to display notifications, that are stored in a database.

use eyre::Result;
use elmo_lib::{set_event, EventTemplate};
use sqlx::sqlite::SqlitePool;

#[tokio::main]
async fn main() -> Result<()> {
    let pool = SqlitePool::connect("file::memory:").await?;
    sqlx::query(
        "CREATE TABLE IF NOT EXISTS events(
            id INTEGER PRIMARY KEY NOT NULL,
            name TEXT NOT NULL,
            description TEXT NULL,
            event_date TEXT NOT NULL,
            icon TEXT NULL,
            sound_file_path TEXT NULL
            )
        "
        ).execute(&pool).await?;

    let new_event = EventTemplate {
        name: String::from("Test notification"),
        desc: String::from("description of an event in the future"),
        date_str: Some(String::from("2099-10-10T18:00")),
        wait_expr: None,
        cron_str: None,
        icon_name: Some(String::from("future_icon")),
        sound_path: None,
        announce: true,
        test_sound: false,
    };
    set_event(new_event, &pool).await?;
    Ok(())
}

Within the repository of this project you can locate the migrations/1_events.sql file, which contains the SQL statements for the two tables used by the project.

To create a new SQLite database and create the required tables issue the following command:

sqlite3 /tmp/events.db < /path/to/elmo/migrations/1_events.sql

Example without a database

This example doesn’t utilize a database but instead creates a separate thread that sleeps for the specified amount of time.

use elmo_lib::{emit_event, EventTemplate};

fn main() {
    let new_event = EventTemplate {
        name: String::from("Test notification"),
        desc: String::from("description of a notification in 5 minutes"),
        date_str: None,
        wait_expr: Some(String::from("5 seconds")),
        cron_str: None,
        icon_name: Some(String::from("dog_icon")),
        sound_path: None,
        announce: true,
        test_sound: false,
    };
    emit_event(new_event);
}

Additional hints

To use custom icons you have to place the new images into a folder that is known to the notification daemon. Please refer to the documnetation of the software you use on your system to find out how to declare custom locations, for example in dunst you simply have to add the folder to the icon_path variable in the configuration (dunstrc).

Structs

EventTemplate

Structure describing a notification

Functions

check_events

Search for upcoming or just missed events within all database tables.

delete_event

Delete a recurring or regular event by ID.

emit_event

list_events

List upcoming events or recurring events within the CLI with colorful output.

prepare_environment

set_event

Create a delayed, recurring or direct notification.

Type Definitions

SqlitePool

An alias for [Pool][crate::pool::Pool], specialized for SQLite.