when
A natural language date/time parser with pluggable rules and merge strategies for Go applications.
What is when?
When is a Go library for parsing natural language date and time expressions into structured time data. It enables applications to understand human-readable time references like 'tonight at 11:10 pm' or 'next Tuesday at 2:25 p.m.' without requiring rigid input formats.
Go developers building applications that need to process user-entered, informal date and time strings, such as chatbots, scheduling tools, or command-line interfaces.
Developers choose When for its pluggable, multi-language rule system and configurable cluster matching, which allows precise handling of composite expressions and extensibility to new languages or custom formats.
Overview
A natural language date/time parser with pluggable rules
Use Cases
Best For
- Parsing informal date-time strings in user-generated text for chatbots or virtual assistants.
- Extracting scheduling information from natural language input in productivity or calendar applications.
- Processing log entries or timestamps that include relative time phrases like 'next Wednesday'.
- Building multilingual applications that require date-time parsing in languages like English, Russian, Brazilian Portuguese, Chinese, or Dutch.
- Handling composite time expressions where multiple date and time components are spread within a sentence.
- Creating custom parsing rules for domain-specific or niche time expressions not covered by standard libraries.
Not Ideal For
- Projects requiring strict ISO 8601 or RFC 3339 date format validation without natural language ambiguity
- High-throughput systems where low-latency parsing is critical and computational overhead from rule matching is unacceptable
- Applications needing immediate support for languages beyond English, Russian, Brazilian Portuguese, Chinese, or Dutch without custom rule development
- Use cases where date-time input must be error-proof and ambiguous phrases should be rejected rather than interpreted
Pros & Cons
Pros
Includes built-in rules for five languages (EN, RU, BR, ZH, NL) with pluggable architecture, allowing extensibility for international applications as mentioned in the README.
Groups nearby matches within a configurable distance to handle composite expressions like 'next Wednesday at 2:25 p.m.', demonstrated in the README examples with distance tuning.
Encourages community contributions for adding custom rules or languages, with an open issue system for missing cases, making it adaptable to niche or domain-specific expressions.
Allows tuning of match distance and ordering via options like Distance and MatchByOrder, providing control over how text patterns are processed for optimization.
Cons
The TODO list admits missed rules from examples like those in the chronic library, meaning some natural language expressions may not be parsed correctly out of the box.
Only the Override strategy is fully implemented, with other strategies not yet available, which can restrict conflict resolution in complex parses, as noted in the README.
The README explicitly lists describing all existing rules as a TODO item, so current documentation is incomplete and may hinder quick adoption or troubleshooting.
Natural language parsing with multiple rules and cluster matching is inherently slower than simple date parsing, making it less suitable for performance-sensitive applications without careful optimization.
Frequently Asked Questions
Related Projects
shA shell parser, formatter, and interpreter with bash and zsh support; includes shfmt
gofeedParse RSS, Atom and JSON feeds in Go
go-querystringgo-querystring is Go library for encoding structs into URL query strings.
godump (goforj)A minimal, developer-friendly pretty-printer and debug dumper for Go structs, inspired by Laravel’s dump() and Symfony’s VarDumper.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.