Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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