Chronic-0.1.0

Ruby
1

I am pleased to announce the FIRST release of Chronic.

project: http://rubyforge.org/projects/chronic
docs: http://chronic.rubyforge.org/

This is a preview and feedback solicitation release. I would love to
field any comments or questions you may have about the library.

==Description

Chronic is a natural language date/time parser written in pure Ruby. See
below for the wide variety of formats Chronic will parse.

==Installation

Chronic can be installed via RubyGems:

$ sudo gem install chronic

==Usage

You can parse strings containing a natural language date or time using
the Chronic.parse method.

require ‘chronic’

Time.now #=> Sun Aug 27 23:18:25 PDT 2006

#—

Chronic.parse(‘tomorrow’)
#=> Mon Aug 28 12:00:00 PDT 2006

Chronic.parse(‘monday’, :context => :past)
#=> Mon Aug 21 12:00:00 PDT 2006

Chronic.parse(‘this tuesday 5:00’)
#=> Tue Aug 29 17:00:00 PDT 2006

Chronic.parse(‘this tuesday 5:00’, :ambiguous_time_range => :none)
#=> Tue Aug 29 05:00:00 PDT 2006

Chronic.parse(‘may 27th’, :now => Time.local(2000, 1, 1))
#=> Sat May 27 12:00:00 PDT 2000

Chronic.parse(‘may 27th’, :guess => false)
#=> Sun May 27 00:00:00 PDT 2007…Mon May 28 00:00:00 PDT 2007

See Chronic.parse for detailed usage instructions.

==Examples

Chronic can parse a huge variety of date and time formats. Following is
a small sample of strings that will be properly parsed. Parsing is case
insensitive and will handle common abbreviations and misspellings.

Simple

thursday
november
summer
friday 13:00
mon 2:35
4pm
6 in the morning
friday 1pm
sat 7 in the evening
yesterday
today
tomorrow
this tuesday
next month
last winter
this morning
last night
this second
yesterday at 4:00
last friday at 20:00
last week tuesday
tomorrow at 6:45pm
afternoon yesterday
thursday last week

Complex

3 years ago
5 months before now
7 hours ago
7 days from now
1 week hence
in 3 hours
1 year ago tomorrow
3 months ago saturday at 5:00 pm
7 hours before tomorrow at noon
3rd wednesday in november
3rd month next year
3rd thursday this september
4th day last week

Specific Dates

January 5
dec 25
may 27th
October 2006
oct 06
jan 3 2010
february 14, 2004
3 jan 2000
17 april 85
5/27/1979
27/5/1979
05/06
1979-05-27
Friday
5
4:00
17:00
0800

Specific Times (many of the above with an added time)

January 5 at 7pm
1979-05-27 05:00
etc

==Limitations

Chronic uses Ruby’s built in Time class for all time storage and
computation. Because of this, only times that the Time class can handle
will be properly parsed. Parsing for times outside of this range will
simply return nil. Support for a wider range of times is planned for a
future release.

Time zones other than the local one are not currently supported. Support
for other time zones is planned for a future release.

Tom

2

On 9/7/06, Tom W. [email protected] wrote:

I am pleased to announce the FIRST release of Chronic.

project: http://rubyforge.org/projects/chronic
docs: http://chronic.rubyforge.org/

This is a preview and feedback solicitation release. I would love to field any comments or questions you may have about the library.

==Description

Chronic is a natural language date/time parser written in pure Ruby. See below for the wide variety of formats Chronic will parse.

This is really really awesome. How did you implement stuff like “the
3rd tuesday in January”? I’ve been wrestling with that concept for
awhile not in a OS X Dashboard clock I made.
-Mat

3

Mat S. wrote:

On 9/7/06, Tom W. [email protected] wrote:

Chronic is a natural language date/time parser written in pure Ruby.
See below for the wide variety of formats Chronic will parse.

This is really really awesome. How did you implement stuff like “the
3rd tuesday in January”? I’ve been wrestling with that concept for
awhile not in a OS X Dashboard clock I made.
-Mat

Chronic uses a compiler approach, so the date is parsed, tokenized, and
then run through a list of possible matches. The first matching rule
fires off a handler that knows how to deal with that pattern. To handle
things like “3rd tuesday in january”, it goes something like this:

3rd [ordinal-3]
tuesday [repeater-dayname-tuesday]
in [pointer-future]
january [repeater-monthname-january]

Which matches a pattern that knows to look for the next future January,
and beginning with the start of that month, look for the next future
Tuesday three times. There are classes that represent each of the
possible repeaters (there a lot of them!), and know everything about how
to find the next, previous, or this span, and to do offsets. Examine the
source code if you’re really interested, it shouldn’t be too hard to
grok.

Tom

4

Hey Tom,

Not sure if you have seen DateBocks (http://datebocks.inimit.com), it
does much of the same in JavaScript.

Very cool plugin indeed, if I do say so myself :wink:

-NSHB

On 9/7/06, Tom W. [email protected] wrote:

Chronic uses a compiler approach, so the date is parsed, tokenized, and
and beginning with the start of that month, look for the next future
Software Developer
[email protected]
www.helmetstohardhats.org

–
Nathaniel Steven Henry Brown

Open Source Insight - http://nshb.net
Open Source Development - http://inimit.com
Open Source Training - http://osevents.com

5

Nathaniel B. wrote:

Hey Tom,

Not sure if you have seen DateBocks (http://datebocks.inimit.com), it
does much of the same in JavaScript.

I did indeed see DateBocks, and like it very much! For a lot of use
cases, your solution is perfect. The immediate verification you do (with
JS) is very cool.

I admit freely that Chronic tends a bit towards the academic, but I hope
it will find its place. You can do some fun things with Chronic like
setting the context to the past, setting a “now” date on which to base
everything, specifying a block of 12 hours to use in case of unadorned
times (like 5:00), and returning the entire time span for date/times
that are longer than one second.

Tom

6

This is going to make part of my upcoming project SOOO much easier.

Thanks.

7

I’ve followed the install instructions perfectly. I can only require
‘chronice’ after i require ‘rubygems’. And then there is a problem?
Any ideas? :

~> irb
irb(main):001:0> require ‘chronic’
LoadError: no such file to load – chronic
from (irb):1:in require' from (irb):1 irb(main):002:0> require 'rubygems' => true irb(main):003:0> require 'chronic' NameError: uninitialized constant Chronic::RepeaterSeason from /usr/local/lib/ruby/gems/1.8/gems/chronic-0.1.0/lib/chronic/repeaters/repeater_season_name.rb:1 from /usr/local/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:21:inrequire’
from
/usr/local/lib/ruby/gems/1.8/gems/chronic-0.1.0/lib/chronic.rb:22
from
/usr/local/lib/ruby/gems/1.8/gems/chronic-0.1.0/lib/chronic.rb:21
from
/usr/local/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:21:in
require' from /usr/local/lib/ruby/site_ruby/1.8/rubygems.rb:182:inactivate’
from /usr/local/lib/ruby/site_ruby/1.8/rubygems.rb:181:in
activate' from /usr/local/lib/ruby/site_ruby/1.8/rubygems/custom_require.rb:26:inrequire’
from (irb):3
irb(main):004:0>

8

I am pleased to announce the FIRST release of Chronic.

Not had a chance to download yet, but you don’t give an example of
something like “ten to four” or “quater past five tomorrow” - are those
supported? If they’re not, then that’s a feature suggestion :slight_smile:

9

On 9/8/06, Tom W. [email protected] wrote:

I admit freely that Chronic tends a bit towards the academic, but I hope
it will find its place. You can do some fun things with Chronic like
setting the context to the past, setting a “now” date on which to base
everything, specifying a block of 12 hours to use in case of unadorned
times (like 5:00), and returning the entire time span for date/times
that are longer than one second.

For one, on unix systems it’d make a great frontend to at

martin

10

[email protected] wrote:

I am pleased to announce the FIRST release of Chronic.

Not had a chance to download yet, but you don’t give an example of
something like “ten to four” or “quater past five tomorrow” - are those
supported? If they’re not, then that’s a feature suggestion :slight_smile:

Currently not supported, but it’s on the todo list!

Tom

11

I have been looking at Runt and was wondering if there is planned
support for something similar here such as natural language ranges to
create temporal expressions “every other Monday between 16:00 and 10pm
except 9/18/06”

12

Josh Martin wrote:

I have been looking at Runt and was wondering if there is planned
support for something similar here such as natural language ranges to
create temporal expressions “every other Monday between 16:00 and 10pm
except 9/18/06”

Recurring events (e.g. every monday) and time ranges (e.g. 9am-5pm) are
planned. Chronic’s architecture should make these enhancements
relatively straightforward. If you have specific requirements/use cases
you’re looking to see implemented, please post them as feature requests
on the tracker at rubyforge.org/projects/chronic.

Tom

13
  • Tom W. wrote:

I am pleased to announce the FIRST release of Chronic.

Nice work!

Chronic uses Ruby’s built in Time class for all time storage and
computation. Because of this, only times that the Time class can
handle will be properly parsed. Parsing for times outside of this
range will simply return nil. Support for a wider range of times is
planned for a future release.

Some things that I noticed on Cygwin:

  • I have to require ‘time’, otherwise, I’m getting an error “no method
    parse for class Time”. I’ll put that into chronic.rb
  • I had to upgrade to Ruby 1.8.5. With 1.8.4, I got lots of “time out of
    range” errors
  • it would be good if non-supported constructions return “nil” always,
    but sometimes they return wrong parses, and some produce errors

Examples:

“now”
-> Wed Sep 13 16:09:16 -0400 2006

“20 minutes before noon tomorrow”
-> Wed Sep 13 23:40:00 -0400 2006
(= “20 minutes before midnight”, how come?)

“in a few days”
-> Thu Sep 14 16:12:30 -0400 2006
(= “in a day”)

“hour”
-> Wed Sep 13 16:37:00 -0400 2006
(= “the middle between the next full minute and the next hour”)

Similarly, “day”, “year” etc. make for weird answers. The same answers
come out if you combine them with ignored words, e.g.:

“one hour back” (= “hour” = “the middle between the next full minute and
the next hour”)
“three days later” (= “day” = “the middle between the next full hour and
the next day”)

“3 days later”
-> Wed Sep 13 15:00:00 -0400 2006
(= “3 days” = “3 day” = “3 today”)

“20 minutes before 3 yesterday”
-> Error

/usr/lib/ruby/gems/1.8/gems/chronic-0.1.1/lib/chronic/repeaters/repeater_minute.
rb:11:in offset': undefined method+’ for nil:NilClass (NoMethodError)
[…]

For the future, it would be nice if it understood “five hours” as well
as “5 hours”.

I’m working in NLP and ready to help.

14

On 9/7/06, Tom W. [email protected] wrote:

Which matches a pattern that knows to look for the next future January,
and beginning with the start of that month, look for the next future
Tuesday three times. There are classes that represent each of the
possible repeaters (there a lot of them!), and know everything about how
to find the next, previous, or this span, and to do offsets. Examine the
source code if you’re really interested, it shouldn’t be too hard to grok.

Okay, so you use an itertive approach. I made this clock for OS X’s
dashboard that does it using a formula borrowed from another widget.
No-one I’ve showed it to has been able to figure out just what it
does. If you’re interested, I suppose it’d be better suited to an
offline discussion. Feel free to email me.
-Mat