Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 173 lines (128 sloc) 3.989 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
101
102 Specific Dates
103
104 * January 5
f7825a2 added ordinal string example to README
Lee Jarvis authored
105 * February twenty first
9c5279a @mojombo Update README to Markdown.
authored
106 * dec 25
107 * may 27th
108 * October 2006
109 * oct 06
110 * jan 3 2010
111 * february 14, 2004
08dab52 @jfelchner Add ordinal format support: ie 'February 14th, 2004'
jfelchner authored
112 * february 14th, 2004
9c5279a @mojombo Update README to Markdown.
authored
113 * 3 jan 2000
114 * 17 april 85
115 * 5/27/1979
116 * 27/5/1979
117 * 05/06
118 * 1979-05-27
119 * Friday
120 * 5
121 * 4:00
122 * 17:00
123 * 0800
124
125 Specific Times (many of the above with an added time)
126
127 * January 5 at 7pm
128 * 1979-05-27 05:00:00
129 * etc
130
131
132 ## TIME ZONES
133
134 Chronic allows you to set which Time class to use when constructing times. By
135 default, the built in Ruby time class creates times in your system's local
13c83ec added link to ActiveSupport TimeZone documentation
Lee Jarvis authored
136 time zone. You can set this to something like ActiveSupport's
137 [TimeZone](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html)
138 class to get full time zone support.
9c5279a @mojombo Update README to Markdown.
authored
139
140 >> Time.zone = "UTC"
141 >> Chronic.time_class = Time.zone
142 >> Chronic.parse("June 15 2006 at 5:45 AM")
143 => Thu, 15 Jun 2006 05:45:00 UTC +00:00
144
145
146 ## LIMITATIONS
147
148 Chronic uses Ruby's built in Time class for all time storage and computation.
149 Because of this, only times that the Time class can handle will be properly
150 parsed. Parsing for times outside of this range will simply return nil.
151 Support for a wider range of times is planned for a future release.
152
153
154 ## CONTRIBUTE
155
156 If you'd like to hack on Chronic, start by forking the repo on GitHub:
157
5f7cae2 @precipice Correct 404'ing project URL in the README.
precipice authored
158 https://github.com/mojombo/chronic
9c5279a @mojombo Update README to Markdown.
authored
159
160 To get all of the dependencies, install the gem first. The best way to get
161 your changes merged back into core is as follows:
162
163 1. Clone down your fork
164 1. Create a thoughtfully named topic branch to contain your change
165 1. Hack away
166 1. Add tests and make sure everything still passes by running `rake`
60ce150 clean up README
Lee Jarvis authored
167 1. Ensure your tests pass in multiple timezones
9c5279a @mojombo Update README to Markdown.
authored
168 1. If you are adding new functionality, document it in the README
169 1. Do not change the version number, we will do that on our end
170 1. If necessary, rebase your commits into logical chunks, without errors
171 1. Push the branch up to GitHub
08dab52 @jfelchner Add ordinal format support: ie 'February 14th, 2004'
jfelchner authored
172 1. Send a pull request for your branch
Something went wrong with that request. Please try again.