Extends calendarium-romanum with a new class
It is (only exception being the constructor) API-compatible
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
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
calendarium-romanum, and there is a regularly updated instance
of calendar API out there.
In all these cases it is convenient to use
instead of building a regular
Calendar in your application.
require 'calendarium-romanum' require 'calendarium-romanum/remote'
or by a shortcut
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
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 it's 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
freely choose between GNU/LGPL 3 and MIT