The scheduling toolkit for Ruby.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib
spec
.gitignore
.rspec
.rubocop.yml
.travis.yml
CHANGELOG.md
Gemfile
LICENSE.txt
README.md
Rakefile
artic.gemspec

README.md

A.R.TI.C.

Build Status Maintainability Coverage Status

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.