Skip to content
Newer
Older
100644 172 lines (127 sloc) 3.83 KB
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
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 Jun 3, 2011
12 ### RubyGems
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
13
14 $ [sudo] gem install chronic
15
60ce150 clean up README
Lee Jarvis authored Jun 3, 2011
16 ### GitHub
17
5de7d41 fix chronic git url in README
Lee Jarvis authored Jun 3, 2011
18 $ git clone git://github.com/mojombo/chronic.git
60ce150 clean up README
Lee Jarvis authored Jun 3, 2011
19 $ cd chronic && gem build chronic.gemspec
20 $ gem install chronic-<version>.gem
21
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
22
23 ## USAGE
24
25 You can parse strings containing a natural language date using the
60ce150 clean up README
Lee Jarvis authored Jun 3, 2011
26 `Chronic.parse` method.
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
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 Jun 3, 2011
50 See `Chronic.parse` for detailed usage instructions.
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
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 Jun 3, 2011
105 * February twenty first
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
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 Nov 24, 2010
112 * february 14th, 2004
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
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
136 time zone. You can set this to something like ActiveSupport's TimeZone class
137 to get full time zone support.
138
139 >> Time.zone = "UTC"
140 >> Chronic.time_class = Time.zone
141 >> Chronic.parse("June 15 2006 at 5:45 AM")
142 => Thu, 15 Jun 2006 05:45:00 UTC +00:00
143
144
145 ## LIMITATIONS
146
147 Chronic uses Ruby's built in Time class for all time storage and computation.
148 Because of this, only times that the Time class can handle will be properly
149 parsed. Parsing for times outside of this range will simply return nil.
150 Support for a wider range of times is planned for a future release.
151
152
153 ## CONTRIBUTE
154
155 If you'd like to hack on Chronic, start by forking the repo on GitHub:
156
5f7cae2 @precipice Correct 404'ing project URL in the README.
precipice authored Mar 9, 2011
157 https://github.com/mojombo/chronic
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
158
159 To get all of the dependencies, install the gem first. The best way to get
160 your changes merged back into core is as follows:
161
162 1. Clone down your fork
163 1. Create a thoughtfully named topic branch to contain your change
164 1. Hack away
165 1. Add tests and make sure everything still passes by running `rake`
60ce150 clean up README
Lee Jarvis authored Jun 3, 2011
166 1. Ensure your tests pass in multiple timezones
9c5279a @mojombo Update README to Markdown.
authored Oct 22, 2010
167 1. If you are adding new functionality, document it in the README
168 1. Do not change the version number, we will do that on our end
169 1. If necessary, rebase your commits into logical chunks, without errors
170 1. Push the branch up to GitHub
08dab52 @jfelchner Add ordinal format support: ie 'February 14th, 2004'
jfelchner authored Nov 24, 2010
171 1. Send a pull request for your branch
Something went wrong with that request. Please try again.