Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 184 lines (145 sloc) 4.309 kb
9c5279a @mojombo Update README to Markdown.
authored
1 Chronic
2 =======
3
4 Chronic is a natural language date/time parser written in pure Ruby. See below
5 for the wide variety of formats Chronic will parse.
6
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
7 ## Installation
9c5279a @mojombo Update README to Markdown.
authored
8
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
9 ```
10 $ gem install chronic
11 ```
60ce150 clean up README
Lee Jarvis authored
12
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
13 ## Usage
60ce150 clean up README
Lee Jarvis authored
14
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
15 ```ruby
16 require 'chronic'
9c5279a @mojombo Update README to Markdown.
authored
17
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
18 Time.now #=> Sun Aug 27 23:18:25 PDT 2006
9c5279a @mojombo Update README to Markdown.
authored
19
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
20 Chronic.parse('tomorrow')
21 #=> Mon Aug 28 12:00:00 PDT 2006
9c5279a @mojombo Update README to Markdown.
authored
22
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
23 Chronic.parse('monday', :context => :past)
24 #=> Mon Aug 21 12:00:00 PDT 2006
9c5279a @mojombo Update README to Markdown.
authored
25
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
26 Chronic.parse('this tuesday 5:00')
27 #=> Tue Aug 29 17:00:00 PDT 2006
9c5279a @mojombo Update README to Markdown.
authored
28
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
29 Chronic.parse('this tuesday 5:00', :ambiguous_time_range => :none)
30 #=> Tue Aug 29 05:00:00 PDT 2006
9c5279a @mojombo Update README to Markdown.
authored
31
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
32 Chronic.parse('may 27th', :now => Time.local(2000, 1, 1))
33 #=> Sat May 27 12:00:00 PDT 2000
9c5279a @mojombo Update README to Markdown.
authored
34
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
35 Chronic.parse('may 27th', :guess => false)
36 #=> Sun May 27 00:00:00 PDT 2007..Mon May 28 00:00:00 PDT 2007
9c5279a @mojombo Update README to Markdown.
authored
37
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
38 Chronic.parse('6/4/2012', :endian_precedence => :little)
39 #=> Fri Apr 06 00:00:00 PDT 2012
9a828dd @johari add failing Chronic.parse example to README
johari authored
40
41 Chronic.parse('INVALID DATE')
42 #=> nil
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
43 ```
9c5279a @mojombo Update README to Markdown.
authored
44
9a828dd @johari add failing Chronic.parse example to README
johari authored
45 If the parser can find a date or time, either a Time or Chronic::Span
46 will be returned (depending on the value of `:guess`). If no
47 date or time can be found, `nil` will be returned.
48
60ce150 clean up README
Lee Jarvis authored
49 See `Chronic.parse` for detailed usage instructions.
9c5279a @mojombo Update README to Markdown.
authored
50
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
51 ## Examples
9c5279a @mojombo Update README to Markdown.
authored
52
53 Chronic can parse a huge variety of date and time formats. Following is a
54 small sample of strings that will be properly parsed. Parsing is case
55 insensitive and will handle common abbreviations and misspellings.
56
57 Simple
58
59 * thursday
60 * november
61 * summer
62 * friday 13:00
63 * mon 2:35
64 * 4pm
c3b311c @chicagogrooves Added support for time expressions such as '10 till' or 'half past two'
chicagogrooves authored
65 * 10 to 8
66 * 10 past 2
67 * half past 2
9c5279a @mojombo Update README to Markdown.
authored
68 * 6 in the morning
69 * friday 1pm
70 * sat 7 in the evening
71 * yesterday
72 * today
73 * tomorrow
9bae166 @joshwalsh Added next/last week to documentation
joshwalsh authored
74 * last week
75 * next week
9c5279a @mojombo Update README to Markdown.
authored
76 * this tuesday
77 * next month
78 * last winter
79 * this morning
80 * last night
81 * this second
82 * yesterday at 4:00
83 * last friday at 20:00
84 * last week tuesday
85 * tomorrow at 6:45pm
86 * afternoon yesterday
87 * thursday last week
88
89 Complex
90
91 * 3 years ago
0024100 @steveburkett add support for an hour
steveburkett authored
92 * a year ago
9c5279a @mojombo Update README to Markdown.
authored
93 * 5 months before now
94 * 7 hours ago
95 * 7 days from now
96 * 1 week hence
97 * in 3 hours
98 * 1 year ago tomorrow
99 * 3 months ago saturday at 5:00 pm
100 * 7 hours before tomorrow at noon
101 * 3rd wednesday in november
102 * 3rd month next year
103 * 3rd thursday this september
104 * 4th day last week
ebca496 add a couple more complex dates to the readme
Lee Jarvis authored
105 * fourteenth of june 2010 at eleven o'clock in the evening
106 * may seventh '97 at three in the morning
9c5279a @mojombo Update README to Markdown.
authored
107
108 Specific Dates
109
110 * January 5
152124b added support for ordinal-day/repeater-month-name with optional time
Lee Jarvis authored
111 * 22nd of june
0fc3f13 Added support for parsing ordinal-dates/month-names/year
Lee Jarvis authored
112 * 5th may 2017
f7825a2 added ordinal string example to README
Lee Jarvis authored
113 * February twenty first
9c5279a @mojombo Update README to Markdown.
authored
114 * dec 25
115 * may 27th
116 * October 2006
117 * oct 06
118 * jan 3 2010
119 * february 14, 2004
08dab52 @jfelchner Add ordinal format support: ie 'February 14th, 2004'
jfelchner authored
120 * february 14th, 2004
9c5279a @mojombo Update README to Markdown.
authored
121 * 3 jan 2000
122 * 17 april 85
123 * 5/27/1979
124 * 27/5/1979
125 * 05/06
126 * 1979-05-27
127 * Friday
128 * 5
129 * 4:00
130 * 17:00
131 * 0800
132
133 Specific Times (many of the above with an added time)
134
135 * January 5 at 7pm
152124b added support for ordinal-day/repeater-month-name with optional time
Lee Jarvis authored
136 * 22nd of june at 8am
9c5279a @mojombo Update README to Markdown.
authored
137 * 1979-05-27 05:00:00
f019cd6 @davispuh Support for time with subseconds.
davispuh authored
138 * 03/01/2012 07:25:09.234567
9c5279a @mojombo Update README to Markdown.
authored
139 * etc
140
141
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
142 ## Time Zones
9c5279a @mojombo Update README to Markdown.
authored
143
144 Chronic allows you to set which Time class to use when constructing times. By
145 default, the built in Ruby time class creates times in your system's local
13c83ec added link to ActiveSupport TimeZone documentation
Lee Jarvis authored
146 time zone. You can set this to something like ActiveSupport's
147 [TimeZone](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html)
148 class to get full time zone support.
9c5279a @mojombo Update README to Markdown.
authored
149
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
150 ```
151 >> Time.zone = "UTC"
152 >> Chronic.time_class = Time.zone
153 >> Chronic.parse("June 15 2006 at 5:45 AM")
154 => Thu, 15 Jun 2006 05:45:00 UTC +00:00
155 ```
9c5279a @mojombo Update README to Markdown.
authored
156
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
157 ## Limitations
9c5279a @mojombo Update README to Markdown.
authored
158
159 Chronic uses Ruby's built in Time class for all time storage and computation.
160 Because of this, only times that the Time class can handle will be properly
161 parsed. Parsing for times outside of this range will simply return nil.
162 Support for a wider range of times is planned for a future release.
163
164
cef2d4d @leejarvis updated Readme formatting
leejarvis authored
165 ## Contribute
9c5279a @mojombo Update README to Markdown.
authored
166
167 If you'd like to hack on Chronic, start by forking the repo on GitHub:
168
5f7cae2 @precipice Correct 404'ing project URL in the README.
precipice authored
169 https://github.com/mojombo/chronic
9c5279a @mojombo Update README to Markdown.
authored
170
c5742d5 slight readme updates
Lee Jarvis authored
171 The best way to get your changes merged back into core is as follows:
9c5279a @mojombo Update README to Markdown.
authored
172
173 1. Clone down your fork
174 1. Create a thoughtfully named topic branch to contain your change
7efdf11 @dnrce Instruct developers to use Bundler
dnrce authored
175 1. Install the development dependencies by running `bundle install`
9c5279a @mojombo Update README to Markdown.
authored
176 1. Hack away
7efdf11 @dnrce Instruct developers to use Bundler
dnrce authored
177 1. Add tests and make sure everything still passes by running `bundle exec rake`
178 1. Ensure your tests pass in multiple timezones. ie `TZ=utc bundle exec rake` `TZ=BST bundle exec rake`
9c5279a @mojombo Update README to Markdown.
authored
179 1. If you are adding new functionality, document it in the README
180 1. Do not change the version number, we will do that on our end
181 1. If necessary, rebase your commits into logical chunks, without errors
182 1. Push the branch up to GitHub
08dab52 @jfelchner Add ordinal format support: ie 'February 14th, 2004'
jfelchner authored
183 1. Send a pull request for your branch
Something went wrong with that request. Please try again.