calendarium-romanum-remote

Extends calendarium-romanum with a new class CalendariumRomanum::Remote::Calendar. It is (only exception being the constructor) API-compatible with CalendariumRomanum::Calendar, but obtains the data from a remote calendar API instead of computing them.

What it is good for

There are cases when you can't - or don't want to - setup a CalendariumRomanum::Calendar yourself. Maybe you don't have all the necessary data, but there is a calendar API instance which has them. Maybe you always want to have the most accurate and up-to-date data, but you don't want to watch for fixes and updates to calendarium-romanum, and there is a regularly updated instance of calendar API out there. In all these cases it is convenient to use calendarium-romanum-remote instead of building a regular Calendar in your application.

Usage

Load by

require 'calendarium-romanum'
require 'calendarium-romanum/remote'

or by a shortcut

require 'calendarium-romanum-remote'

CR = CalendariumRomanum

# create by specifying a year and remote calendar URI
calendar = CR::Remote::Calendar.new(2016, 'http://calapi.inadiutorium.cz/api/v0/en/calendars/general-la/')

# use the same way as the normal Calendar, get the same return values
day = calendar.day Date.new(2016, 12, 24)

As most abstractions, also the one of Remote::Calendar is leaky: a whole bunch of errors specific to the network communication taking place in the background can occur.

CR = CalendariumRomanum

calendar = CR::Remote::Calendar.new(2016, 'http://calapi.inadiutorium.cz/api/v0/en/calendars/general-la/')

begin
  day = calendar.day Date.new(2016, 12, 24)
rescue CR::Remote::UnexpectedResponseError
  # the server responded with some "unhappy" HTTP status code
rescue CR::Remote::InvalidDataError => err
  # data returned by the server were not understood
rescue HTTPI::Error
  # parent class of lower-level network errors raised by HTTPI -
  # see its documentation or source for the specific exception
  # classes
end

Important implementation details

Under the hood HTTPi is used to issue HTTP requests and multi_json for JSON deserialization. Both gems provide uniform public interfaces while allowing you to choose among several implementations. calendarium-romanum-remote deliberately does not make any choice concerning the implementations and leaves this up to you. There are sensible defaults working out of the box, but it's advisable to check both gems' documentation to see what options you have and how to make use of them.

The following example configures curb to be used internally as HTTP client and oj as JSON deserializer.

require 'curb'
require 'oj'
require 'calendarium-romanum-remote'

HTTPI.adapter = :curb
MultiJson.adapter = :oj

License

freely choose between GNU/LGPL 3 and MIT