Skip to content

HTTPS clone URL

Subversion checkout URL

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