Skip to content
Newer
Older
100644 158 lines (107 sloc) 6.74 KB
c71a80f @bokmann Initial commit to business_time.
authored Apr 13, 2010
1 = business_time
2
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
3 ActiveSupport gives us some great helpers so we can do things like:
4
59e157f @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
5 5.days.ago
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
6
7 and
8
59e157f @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
9 8.hours.from_now
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
10
11 as well as helpers to do that from any provided date or time.
12
13 I needed this, but taking into account business hours/days and holidays.
14
15 == Usage
16 * install the gem
17
4589779 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
18 gem install business_time
19
20 or
21
22 sudo gem install business_time
23
24 if you require sudo to install gems
25
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
26 * open up your console
27
dfaa160 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
28 # if in irb, add these lines:
4987a47 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
29
dfaa160 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
30 require 'rubygems'
31 require 'active_support'
32 require 'business_time'
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
33
dfaa160 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
34 # try these examples, using the current time:
4987a47 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
35
dfaa160 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
36 1.business_hour.from_now
37 4.business_hours.from_now
38 8.business_hours.from_now
39
40 1.business_hour.ago
41 4.business_hours.ago
42 8.business_hours.ago
43
44 1.business_day.from_now
45 4.business_days.from_now
46 8.business_days.from_now
47
48 1.business_day.ago
49 4.business_days.ago
50 8.business_days.ago
51
52 # and we can do it from any Date or Time object.
53 my_birthday = Date.parse("August 4th, 1969")
54 8.business_days.after(my_birthday)
55 8.business_days.before(my_birthday)
56
57 my_birthday = Time.parse("August 4th, 1969, 8:32 am")
58 8.business_days.after(my_birthday)
59 8.business_days.before(my_birthday)
60
61
62 # We can adjust the start and end time of our business hours
63 BusinessTime::Config.beginning_of_workday = "8:30 am"
64 BusinessTime::Config.end_of_workday = "5:30 pm"
65
66 # and we can add holidays that don't count as business days
67 # July 5 in 2010 is a monday that the U.S. takes off because our independence day falls on that Sunday.
68 three_day_weekend = Date.parse("July 5th, 2010")
69 BusinessTime::Config.holidays << three_day_weekend
70 friday_afternoon = Time.parse("July 2nd, 2010, 4:50 pm")
71 tuesday_morning = 1.business_hour.after(friday_afternoon)
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
72
36e7810 @piotrj Added functionality of calculating business duration (number of busin…
piotrj authored Dec 22, 2010
73 # you can always calculate business duration between two dates
74 friday = Date.parse("December 24, 2010")
75 monday = Date.parse("December 27, 2010")
76 friday.business_days_until(monday) #=> 1
77
ee0cf71 @bokmann instructions for the new initializer
authored Apr 14, 2010
78 == Usage in Rails
79 The code above should work on a rails console without any issue. You will want to add a line something like:
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
80
ee0cf71 @bokmann instructions for the new initializer
authored Apr 14, 2010
81 config.gem "business_time"
82
54fd209 @enricob Add Rails 3 generator and instructions for use
enricob authored Apr 14, 2010
83 to your environment.rb file. Or if you're using bundler, add this line to your Gemfile:
84
85 gem "business_time"
86
87 This gem also includes a generator so you can bootstrap some stuff in your environment:
ee0cf71 @bokmann instructions for the new initializer
authored Apr 14, 2010
88
89 ./script/generate business_time_config
90
54fd209 @enricob Add Rails 3 generator and instructions for use
enricob authored Apr 15, 2010
91 Or in Rails 3:
92
93 script/rails generate business_time:config
94
95 The generator will add a /config/business_time.yml and a /config/initializers/business_time.rb file that will cause the start of business day, the end of business day, and your holidays to be loaded from the yaml file. You might want to programatically load your holidays from a database table, but you will want to pay attention to how the initializer works - you will want to make sure that the initializer sets stuff up appropriately so rails instances on mongrels or passenger will have the appropriate data as they come up and down.
ee0cf71 @bokmann instructions for the new initializer
authored Apr 14, 2010
96
97 == Outside of Rails
98 This code does depend on ActiveSupport, but nothing else within rails. Even then, it would be pretty easy to break that dependency as well (but would add some code bloat and remove some clarity). Feel free to use it on any ruby project you'd like!
c71a80f @bokmann Initial commit to business_time.
authored Apr 13, 2010
99
011fe83 @bokmann adding readme timezone information and Arild credit
authored May 30, 2010
100 == Timezone support
101 This gem strives to be timezone-agnostic. Due to some complications in the handling of timezones in the built in Time class, and some complexities (bugs?) in the timeWithZone class, this was harder than expected... but here's the idea:
5679a71 @bokmann other important notes
authored May 30, 2010
102
103 * When you configure the gem with something like 9:00am as the start time,
104 this is agnostic of time zone.
105 * When you are dealing with a Time or TimeWithZone class, the timezone is
106 preserved and the beginning and end of times for the business day are
107 referenced in that time zone.
011fe83 @bokmann adding readme timezone information and Arild credit
authored May 30, 2010
108
109 This can lead to some wierd looking effects if, say, you are in the Eastern time zone but doing everything in UTC times... Your business day will appear to start and end at 9:00 and 5:00 UTC. If this seems perplexing to you, I can almost guarantee you are in over your head with timezones in other ways too, this is just the first place you encountered it. Timezone relative date handling gets more and more complicated every time you look at it and takes a long time before it starts to seem simple again. I'm hoping Arild and I write some good blog entries on the subject at http://blog.codesherpas.com.
110
6aca0ac @bokmann giving creait where credit is due
authored Apr 16, 2010
111 == Contributors
112 * David Bock http://github.com/bokmann
113 * Enrico Bianco http://github.com/enricob
011fe83 @bokmann adding readme timezone information and Arild credit
authored May 30, 2010
114 * Arild Shirazi http://github.com/ashirazi
115
116 (Special thanks for Arild on the complexities of dealing with TimeWithZone)
117
c71a80f @bokmann Initial commit to business_time.
authored Apr 13, 2010
118 == Note on Patches/Pull Requests
119
120 * Fork the project.
121 * Make your feature addition or bug fix.
122 * Add tests for it. This is important so I don't break it in a
123 future version unintentionally.
124 * Commit, do not mess with rakefile, version, or history.
125 (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
126 * Send me a pull request. Bonus points for topic branches.
127
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
128 == TODO
5679a71 @bokmann other important notes
authored May 30, 2010
129
130 * if it doesn't pollute the logic too much, I'd like to vary the days counted as 'business days'. Bakers often
131 don't work on Mondays, for instance. I'd do it in something like this:
132
133 BusinessTime::Config.work_week = [:tue, :wed, :thur, :fri, :sat]
134
135 * Arild has pointed out that there may be some logical inconsistencies
136 regaring the beginning_of_workday and end_of workday times not actually
137 being considered inside of the workday. I'd like to make sure that they
138 work as if the beginning_of_workday is included and the end_of_workday is
02054d0 @bokmann other important notes
authored May 30, 2010
139 not included, just like the '...' range operator in Ruby.
2f1b654 @bokmann adding the readme - making sure formatting is correct
authored Apr 13, 2010
140
b524255 @bokmann important notes on what I'm not going to do as well
authored May 30, 2010
141 == NOT TODO
5679a71 @bokmann other important notes
authored May 30, 2010
142
b524255 @bokmann important notes on what I'm not going to do as well
authored May 30, 2010
143 * I spent way too much time in my previous java-programmer life building frameworks that worshipped complexity,
144 always trying to give the developer-user ultimate flexibility at the expense of the 'surface area' of the api.
145 Never again - I will sooner limit functionality to 80% so that something stays usable and let people fork.
146 * While there have been requests to add 'business minutes' and even 'business seconds' to this gem, I won't
147 entertain a pullup request with such things. If you find it useful, great. Most users won't, and they don't
148 need the baggage.
149 * I'm torn on the inclusion of some kind of business_duration_between two Times, for the following reasons:
150 * As a duration, it will be in seconds. This would naturally be business-seconds, which I trimmed out above.
151 * The logic is complex and error prone.
152 * There is no logical place to put it, as most of this gem mirrors the Timehelpers in ActiveSupport.
153 As a result I'm unlikely to add it unless I have an epiphany or someone wows me with an awesome pullup request.
154
c71a80f @bokmann Initial commit to business_time.
authored Apr 13, 2010
155 == Copyright
156
157 Copyright (c) 2010 bokmann. See LICENSE for details.
Something went wrong with that request. Please try again.