A.R.TI.C.

A Ruby gem for TIme Computations.

A.R.TI.C. can take questions like:

If I'm available 9am-5pm on Mondays and I have a meeting from 10am to 1pm and another from 3pm to 4pm next Monday, when am I free next Monday?

And give you an answer like:

You are free in these time slots:

• 9am-10am;
• 1pm-3pm;
• 4pm-5pm.

Installation

Add this line to your application's Gemfile:

gem 'artic'

And then execute:

$ bundle

Or install it yourself as:

$ gem install artic

Usage

First of all, you will need to create a new calendar:

calendar = Artic::Calendar.new

Setting available times

Now you can start defining the free slots in your calendar:

calendar.availabilities << Artic::Availability.new(:monday, '09:00'..'11:00')
calendar.availabilities << Artic::Availability.new(:monday, '11:00'..'13:00')
calendar.availabilities << Artic::Availability.new(:monday, '15:00'..'19:00')

If you want, you can also use specific dates in place of days of the week:

calendar.availabilities << Artic::Availability.new(Date.parse('2016-10-03'), '15:00'..'19:00')

Or you can mix the two! In this case, we won't consider the availability slots for that day of the week when calculating availabilities:

calendar.availabilities << Artic::Availability.new(:monday, '09:00'..'17:00')

# Only available 15-19 on Monday, October 3rd 2016.
calendar.availabilities << Artic::Availability.new(Date.parse('2016-10-03'), '15:00'..'19:00')

Defining occupations

You can also define some specific slots when you will be busy with something:

calendar.occupations << Artic::Occupation.new(Date.parse('2016-09-26'), '10:00'..'12:00'))

The times do not have to respect your availability slots:

calendar.occupations << Artic::Occupation.new(Date.parse('2016-09-26'), '18:00'..'20:00'))

Computing available slots

This is where the fun part begins. Suppose you want to get your work hours on Mondays:

calendar.available_slots_on(:monday)
# => Artic::Collection::AvailabilityCollection[
#   Artic::Availability<:monday, 09:00..13:00>,
#   Artic::Availability<:monday, 15:00..19:00>
# ]

# We overrode this, remember?
calendar.available_slots_on(Date.parse('2016-10-03'))
# => Artic::Collection::AvailabilityCollection[
#   Artic::Availability<2016-10-03 15:00..10:00>
# ]

Computing free slots

Or maybe you want to see when you have time for a meeting a particular Monday?

In that case, use #free_slots_on and we'll take care of removing any occupied times from your available slots:

calendar.free_slots_on(Date.parse('2016-09-26'))
# => Artic::Collection::AvailabilityCollection[
#   Artic::Availability<2016-09-26 09:00..13:00>,
#   Artic::Availability<2016-09-26 15:00..18:00>
# ]

Caveats

• All times should be in the same timezone (ideally, UTC).

Development

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/aldesantis/artic.

License

The gem is available as open source under the terms of the MIT License.