Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 181 lines (134 sloc) 4.233 kb
9c5279a @mojombo Update README to Markdown.
authored
1 Chronic
2 =======
3
4 ## DESCRIPTION
5
6 Chronic is a natural language date/time parser written in pure Ruby. See below
7 for the wide variety of formats Chronic will parse.
8
9
10 ## INSTALLATION
11
60ce150 clean up README
Lee Jarvis authored
12 ### RubyGems
9c5279a @mojombo Update README to Markdown.
authored
13
14 $ [sudo] gem install chronic
15
60ce150 clean up README
Lee Jarvis authored
16 ### GitHub
17
5de7d41 fix chronic git url in README
Lee Jarvis authored
18 $ git clone git://github.com/mojombo/chronic.git
60ce150 clean up README
Lee Jarvis authored
19 $ cd chronic && gem build chronic.gemspec
20 $ gem install chronic-<version>.gem
21
9c5279a @mojombo Update README to Markdown.
authored
22
23 ## USAGE
24
25 You can parse strings containing a natural language date using the
60ce150 clean up README
Lee Jarvis authored
26 `Chronic.parse` method.
9c5279a @mojombo Update README to Markdown.
authored
27
28 require 'chronic'
29
30 Time.now #=> Sun Aug 27 23:18:25 PDT 2006
31
32 Chronic.parse('tomorrow')
33 #=> Mon Aug 28 12:00:00 PDT 2006
34
35 Chronic.parse('monday', :context => :past)
36 #=> Mon Aug 21 12:00:00 PDT 2006
37
38 Chronic.parse('this tuesday 5:00')
39 #=> Tue Aug 29 17:00:00 PDT 2006
40
41 Chronic.parse('this tuesday 5:00', :ambiguous_time_range => :none)
42 #=> Tue Aug 29 05:00:00 PDT 2006
43
44 Chronic.parse('may 27th', :now => Time.local(2000, 1, 1))
45 #=> Sat May 27 12:00:00 PDT 2000
46
47 Chronic.parse('may 27th', :guess => false)
48 #=> Sun May 27 00:00:00 PDT 2007..Mon May 28 00:00:00 PDT 2007
4aba019 @cfabianski Update README for endian_precedence options
cfabianski authored
49
50 Chronic.parse('6/4/2012', :endian_precedence => :little)
51 #=> Fri Apr 06 00:00:00 PDT 2012
52
9c5279a @mojombo Update README to Markdown.
authored
53
60ce150 clean up README
Lee Jarvis authored
54 See `Chronic.parse` for detailed usage instructions.
9c5279a @mojombo Update README to Markdown.
authored
55
56
57 ## EXAMPLES
58
59 Chronic can parse a huge variety of date and time formats. Following is a
60 small sample of strings that will be properly parsed. Parsing is case
61 insensitive and will handle common abbreviations and misspellings.
62
63 Simple
64
65 * thursday
66 * november
67 * summer
68 * friday 13:00
69 * mon 2:35
70 * 4pm
71 * 6 in the morning
72 * friday 1pm
73 * sat 7 in the evening
74 * yesterday
75 * today
76 * tomorrow
77 * this tuesday
78 * next month
79 * last winter
80 * this morning
81 * last night
82 * this second
83 * yesterday at 4:00
84 * last friday at 20:00
85 * last week tuesday
86 * tomorrow at 6:45pm
87 * afternoon yesterday
88 * thursday last week
89
90 Complex
91
92 * 3 years ago
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
138 * etc
139
140
141 ## TIME ZONES
142
143 Chronic allows you to set which Time class to use when constructing times. By
144 default, the built in Ruby time class creates times in your system's local
13c83ec added link to ActiveSupport TimeZone documentation
Lee Jarvis authored
145 time zone. You can set this to something like ActiveSupport's
146 [TimeZone](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html)
147 class to get full time zone support.
9c5279a @mojombo Update README to Markdown.
authored
148
149 >> Time.zone = "UTC"
150 >> Chronic.time_class = Time.zone
151 >> Chronic.parse("June 15 2006 at 5:45 AM")
152 => Thu, 15 Jun 2006 05:45:00 UTC +00:00
153
154
155 ## LIMITATIONS
156
157 Chronic uses Ruby's built in Time class for all time storage and computation.
158 Because of this, only times that the Time class can handle will be properly
159 parsed. Parsing for times outside of this range will simply return nil.
160 Support for a wider range of times is planned for a future release.
161
162
163 ## CONTRIBUTE
164
165 If you'd like to hack on Chronic, start by forking the repo on GitHub:
166
5f7cae2 @precipice Correct 404'ing project URL in the README.
precipice authored
167 https://github.com/mojombo/chronic
9c5279a @mojombo Update README to Markdown.
authored
168
c5742d5 slight readme updates
Lee Jarvis authored
169 The best way to get your changes merged back into core is as follows:
9c5279a @mojombo Update README to Markdown.
authored
170
171 1. Clone down your fork
172 1. Create a thoughtfully named topic branch to contain your change
173 1. Hack away
174 1. Add tests and make sure everything still passes by running `rake`
c5742d5 slight readme updates
Lee Jarvis authored
175 1. Ensure your tests pass in multiple timezones. ie `TZ=utc rake` `TZ=BST rake`
9c5279a @mojombo Update README to Markdown.
authored
176 1. If you are adding new functionality, document it in the README
177 1. Do not change the version number, we will do that on our end
178 1. If necessary, rebase your commits into logical chunks, without errors
179 1. Push the branch up to GitHub
08dab52 @jfelchner Add ordinal format support: ie 'February 14th, 2004'
jfelchner authored
180 1. Send a pull request for your branch
Something went wrong with that request. Please try again.