Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 167 lines (123 sloc) 3.765 kB
9c5279a @mojombo Update README to Markdown.
mojombo 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
faad1de @mojombo Copy/paste failure.
mojombo authored
12 The best way to install Chronic is with RubyGems:
9c5279a @mojombo Update README to Markdown.
mojombo authored
13
14 $ [sudo] gem install chronic
15
16
17 ## USAGE
18
19 You can parse strings containing a natural language date using the
20 Chronic.parse method.
21
22 require 'rubygems'
23 require 'chronic'
24
25 Time.now #=> Sun Aug 27 23:18:25 PDT 2006
26
27 #---
28
29 Chronic.parse('tomorrow')
30 #=> Mon Aug 28 12:00:00 PDT 2006
31
32 Chronic.parse('monday', :context => :past)
33 #=> Mon Aug 21 12:00:00 PDT 2006
34
35 Chronic.parse('this tuesday 5:00')
36 #=> Tue Aug 29 17:00:00 PDT 2006
37
38 Chronic.parse('this tuesday 5:00', :ambiguous_time_range => :none)
39 #=> Tue Aug 29 05:00:00 PDT 2006
40
41 Chronic.parse('may 27th', :now => Time.local(2000, 1, 1))
42 #=> Sat May 27 12:00:00 PDT 2000
43
44 Chronic.parse('may 27th', :guess => false)
45 #=> Sun May 27 00:00:00 PDT 2007..Mon May 28 00:00:00 PDT 2007
46
47 See Chronic.parse for detailed usage instructions.
48
49
50 ## EXAMPLES
51
52 Chronic can parse a huge variety of date and time formats. Following is a
53 small sample of strings that will be properly parsed. Parsing is case
54 insensitive and will handle common abbreviations and misspellings.
55
56 Simple
57
58 * thursday
59 * november
60 * summer
61 * friday 13:00
62 * mon 2:35
63 * 4pm
64 * 6 in the morning
65 * friday 1pm
66 * sat 7 in the evening
67 * yesterday
68 * today
69 * tomorrow
70 * this tuesday
71 * next month
72 * last winter
73 * this morning
74 * last night
75 * this second
76 * yesterday at 4:00
77 * last friday at 20:00
78 * last week tuesday
79 * tomorrow at 6:45pm
80 * afternoon yesterday
81 * thursday last week
82
83 Complex
84
85 * 3 years ago
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
98
99 Specific Dates
100
101 * January 5
102 * dec 25
103 * may 27th
104 * October 2006
105 * oct 06
106 * jan 3 2010
107 * february 14, 2004
08dab52 @jfelchner Add ordinal format support: ie 'February 14th, 2004'
jfelchner authored
108 * february 14th, 2004
9c5279a @mojombo Update README to Markdown.
mojombo authored
109 * 3 jan 2000
110 * 17 april 85
111 * 5/27/1979
112 * 27/5/1979
113 * 05/06
114 * 1979-05-27
115 * Friday
116 * 5
117 * 4:00
118 * 17:00
119 * 0800
120
121 Specific Times (many of the above with an added time)
122
123 * January 5 at 7pm
124 * 1979-05-27 05:00:00
125 * etc
126
127
128 ## TIME ZONES
129
130 Chronic allows you to set which Time class to use when constructing times. By
131 default, the built in Ruby time class creates times in your system's local
132 time zone. You can set this to something like ActiveSupport's TimeZone class
133 to get full time zone support.
134
135 >> Time.zone = "UTC"
136 >> Chronic.time_class = Time.zone
137 >> Chronic.parse("June 15 2006 at 5:45 AM")
138 => Thu, 15 Jun 2006 05:45:00 UTC +00:00
139
140
141 ## LIMITATIONS
142
143 Chronic uses Ruby's built in Time class for all time storage and computation.
144 Because of this, only times that the Time class can handle will be properly
145 parsed. Parsing for times outside of this range will simply return nil.
146 Support for a wider range of times is planned for a future release.
147
148
149 ## CONTRIBUTE
150
151 If you'd like to hack on Chronic, start by forking the repo on GitHub:
152
5f7cae2 @precipice Correct 404'ing project URL in the README.
precipice authored
153 https://github.com/mojombo/chronic
9c5279a @mojombo Update README to Markdown.
mojombo authored
154
155 To get all of the dependencies, install the gem first. The best way to get
156 your changes merged back into core is as follows:
157
158 1. Clone down your fork
159 1. Create a thoughtfully named topic branch to contain your change
160 1. Hack away
161 1. Add tests and make sure everything still passes by running `rake`
162 1. If you are adding new functionality, document it in the README
163 1. Do not change the version number, we will do that on our end
164 1. If necessary, rebase your commits into logical chunks, without errors
165 1. Push the branch up to GitHub
08dab52 @jfelchner Add ordinal format support: ie 'February 14th, 2004'
jfelchner authored
166 1. Send a pull request for your branch
Something went wrong with that request. Please try again.