clockwords

Find and resolve natural-language time expressions in text.

clockwords scans free-form text for relative time expressions like "last Friday from 9 to eleven", "yesterday at 3pm", or "letzten Freitag von 9 bis 12 Uhr" and returns their byte-offset spans together with resolved DateTime<Utc> values. It supports English, German, French, and Spanish out of the box.

Built for real-time GUI applications (time-tracking, note-taking, calendars) where the user types naturally and the app highlights detected time references as they appear. Timezone-aware — times the user enters are interpreted in their local timezone (configurable, defaults to UTC).

Features

• Four languages: English, German, French, Spanish
• Timezone-aware: User input is interpreted in a configurable timezone (defaults to UTC for backward compatibility)
• Byte-offset spans: Directly usable for text highlighting in any GUI framework
• Resolved times: Every match resolves to a concrete DateTime<Utc> point or range
• Incremental typing support: Detects partial matches (e.g. "yester" while the user is still typing "yesterday")
• Accent-tolerant: Handles días/dias, à/a, mañana/manana, dernière/derniere
• Fast rejection: Aho-Corasick keyword prefilter skips text with no time-related words in sub-microsecond time
• Zero allocations on rejection: If no keywords are found, scan() returns immediately
• No unsafe code
• Defensive: All internal date arithmetic returns Option — no panics from edge-case dates

Quick Start

Add to your Cargo.toml:

[dependencies]
clockwords = "0.3"

Basic Usage

use clockwords::{default_scanner, ResolvedTime};
use chrono::Utc;

fn main() {
    // Create a scanner with all four languages enabled
    let scanner = default_scanner();
    let now = Utc::now();

    let text = "The last hour I coded the initial code for the time library";
    let matches = scanner.scan(text, now);

    for m in &matches {
        println!(
            "Found '{}' at bytes {}..{} ({:?})",
            &text[m.span.as_range()],
            m.span.start,
            m.span.end,
            m.kind,
        );

        match &m.resolved {
            ResolvedTime::Point(dt) => println!("  Resolved to: {dt}"),
            ResolvedTime::Range { start, end } => {
                println!("  Resolved to: {start} .. {end}")
            }
        }
    }
}

Output:

Found 'The last hour' at bytes 0..13 (TimeRange)
  Resolved to: 2026-02-08T12:30:00Z .. 2026-02-08T13:30:00Z

Select Specific Languages

use clockwords::scanner_for_languages;

// Only English and German
let scanner = scanner_for_languages(&["en", "de"]);

Timezone Support

By default, all times are interpreted in UTC. To interpret user input in a specific timezone, configure ParserConfig::timezone or use scan_with_tz():

use clockwords::{ParserConfig, TimeExpressionScanner, Tz, default_scanner};
use chrono::Utc;

// Option 1: Set timezone in config
let config = ParserConfig {
    timezone: Tz::Europe__Berlin,
    ..Default::default()
};
// Pass config when constructing the scanner (e.g. via TimeExpressionScanner::new)

// Option 2: Override per scan call
let scanner = default_scanner();
let matches = scanner.scan_with_tz("yesterday at 3pm", Utc::now(), Tz::Europe__Berlin);
// "3pm" is interpreted as 15:00 Berlin time → resolves to 14:00 UTC (in winter)

When a timezone is set, all day boundaries (midnight), time-of-day values, and weekday calculations use the user's local timezone. The resolved output always remains in UTC. For example, with Europe/Berlin (CET, UTC+1 in winter):

• "today" at 23:30 UTC (= 00:30 CET next day) → the range covers the next calendar day in Berlin
• "at 3pm" → resolves to 14:00 UTC (not 15:00 UTC)
• "the last hour" → unchanged (duration-based, timezone-independent)

Supported Expressions

Relative Days

Resolves to a full-day Range (midnight to midnight in the configured timezone).

Relative Weekdays

Resolves to a full-day Range (midnight to midnight in the configured timezone). French and Spanish support both pre- and post-positive word order (e.g. lundi prochain and prochain lundi). Spanish also supports el viernes que viene.

Day Offsets

Supports both digits and written-out number words (1–30).

Time Specifications

Colon-delimited minutes (H:MM) are supported in all languages. In English, am/pm is optional — bare H:MM with at is treated as 24-hour time. French supports both h and : as separators (13h30 and 13:30).

Resolves to a Point in time.

Time Ranges

English supports both between X and Y and from X to Y with number words (from nine to five).

Combined Expressions

Any day reference (relative day, weekday, or day offset) can be combined with a time specification or time range in a single expression. The entire phrase is detected as one match:

Relative day + time:

Weekday + time:

Combined expressions resolve to either a Point (day + time spec) or a Range (day + time range) on the specified day.

Architecture

How Scanning Works

Input text
    │
    ▼
┌─────────────────────┐
│ Aho-Corasick        │  Fast keyword check (~ns)
│ Prefilter           │  Rejects text with no time words
└─────────┬───────────┘
          │ keywords found
          ▼
┌─────────────────────┐
│ Per-Language         │  Regex rules with resolver closures
│ Grammar Rules       │  Run for each enabled language
└─────────┬───────────┘
          │ raw matches
          ▼
┌─────────────────────┐
│ Deduplication       │  Prefer Complete > Partial, longer > shorter
│ & Sorting           │  Remove overlapping inferior matches
└─────────┬───────────┘
          │
          ▼
     Vec<TimeMatch>

Buffer-Rescan Strategy

Rather than maintaining an incremental parser state machine, clockwords re-scans the full text buffer on every call to scan(). This is the right trade-off for GUI text input:

• Input buffers are typically < 1 KB
• Full regex scan of a short buffer completes in microseconds
• Dramatically simpler than maintaining parser state across edits
• No edge cases around cursor position, insertions, or deletions

Type Overview

GUI Integration

clockwords is designed for real-time text highlighting. Here's how to wire it up:

use clockwords::{default_scanner, MatchConfidence, TimeExpressionScanner};
use chrono::Utc;

struct App {
    scanner: TimeExpressionScanner,
}

impl App {
    fn new() -> Self {
        Self {
            scanner: default_scanner(),
        }
    }

    /// Call this on every keystroke
    fn on_text_changed(&self, text: &str) {
        let matches = self.scanner.scan(text, Utc::now());

        for m in &matches {
            let range = m.span.start..m.span.end;
            let style = match m.confidence {
                MatchConfidence::Complete => "solid_underline",
                MatchConfidence::Partial  => "dotted_underline",
            };
            // Apply `style` to the character range in your text widget
            println!("Highlight bytes {range:?} with {style}");
        }
    }
}

Partial Match Highlighting

When the user types "I worked yester", the scanner returns a Partial match on "yester". Your GUI can show a dimmed or dotted underline to hint that a time expression is being formed. Once the user completes "yesterday", the match upgrades to Complete with a fully resolved time.

To disable partial matching:

use clockwords::{ParserConfig, TimeExpressionScanner};

let config = ParserConfig {
    report_partial: false,
    ..Default::default()
};

Adding a New Language

1. Create src/lang/xx.rs (copy an existing language file as a template)
2. Implement the LanguageParser trait:
   • lang_id() — return the ISO 639-1 code (e.g. "it")
   • keywords() — return Aho-Corasick trigger words
   • keyword_prefixes() — return typing prefixes (length >= 3)
   • parse() — call apply_rules() with your GrammarRule list
3. Add number-word mappings to src/lang/numbers.rs
4. Register the language in src/lib.rs → scanner_for_languages()
5. Add tests in tests/

Each GrammarRule is a compiled regex paired with a resolver closure:

GrammarRule {
    pattern: Regex::new(r"(?i)\b(?P<day>oggi|domani|ieri)\b").unwrap(),
    kind: ExpressionKind::RelativeDay,
    resolver: |caps, now, tz| {
        let offset = match caps.name("day")?.as_str().to_lowercase().as_str() {
            "oggi" => 0,
            "domani" => 1,
            "ieri" => -1,
            _ => return None,
        };
        resolve::resolve_relative_day(offset, now, tz)
    },
}

Performance

The Aho-Corasick prefilter means that text without any time-related words is rejected in microseconds — the regex engine is never invoked.

Running Tests

cargo test

The test suite includes 141 integration tests + 1 doctest covering:

• All four languages with various expression types
• Combined weekday + time expressions across all languages
• Timezone-aware resolution (Europe/Berlin, US/Eastern, UTC)
• Cross-midnight timezone boundary handling
• Accent-tolerant variants (with and without diacritics)
• Embedded expressions in longer sentences
• Colon-delimited time parsing (3:30pm, 15:30, 13h30, 13:30)
• from X to Y with number words (nine to five)
• Incremental/partial matching
• Edge cases (empty input, no false positives)
• Cross-language default scanner

Running the TUI Demo

An interactive terminal demo is included:

cargo run --example tui_demo

Type time expressions and watch them get parsed in real time. Press ESC to quit.

Dependencies

License

Licensed under the Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0).