Natural Date Parser for Java ☕️ 🗣️ 📅

Description

Natural Date Parser allows to parse date and times from natural language to java.time.LocalDateTime objects. The engine is written completely in Java, uses normalization, tokenization and pattern matching to parse (completely AI-less).

Capabilities

• Basic relative dates (e.g. today, tomorrow)
• Relative offsets with units (e.g. in 30 minutes, in 2 days, 3 weeks ago)
• Weekday expressions (e.g. next monday, last friday)
• Absolute date + time (e.g. 17 april, 21st of march, august 3rd at 10:00)
• Other date + time expressions (e.g. saturday at 5pm, tomorrow at noon)
• Fuzzy (e.g. jan for January, thu for Thursday)

Future implementations

• Absolute dates using numbers only (e.g. 10/02/2025, 2025-02-10 at 7pm)
• More complex relatives (e.g. a week from friday, the day after next monday)
• Mixed numbers and digits (e.g. twenty-one days from now, five hundred seconds ago)
• More fuzzy inputs (e.g. tmrw at 5)
• More about local date times and multi-language support

Installation

Maven

<dependency>
    <groupId>io.github.ggutim</groupId>
    <artifactId>natural-date-parser</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation("io.github.ggutim:natural-date-parser:1.0.0")

Usage

// Create the parser
NaturalDateParser parser = NaturalDateParser.builder().build();
// This will use LocalDateTime.now() as the reference date
LocalDateTime date = parser.parse("Tomorrow at 5pm");
// This will use a different reference date. Result will be relative to that one
LocalDateTime reference = LocalDateTime.of();
LocalDateTime date = parser.parse("Tomorrow at 5pm", reference);