Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update and clarify readme
Browse files Browse the repository at this point in the history
JoeSouthan committed May 5, 2020
1 parent 6d63112 commit 53150bb
Showing 1 changed file with 51 additions and 37 deletions.
88 changes: 51 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
@@ -5,28 +5,30 @@

Date calculations based on business calendars.

## Documentation
- [Getting Started](#getting-started)
- [Creating a calendar](#creating-a-calendar)
- [Using a calendar file](#use-a-calendar-file)
- [🚨 v2.0.0 breaking changes 🚨](#v200-breaking-changes)
- [Checking for business days](#checking-for-business-days)
- [Business day arithmetic](#business-day-arithmetic)
- [But other libraries already do this](#but-other-libraries-already-do-this)
- [License & Contributing](#license--contributing)

To get business, simply:
## Getting started

To install business, simply:

```bash
$ gem install business
gem install business
```

## Important: 2.0.0 breaking changes

We have removed the bundled calendars as of version 2.0.0, if you need the calendars that were included:

Download the calendars you wish to use from [before version 2](https://github.com/gocardless/business/tree/b12c186ca6fd4ffdac85175742ff7e4d0a705ef4/lib/business/data) and place them in a suitable place in your project.

Then, add the directory to where you placed the yml files before you load the calendar:
If you are using a Gemfile:

```ruby
Calendar::Business.load_paths("lib/calendars") # your_project/lib/calendars/ contains bacs.yml
Calendar::Business.load("bacs")
gem "business", "~> 2.0"
```

### Getting started
### Creating a calendar

Get started with business by creating an instance of the calendar class, passing in a hash that specifies with days of the week are considered working days, and which days are holidays.

@@ -38,21 +40,20 @@ calendar = Business::Calendar.new(
)
```

### Load a calendar from a file

#### Calendar file definition
### Use a calendar file

Defining a calendar as a Ruby object may not be convient, to load it from a YAML file follow and customise the example below. All keys are optional and will default to the following:
Defining a calendar as a Ruby object may not be convenient, so we provide a way of defining these calendars as YAML. Below we will walk through the necessary [steps](#example) to build your first calendar. All keys are optional and will default to the following:

- If `working_days` is missing, then common default is used (mon-fri).
- If `holidays` is missing, "no holidays" assumed.
- If `extra_working_dates` is missing, then no changes in `working_days` will happen.

> Note: Elements of `holidays` and `extra_working_dates` may be eiter strings that `Date.parse()` can understand, or YYYY-MM-DD (which is considered as a Date by Ruby YAML itself).
> Note: Elements of `holidays` and `extra_working_dates` may be either strings that `Date.parse()` can understand, or YYYY-MM-DD (which is considered as a Date by Ruby YAML itself).
#### Example

```yaml
# lib/calendars/my_calendar.yml
working_days:
- Monday
- Wednesday
@@ -64,37 +65,47 @@ extra_working_dates:
- 9th March 2020 # A Saturday
```
#### Using the calendar
Ensure the calendar file is saved to a directory that will hold all your calendars, eg; `path/to/your/calendar/directory` then add this directory to your code before you call your calendar:
Ensure the calendar file is saved to a directory that will hold all your calendars, eg; `lib/calendars` then add this directory to `load_paths` before you call your calendar. `load_paths` can also accept an array of hashes, keyed with the calendar's name.

```ruby
Business::Calendar.load_paths = ["path/to/your/calendar/directory"]
Business::Calendar.load_paths = [
"lib/calendars",
{ "foo_calendar" => { "working_days" => ["monday"] } },
]
```

Now you can load the calendar by calling the `load` class method on `Business::Calendar`. The
`load_cached` variant of this method caches the calendars by name after loading them, to avoid reading and parsing the config file multiple times.
Now you can load the calendar by calling the `Business::Calendar.load(calendar_name)`. The
`Business::Calendar.load_cached(calendar_name)` variant of this method caches the calendars by name after loading them, to avoid reading and parsing the config file multiple times.

```ruby
calendar = Business::Calendar.load("my_calendars")
calendar = Business::Calendar.load("my_calendar") # lib/calendars/my_calendar.yml
calendar = Business::Calendar.load("foo_calendar")
# or
calendar = Business::Calendar.load_cached("my_calendars")
calendar = Business::Calendar.load_cached("my_calendar")
calendar = Business::Calendar.load_cached("foo_calendar")
```

#### New in version 2.0.0:
## v2.0.0 breaking changes

We have removed the bundled calendars as of version 2.0.0, if you need the calendars that were included:

Add a hash to the `load_path` array to use already loaded data. This can be useful if loading calendar data from an external source.
- Download the calendars you wish to use from [before version 2](https://github.com/gocardless/business/tree/b12c186ca6fd4ffdac85175742ff7e4d0a705ef4/lib/business/data)
- Place them in a suitable place in your project, eg: `lib/calendars`
- Add the directory to where you placed the yml files before you load the calendar

```ruby
Business::Calendar.load_paths = [
"path/to/your/calendar/directory",
{ "foo_calendar" => { "working_days" => ["monday"] } }
]
Calendar::Business.load_paths("lib/calendars") # your_project/lib/calendars/ contains bacs.yml
Calendar::Business.load("bacs")
```

Business::Calendar.load("foo_calendar")
If you wish to stay on the last version that contained bundled calendars, pin `business` to `v1.18.0`

```ruby
# Gemfile
gem "business", "v1.18.0"
```

### Checking for business days
## Checking for business days

To check whether a given date is a business day (falls on one of the specified working days or working dates, and is not a holiday), use the `business_day?` method on `Business::Calendar`.

@@ -105,7 +116,7 @@ calendar.business_day?(Date.parse("Sunday, 8 June 2014"))
# => false
```

### Business day arithmetic
## Business day arithmetic

The `add_business_days` and `subtract_business_days` are used to perform business day arithmetic on dates.

@@ -144,7 +155,10 @@ essential for us. Business provides a simple `Calendar` class, that is initializ

Secondly, business_time supports calculations on times as well as dates. For our purposes, date-based calculations are sufficient. Supporting time-based calculations as well makes the code significantly more complex. We chose to avoid this extra complexity by sticking solely to date-based mathematics.

---
<div style="text-align: center;"><img src="http://3.bp.blogspot.com/-aq4iOz2OZzs/Ty8xaQwMhtI/AAAAAAAABrM/-vn4tcRA9-4/s1600/daily-morning-awesomeness-243.jpeg" alt="I'm late for business" width="250"/></div>

## License & Contributing
- business is available as open source under the terms of the [MIT License](LICENSE).
- Bug reports and pull requests are welcome on GitHub at https://github.com/gocardless/business.

![I'm late for business](http://3.bp.blogspot.com/-aq4iOz2OZzs/Ty8xaQwMhtI/AAAAAAAABrM/-vn4tcRA9-4/s1600/daily-morning-awesomeness-243.jpeg)
GoCardless ♥ open source. If you do too, come [join us](https://gocardless.com/about/jobs).

0 comments on commit 53150bb

Please sign in to comment.