"Up, and down, and in the end, it's only round and round and round..." - Pink Floyd, "Us and Them"
(Image Courtesy of "Pink Floyd: Time," directed by Ian Eames , ©1973)
Generate periodic datetime blocks based on provided rules/conditions. Great for (but not limited to) calendar and scheduling applications. See Usage for detailed examples.
Add this line to your application's Gemfile:
gem 'periodoxical'And then execute:
$ bundle
Or install it yourself as:
$ gem install periodoxical
As a Ruby dev, I want to generate all the datetime blocks of 9:00AM - 10:30AM for all days from May 23, 2024 to May 26, 2024 inclusive.
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
time_blocks: [
{
start_time: '9:00AM',
end_time: '10:30AM'
},
],
starting_from: '2024-05-23',
ending_at: '2024-05-26',
)
#=>
[
{
start: #<DateTime: 2024-05-23T09:00:00-0700>,
end: #<DateTime: 2024-05-23T10:30:00-0700>,
},
{
start: #<DateTime: 2024-05-24T09:00:00-0700>,
end: #<DateTime: 2024-05-24T10:30:00-0700>,
},
{
start: #<DateTime: 2024-05-25T09:00:00-0700>,
end: #<DateTime: 2024-05-25T10:30:00-0700>,
},
{
start: #<DateTime: 2024-05-26T09:00:00-0700>,
end: #<DateTime: 2024-05-26T10:30:00-0700>,
}
]The starting_from and ending_at params can also accept datetimes in ISO 8601 format. This example generate all the datetime blocks of 9:00AM - 10:30AM but starting from May 23, 2024 at 9:30AM.
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
time_blocks: [
{
start_time: '9:00AM',
end_time: '10:30AM'
},
],
starting_from: '2024-05-23T09:30:00-07:00', # can be string in iso8601 format
ending_at: DateTime.parse('2024-05-26T17:00:00-07:00'), # or an instance of DateTime
)
#=> [
# 2024-05-23 was skipped because the 9AM time block was before
# the `starting_from` of '2024-05-23T09:30:00-07:00'
{
start_time: #<DateTime: 2024-05-24T09:00:00-0700>,
end_time: #<DateTime: 2024-05-24T10:30:00-0700>,
},
...
]As a Ruby dev, I want to generate all the datetime blocks of 9:00AM - 10:30AM and 2:00PM - 2:30PM, on Mondays, Wednesdays, and Thursdays, between the dates of May 23, 2024 and June 12, 2024, inclusive. I can do this using the days_of_week parameter. This can be represented visually as:
(image courtesy of Cal.com)
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
days_of_week: %w[mon wed thu],
time_blocks: [
{
start_time: '9:00AM',
end_time: '10:30AM'
},
{
start_time: '2:00PM',
end_time: '2:30PM'
}
],
starting_from: '2024-05-23',
ending_at: '2024-06-12',
)
# returns an array of hashes, each with :start and :end keys
#=>
[
{
start: #<DateTime: 2024-05-23T09:00:00-0700">,
end: #<DateTime: 2024-05-23T22:30:00-0700">,
},
{
start: #<DateTime: 2024-05-23T14:00:00-0700>,
end: #<DateTime: 2024-05-23T14:30:00-0700>,
},
{
start: #<DateTime: 2024-05-27T09:00:00-0700>,
end: #<DateTime: 2024-05-27T22:30:00-0700>
},
...
{
start: #<DateTime: 2024-06-12T14:00:00-0700>,
end: #<DateTime: 2024-06-12T14:30:00-0700>
}
]As a ruby dev, I want to generate the next 3 datetime blocks of 9:00AM - 10:30AM and 2:00PM - 2:30PM on Sundays, after May 23, 2024. I can do this using the limit parameter, instead of ending_at.
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
days_of_week: %w[sun],
time_blocks: [
{
start_time: '9:00AM',
end_time: '10:30PM'
},
{
start_time: '2:00PM',
end_time: '2:30PM'
}
],
starting_from: Date.parse('2024-05-23'), # Can also pass in `Date` object.
limit: 3
)
# =>
[
{
start: #<DateTime: 2024-05-26T09:00:00-0700>,
end: #<DateTime: 2024-05-26T22:30:00-0700>,
},
{
start: #<DateTime: 2024-05-26T14:00:00-0700>,
end: #<DateTime: 2024-05-26T14:30:00-0700>,
},
{
start: #<DateTime: 2024-06-02T09:00:00-0700>,
end: #<DateTime: 2024-06-02T22:30:00-0700>,
},
]As a ruby dev, I want to generate all the timeblocks between May 23, 2024 and June 12, 2024 where the time should be 8AM-9AM on Mondays, but 10:45AM-12:00PM and 2:00PM-4:00PM on Wednesdays, and 2:30PM-4:15PM on Thursdays. I can do this using the day_of_week_time_blocks parameter.
(image courtesy of Cal.com)
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
starting_from: Date.parse('2024-05-23'), # can also pass in Date objects
ending_at: Date.parse('2024-06-12'), # can also pass in Date objects,
day_of_week_time_blocks: {
mon: [
{ start_time: '8:00AM', end_time: '9:00AM' },
],
wed: [
{ start_time: '10:45AM', end_time: '12:00PM' },
{ start_time: '2:00PM', end_time: '4:00PM' },
],
thu: [
{ start_time: '2:30PM', end_time: '4:15PM' }
],
}
)As a Ruby dev, I want to generate the next 3 timeblocks for 8AM - 9AM for the 5th and 10th day of every month starting from June. I can do this using the days_of_month parameter.
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
starting_from: '2024-06-01',
limit: 3,
days_of_month: [5, 10],
time_blocks: [
{ start_time: '8:00AM', end_time: '9:00AM' },
],
)
#=>
[
{
start: #<DateTime: 2024-06-05T08:00:00-0700>,
end: #<DateTime: 2024-06-05T09:00:00-0700>,
},
{
start: #<DateTime: 2024-06-10T08:00:00-0700>,
end: #<DateTime: 2024-06-10T09:00:00-0700>,
},
{
start: #<DateTime: 2024-07-05T08:00:00-0700>,
end: #<DateTime: 2024-07-05T09:00:00-0700>,
},
]Specify nth day-of-week in month (ie. first Monday of the Month, second Tuesday of the Month, last Friday of Month)
As a Ruby dev, I want to generate timeblocks for 8AM - 9AM on the first and second Mondays and last Fridays of every month starting in June 2024. I can do this with the nth_day_of_week_in_month param.
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
starting_from: '2024-06-01',
limit: 5,
nth_day_of_week_in_month: {
mon: [1, 2], # valid values: -1,1,2,3,4,5
fri: [-1], # Use -1 to specify the last Friday of the month.
},
time_blocks: [
{ start_time: '8:00AM', end_time: '9:00AM' },
],
)
# =>
[
{
start: #<DateTime: 2024-06-03T08:00:00-0700>, # First Monday of June 2024
end: #<DateTime: 2024-06-03T09:00:00-0700>,
},
{
start: #<DateTime: 2024-06-10T08:00:00-0700>, # second Monday of June 2024
end: #<DateTime: 2024-06-10T09:00:00-0700>,
},
{
start: #<DateTime: 2024-06-28 08:00:00 -0700>, # last Friday of June 2024
end: #<DateTime: 2024-06-28 09:00:00 -0700>,
},
{
start: #<DateTime: 2024-07-01 08:00:00 -0700>, # First Monday of July 2024
end: #<DateTime: 2024-07-01 09:00:00 -0700>,
},
{
start: #<DateTime: 2024-07-08 08:00:00 -0700>, # Second Monday of July 2024
end: #<DateTime: 2024-07-08 09:00:00 -0700>,
},
]As a Ruby dev, I want to generate timeblocks for 8AM - 9AM on Mondays, except for the Monday of June 10, 2024. I can do this using the exlcusion_dates parameter.
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
starting_from: '2024-06-03',
limit: 4,
exclusion_dates: %w(2024-06-10),
day_of_week_time_blocks: {
mon: [
{ start_time: '8:00AM', end_time: '9:00AM' },
],
}
)
# Returns all Monday 8AM - 9AM blocks except for the Monday on June 10, 2024
# =>
[
{
start: #<DateTime: 2024-06-03T08:00:00-0700>,
end: #<DateTime: 2024-06-03T09:00:00-0700>,
}
{
start: #<DateTime: 2024-06-17T08:00:00-0700>,
end: #<DateTime: 2024-06-17T09:00:00-0700>,
}
{
start: #<DateTime: 2024-06-24T08:00:00-0700>,
end: #<DateTime: 2024-06-24T09:00:00-0700>,
}
{
start: #<DateTime: 2024-07-01T08:00:00-0700>,
end: #<DateTime: 2024-07-01T09:00:00-0700>,
}
]As a Ruby dev, I want to generate timeblocks for 8AM - 9AM, and 10AM - 11AM on Mondays, except for those that conflict (meaning overlap) with the time block of 10:30AM - 11:30AM on the Monday of June 10, 2024. I can skip the conflicting time blocks by using the exclusion_times parameter.
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
starting_from: '2024-06-03',
limit: 4,
days_of_week: %(mon),
time_blocks: [
{ start_time: '8:00AM', end_time: '9:00AM' },
{ start_time: '10:00AM', end_time: '11:00AM' },
],
exclusion_times: [
{
start: '2024-06-10T10:30:00-07:00',
end: '2024-06-10T11:30:00-07:00',
}
],
)
# =>
[
{
start: #<DateTime 2024-06-03T08:00:00-0700>,
end: #<DateTime 2024-06-03T09:00:00-0700>,
},
{
start: #<DateTime 2024-06-03T10:00:00-0700>,
end: #<DateTime 2024-06-03T11:00:00-0700>,
},
{
start: #<DateTime 2024-06-10T08:00:00-0700>,
end: #<DateTime 2024-06-10T09:00:00-0700>,
},
# The June 10 10AM - 11AM was skipped because it overlapped with the June 10 10:30AM - 11:30AM exclusion time.
{
start: #<DateTime 2024-06-17T08:00:00-0700>,
end: #<DateTime 2024-06-17T09:00:00-0700>,
},
{
start: #<DateTime 2024-06-17T10:00:00-0700>,
end: #<DateTime 2024-06-17T11:00:00-0700>,
},
{
start: #<DateTime 2024-06-24T08:00:00-0700>,
end: #<DateTime 2024-06-24T09:00:00-0700>,
},
]As a Ruby dev, I want to generate timeblocks for 9AM- 10AM on every Monday, but every other Tuesday, and every other 3rd Wednesday. I can do this using the days_of_week parameter with the every and every_other_nth keys to specify the every-other-nth-rules.
This can be visualized as:
(image courtesy of calendar.google.com)
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
starting_from: '2024-12-30',
days_of_week: {
mon: { every: true }, # every Monday (no skipping)
tue: { every_other_nth: 2 }, # every other Tuesday starting at first Tuesday from `starting_from` date
wed: { every_other_nth: 3 }, # every 3rd Wednesday starting at first Wednesday from `starting_from` date
},
limit: 10,
time_blocks: [
{ start_time: '9:00AM', end_time: '10:00AM' },
],
)
#=>
[
{
start: #<DateTime: 2024-12-30T09:00:00-0800>,
end: #<DateTime: 2024-12-30T10:00:00-0800>,
},
{
start: #<DateTime: 2024-12-31T09:00:00-0800>,
end: #<DateTime: 2024-12-31T10:00:00-0800>,
},
{
start: #<DateTime: 2025-01-01T09:00:00-0800>,
end: #<DateTime: 2025-01-01T10:00:00-0800>,
},
{
start: #<DateTime: 2025-01-06T09:00:00-0800>,
end: #<DateTime: 2025-01-06T10:00:00-0800>,
},
{
start: #<DateTime: 2025-01-13T09:00:00-0800>,
end: #<DateTime: 2025-01-13T10:00:00-0800>,
},
{
start: #<DateTime: 2025-01-14T09:00:00-0800>,
end: #<DateTime: 2025-01-14T10:00:00-0800>,
},
{
start: #<DateTime: 2025-01-20T09:00:00-0800>,
end: #<DateTime: 2025-01-20T10:00:00-0800>,
},
{
start: #<DateTime: 2025-01-22T09:00:00-0800>,
end: #<DateTime: 2025-01-22T10:00:00-0800>,
},
{
start: #<DateTime: 2025-01-27T09:00:00-0800>,
end: #<DateTime: 2025-01-27T10:00:00-0800>,
},
{
start: #<DateTime: 2025-01-28T09:00:00-0800>,
end: #<DateTime: 2025-01-28T10:00:00-0800>,
}
]Use the duration key, to automatically partition the provided time_blocks into smaller chunks to the given duration.
As a Ruby dev, I want to generate 30 minute time blocks between 9:00AM - 1:00PM, and 2:00PM - 5:00PM. Because it is too tedious to generate all 14 of these time blocks, I prefer to pass in the duration key and have periodoxical generate them for me.
N.B. If you provide a duration that conflicts with your time blocks, periodoxical will not return any time blocks. For example, if you specify 9:00AM - 10:00AM but set your duration as 90 minutes, no time blocks are generated since we can't fit 90 minutes into an hour!
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
time_blocks: [
{
start_time: '9:00AM',
end_time: '1:00PM'
},
{
start_time: '2:00PM',
end_time: '5:00PM'
},
],
duration: 30, #(minutes)
starting_from: '2024-05-23',
ending_at: '2024-05-26',
)
# => [
{
start: #<DateTime: 2024-05-23T09:00:00--0700>
end: #<DateTime: 2024-05-23T09:30:00--0700>
},
{
start: #<DateTime: 2024-05-23T09:30:00--0700>
end: #<DateTime: 2024-05-23T10:00:00--0700>
},
{
start: #<DateTime: 2024-05-23T10:00:00--0700>
end: #<DateTime: 2024-05-23T10:30:00--0700>
},
{
start: #<DateTime: 2024-05-23T10:30:00--0700>
end: #<DateTime: 2024-05-23T11:00:00--0700>
}
]Generate all the Friday the 13ths ever since May 1980 (when the first Friday the 13th film was released).
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
starting_from: '1980-05-01',
days_of_week: %w(fri),
days_of_month: [13],
limit: 100,
time_blocks: [
{ start_time: '11:00PM', end_time: '12:00AM' },
],
)
# =>
[
{
start: #<DateTime: 1980-06-13T23:00:00-0700>,
end: #<DateTime: 1980-06-13T00:00:00-0700>,
},
{
start: #<DateTime: 1981-02-13T23:00:00-0800>,
end: #<DateTime: 1981-02-13T00:00:00-0800>,
},
{
start: #<DateTime: 1981-03-13T23:00:00-0800>,
end: #<DateTime: 1981-03-13T00:00:00-0800>,
},
{
start: #<DateTime: 1981-11-13T23:00:00-0800>,
end: #<DateTime: 1981-11-13T00:00:00-0800>,
}
...
]Generate the next 10 Thanksgivings from now on (Thanksgivings is defined as the 4th Thursday in November).
Periodoxical.generate(
time_zone: 'America/Los_Angeles',
starting_from: '2024-05-01',
months: [11],
nth_day_of_week_in_month: {
thu: [4],
},
limit: 10,
time_blocks: [
{ start_time: '5:00PM', end_time: '6:00PM' },
],
)
#=>
[
{
start: #<DateTime: 2024-11-28T17:00:00-0800>,
end: #<DateTime: 2024-11-28T18:00:00-0800>,
},
{
start: #<DateTime: 2025-11-27T17:00:00-0800>,
end: #<DateTime: 2025-11-27T18:00:00-0800>,
},
{
start: #<DateTime: 2026-11-26T17:00:00-0800>,
end: #<DateTime: 2026-11-26T18:00:00-0800>,
},
{
start: #<DateTime: 2027-11-25T17:00:00-0800>,
end: #<DateTime: 2027-11-25T18:00:00-0800>,
},
{
start: #<DateTime: 2028-11-23T17:00:00-0800>,
end: #<DateTime: 2028-11-23T18:00:00-0800>,
},
...
]After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/periodoxical. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Periodoxical project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.