chronic
A pure Ruby natural language date/time parser that converts human-readable phrases into structured time objects.
What is chronic?
Chronic is a natural language date and time parser written in pure Ruby. It converts human-readable phrases like 'tomorrow at 5pm' or '3 years ago' into structured Ruby Time objects or time spans, solving the problem of interpreting flexible date inputs in applications.
Ruby developers building applications that need to parse user-provided date strings, particularly those working on scheduling tools, calendar applications, or any system requiring flexible date input handling.
Developers choose Chronic for its extensive natural language support, pure Ruby implementation with no dependencies, and configurable parsing options that handle edge cases like time zones and ambiguous date ranges.
Overview
Chronic is a pure Ruby natural language date parser.
Use Cases
Best For
- Parsing user-entered date strings in Ruby web applications
- Building scheduling or calendar tools with natural language input
- Processing log files with human-readable timestamps
- Creating command-line tools that accept flexible date arguments
- Implementing reminder systems with phrases like 'in 3 hours'
- Handling international date formats and time zone conversions
Not Ideal For
- High-throughput applications parsing standardized date formats like ISO 8601, where dedicated parsers offer better performance
- Projects requiring handling of dates outside Ruby's Time class range (e.g., before 1901 or after 2038 on many systems)
- Non-Ruby environments or polyglot projects needing a language-agnostic date parsing solution
- Systems where precise, unambiguous date interpretation is critical and natural language inference could lead to errors
Pros & Cons
Pros
Parses a wide variety of human-readable phrases from simple terms like 'tomorrow' to complex expressions like '7 hours before tomorrow at noon', as shown in the extensive examples list.
Implemented in pure Ruby with no external gems, making it easy to add to any Ruby project without additional setup or compatibility issues.
Offers settings like :context for past/future hints and :ambiguous_time_range for control over time interpretation, allowing developers to fine-tune accuracy for edge cases.
Supports custom time classes, enabling integration with systems like ActiveSupport::TimeZone for proper time zone handling, as demonstrated in the README.
Cons
Relies on Ruby's built-in Time class, so dates outside its supported range will return nil, a limitation explicitly admitted in the README that restricts use for historical or far-future dates.
Natural language inputs can be misinterpreted; for example, 'this tuesday 5:00' defaults to PM without configuration, requiring careful option setting to avoid errors in time-sensitive applications.
Primarily optimized for English date expressions, making it less suitable for international applications without custom preprocessing or modifications for other languages.
Frequently Asked Questions
Related Projects
groupdateThe simplest way to group temporal data
ice_cubeRuby Date Recurrence Library - Allows easy creation of recurrence rules and fast querying
local_timeRails engine for cache-friendly, client-side local time
validates_timelinessDate and time validation plugin for ActiveModel and Rails. Supports multiple ORMs and allows custom date/time formats.
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.