README.md
# A.R.TI.C.
[](https://travis-ci.org/aldesantis/artic)
[](https://codeclimate.com/github/aldesantis/artic/maintainability)
[](https://coveralls.io/github/aldesantis/artic?branch=master)
**A** **R**uby gem for **TI**me **C**omputations.
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:
```ruby
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:
```ruby
calendar = Artic::Calendar.new
```
### Setting available times
Now you can start defining the free slots in your calendar:
```ruby
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:
```ruby
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:
```ruby
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:
```ruby
calendar.occupations << Artic::Occupation.new(Date.parse('2016-09-26'), '10:00'..'12:00'))
```
The times do not have to respect your availability slots:
```ruby
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:
```ruby
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:
```ruby
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](https://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](http://opensource.org/licenses/MIT).