calendarium-romanum 0.3.0 → 0.7.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/.gitignore +4 -0
- data/.rspec +2 -0
- data/.rubocop.yml +47 -0
- data/.travis.yml +20 -0
- data/.yardopts +3 -0
- data/CHANGELOG.md +340 -0
- data/Gemfile +25 -0
- data/Gemfile.lock +86 -0
- data/README.md +515 -0
- data/Rakefile +9 -0
- data/bin/calendariumrom +4 -1
- data/calendarium-romanum.gemspec +26 -0
- data/config/locales/cs.yml +17 -1
- data/config/locales/en.yml +28 -14
- data/config/locales/es.yml +90 -0
- data/config/locales/fr.yml +90 -0
- data/config/locales/it.yml +18 -2
- data/config/locales/la.yml +17 -1
- data/data/README.md +43 -1
- data/data/czech-brno-cs.txt +4 -6
- data/data/czech-budejovice-cs.txt +4 -6
- data/data/czech-cechy-cs.txt +4 -5
- data/data/czech-cs.txt +237 -234
- data/data/czech-hradec-cs.txt +3 -5
- data/data/czech-litomerice-cs.txt +5 -7
- data/data/czech-morava-cs.txt +4 -5
- data/data/czech-olomouc-cs.txt +2 -4
- data/data/czech-ostrava-cs.txt +3 -5
- data/data/czech-plzen-cs.txt +3 -5
- data/data/czech-praha-cs.txt +3 -4
- data/data/universal-en.txt +214 -211
- data/data/universal-es.txt +243 -0
- data/data/universal-fr.txt +243 -0
- data/data/universal-it.txt +214 -211
- data/data/universal-la.txt +214 -210
- data/doc/data_readme.md +2 -0
- data/doc/images/class_diagram.png +0 -0
- data/doc/images/class_diagram.puml +44 -0
- data/doc/yard_readme.rdoc +76 -0
- data/lib/calendarium-romanum.rb +30 -21
- data/lib/calendarium-romanum/abstract_date.rb +12 -0
- data/lib/calendarium-romanum/calendar.rb +207 -52
- data/lib/calendarium-romanum/cli.rb +101 -52
- data/lib/calendarium-romanum/cr.rb +16 -0
- data/lib/calendarium-romanum/data.rb +46 -18
- data/lib/calendarium-romanum/day.rb +202 -20
- data/lib/calendarium-romanum/enum.rb +24 -5
- data/lib/calendarium-romanum/enums.rb +102 -36
- data/lib/calendarium-romanum/errors.rb +4 -0
- data/lib/calendarium-romanum/ordinalizer.rb +30 -6
- data/lib/calendarium-romanum/perpetual_calendar.rb +97 -0
- data/lib/calendarium-romanum/rank.rb +43 -6
- data/lib/calendarium-romanum/sanctorale.rb +170 -24
- data/lib/calendarium-romanum/sanctorale_factory.rb +74 -3
- data/lib/calendarium-romanum/sanctorale_loader.rb +176 -0
- data/lib/calendarium-romanum/temporale.rb +251 -119
- data/lib/calendarium-romanum/temporale/celebration_factory.rb +106 -0
- data/lib/calendarium-romanum/temporale/dates.rb +117 -36
- data/lib/calendarium-romanum/temporale/extensions/christ_eternal_priest.rb +18 -6
- data/lib/calendarium-romanum/transfers.rb +20 -1
- data/lib/calendarium-romanum/util.rb +36 -3
- data/lib/calendarium-romanum/version.rb +5 -1
- metadata +29 -21
- data/lib/calendarium-romanum/sanctoraleloader.rb +0 -115
- data/spec/abstract_date_spec.rb +0 -62
- data/spec/calendar_spec.rb +0 -352
- data/spec/cli_spec.rb +0 -26
- data/spec/data_spec.rb +0 -23
- data/spec/date_spec.rb +0 -61
- data/spec/dates_spec.rb +0 -45
- data/spec/enum_spec.rb +0 -51
- data/spec/i18n_spec.rb +0 -59
- data/spec/rank_spec.rb +0 -42
- data/spec/readme_spec.rb +0 -52
- data/spec/sanctorale_factory_spec.rb +0 -42
- data/spec/sanctorale_spec.rb +0 -167
- data/spec/sanctoraleloader_spec.rb +0 -171
- data/spec/spec_helper.rb +0 -35
- data/spec/temporale_spec.rb +0 -500
data/Gemfile.lock
ADDED
@@ -0,0 +1,86 @@
|
|
1
|
+
GEM
|
2
|
+
remote: https://rubygems.org/
|
3
|
+
specs:
|
4
|
+
aruba (0.8.1)
|
5
|
+
childprocess (~> 0.5.6)
|
6
|
+
contracts (~> 0.9)
|
7
|
+
cucumber (>= 1.3.19)
|
8
|
+
rspec-expectations (>= 2.99)
|
9
|
+
ast (2.3.0)
|
10
|
+
backports (3.18.1)
|
11
|
+
builder (3.2.3)
|
12
|
+
childprocess (0.5.9)
|
13
|
+
ffi (~> 1.0, >= 1.0.11)
|
14
|
+
contracts (0.16.0)
|
15
|
+
cucumber (2.99.0)
|
16
|
+
builder (>= 2.1.2)
|
17
|
+
cucumber-core (~> 1.5.0)
|
18
|
+
cucumber-wire (~> 0.0.1)
|
19
|
+
diff-lcs (>= 1.1.3)
|
20
|
+
gherkin (~> 4.0)
|
21
|
+
multi_json (>= 1.7.5, < 2.0)
|
22
|
+
multi_test (>= 0.1.2)
|
23
|
+
cucumber-core (1.5.0)
|
24
|
+
gherkin (~> 4.0)
|
25
|
+
cucumber-wire (0.0.1)
|
26
|
+
diff-lcs (1.3)
|
27
|
+
docile (1.1.5)
|
28
|
+
ffi (1.9.18)
|
29
|
+
gherkin (4.1.3)
|
30
|
+
i18n (0.6.9)
|
31
|
+
json (2.0.2)
|
32
|
+
multi_json (1.12.2)
|
33
|
+
multi_test (0.1.2)
|
34
|
+
parser (2.4.0.0)
|
35
|
+
ast (~> 2.2)
|
36
|
+
powerpack (0.1.1)
|
37
|
+
rainbow (2.1.0)
|
38
|
+
rake (12.0.0)
|
39
|
+
roman-numerals (0.3.0)
|
40
|
+
rspec (3.7.0)
|
41
|
+
rspec-core (~> 3.7.0)
|
42
|
+
rspec-expectations (~> 3.7.0)
|
43
|
+
rspec-mocks (~> 3.7.0)
|
44
|
+
rspec-core (3.7.0)
|
45
|
+
rspec-support (~> 3.7.0)
|
46
|
+
rspec-expectations (3.7.0)
|
47
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
48
|
+
rspec-support (~> 3.7.0)
|
49
|
+
rspec-mocks (3.7.0)
|
50
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
51
|
+
rspec-support (~> 3.7.0)
|
52
|
+
rspec-support (3.7.0)
|
53
|
+
rubocop (0.46.0)
|
54
|
+
parser (>= 2.3.1.1, < 3.0)
|
55
|
+
powerpack (~> 0.1)
|
56
|
+
rainbow (>= 1.99.1, < 3.0)
|
57
|
+
ruby-progressbar (~> 1.7)
|
58
|
+
unicode-display_width (~> 1.0, >= 1.0.1)
|
59
|
+
ruby-progressbar (1.8.1)
|
60
|
+
simplecov (0.12.0)
|
61
|
+
docile (~> 1.1.0)
|
62
|
+
json (>= 1.8, < 3)
|
63
|
+
simplecov-html (~> 0.10.0)
|
64
|
+
simplecov-html (0.10.0)
|
65
|
+
thor (0.18.1)
|
66
|
+
unicode-display_width (1.1.2)
|
67
|
+
yard (0.9.16)
|
68
|
+
|
69
|
+
PLATFORMS
|
70
|
+
ruby
|
71
|
+
|
72
|
+
DEPENDENCIES
|
73
|
+
aruba
|
74
|
+
backports (~> 3.18)
|
75
|
+
cucumber (~> 2.99)
|
76
|
+
i18n
|
77
|
+
rake
|
78
|
+
roman-numerals
|
79
|
+
rspec
|
80
|
+
rubocop
|
81
|
+
simplecov
|
82
|
+
thor
|
83
|
+
yard
|
84
|
+
|
85
|
+
BUNDLED WITH
|
86
|
+
1.16.6
|
data/README.md
ADDED
@@ -0,0 +1,515 @@
|
|
1
|
+
# calendarium-romanum
|
2
|
+
|
3
|
+
[![Build Status](https://travis-ci.org/igneus/calendarium-romanum.svg?branch=master)](https://travis-ci.org/igneus/calendarium-romanum)
|
4
|
+
[![Gem Version](https://badge.fury.io/rb/calendarium-romanum.svg)](https://badge.fury.io/rb/calendarium-romanum)
|
5
|
+
|
6
|
+
API documentation:
|
7
|
+
[master](http://www.rubydoc.info/github/igneus/calendarium-romanum/master)
|
8
|
+
[0.7.0](http://www.rubydoc.info/gems/calendarium-romanum/0.7.0)
|
9
|
+
[0.6.0](http://www.rubydoc.info/gems/calendarium-romanum/0.6.0)
|
10
|
+
[0.5.0](http://www.rubydoc.info/gems/calendarium-romanum/0.5.0)
|
11
|
+
[0.4.0](http://www.rubydoc.info/gems/calendarium-romanum/0.4.0)
|
12
|
+
[0.3.0](http://www.rubydoc.info/gems/calendarium-romanum/0.3.0)
|
13
|
+
[0.2.0](http://www.rubydoc.info/gems/calendarium-romanum/0.2.0)
|
14
|
+
|
15
|
+
Ruby gem for
|
16
|
+
calendar computations according to the Roman Catholic liturgical
|
17
|
+
calendar as instituted by
|
18
|
+
[MP Mysterii Paschalis](http://w2.vatican.va/content/paul-vi/en/motu_proprio/documents/hf_p-vi_motu-proprio_19690214_mysterii-paschalis.html) of Paul VI. (AAS 61 (1969), pp. 222-226).
|
19
|
+
The rules are defined in
|
20
|
+
*General Norms for the Liturgical Year and the Calendar*
|
21
|
+
([English translation][gnlyc]).
|
22
|
+
|
23
|
+
calendarium-romanum aspires to become the most complete
|
24
|
+
FOSS implementation of this calendar system
|
25
|
+
(see [list of implementations available][awesomecc]).
|
26
|
+
|
27
|
+
## Features
|
28
|
+
|
29
|
+
- [x] liturgical season
|
30
|
+
- [x] Sundays, temporale feasts
|
31
|
+
- [x] sanctorale calendars: data format, example data files, their loading
|
32
|
+
- [x] resolution of precedence of concurrent celebrations
|
33
|
+
- [x] octave days
|
34
|
+
- [x] commemorations in the privileged seasons where memorials are suppressed
|
35
|
+
- [x] transfer of suppressed solemnities
|
36
|
+
- [x] optional transfer of important solemnities to a Sunday
|
37
|
+
- [x] additional temporale feasts (Christ the Eternal Priest and similar)
|
38
|
+
|
39
|
+
## Credits
|
40
|
+
|
41
|
+
includes computation of the Easter date from the
|
42
|
+
[easter](https://github.com/jrobertson/easter) gem
|
43
|
+
by James Robertson.
|
44
|
+
|
45
|
+
See also changelog for list of contributions and their authors.
|
46
|
+
|
47
|
+
## License
|
48
|
+
|
49
|
+
freely choose between GNU/LGPL 3 and MIT
|
50
|
+
|
51
|
+
## Project status, Backward compatibility
|
52
|
+
|
53
|
+
The gem's public interface still evolves and each minor release
|
54
|
+
contains several breaking changes. There is no backward compatibility
|
55
|
+
between minor versions.
|
56
|
+
This will continue until release of v1.0.0.
|
57
|
+
|
58
|
+
When using the gem in your projects, it is recommended to lock
|
59
|
+
the dependency to a particular minor version.
|
60
|
+
|
61
|
+
In your app's Gemfile
|
62
|
+
|
63
|
+
```
|
64
|
+
gem 'calendarium-romanum', '~>0.6.0'
|
65
|
+
```
|
66
|
+
|
67
|
+
or in gemspec of your gem
|
68
|
+
|
69
|
+
```
|
70
|
+
spec.add_dependency 'calendarium-romanum', '~>0.6.0'
|
71
|
+
```
|
72
|
+
|
73
|
+
## Usage
|
74
|
+
|
75
|
+
All the examples below expect that you first required the gem:
|
76
|
+
|
77
|
+
```ruby
|
78
|
+
require 'calendarium-romanum'
|
79
|
+
```
|
80
|
+
|
81
|
+
### 1. Typical usage
|
82
|
+
|
83
|
+
The easiest way to obtain calendar entry of a liturgical day:
|
84
|
+
|
85
|
+
```ruby
|
86
|
+
I18n.locale = :en # set locale
|
87
|
+
|
88
|
+
# build calendar
|
89
|
+
pcal = CalendariumRomanum::PerpetualCalendar.new(
|
90
|
+
sanctorale: CalendariumRomanum::Data::GENERAL_ROMAN_ENGLISH.load
|
91
|
+
)
|
92
|
+
|
93
|
+
# query
|
94
|
+
day = pcal[Date.new(2000, 1, 1)]
|
95
|
+
```
|
96
|
+
|
97
|
+
For explanation see the detailed steps below.
|
98
|
+
|
99
|
+
### 2. What liturgical day is it today?
|
100
|
+
|
101
|
+
`PerpetualCalendar` used in the example above is a high-level API.
|
102
|
+
In order to understand what's happening under the hood, we will
|
103
|
+
now take a lower-level approach and work on the level of a simple
|
104
|
+
`Calendar`.
|
105
|
+
Each `Calendar` instance describes a particular *liturgical year*.
|
106
|
+
We may not know which liturgical year our day of interest
|
107
|
+
belongs to, but fortunately there is "alternative constructor"
|
108
|
+
`Calendar.for_day()` to rescue:
|
109
|
+
|
110
|
+
```ruby
|
111
|
+
date = Date.new(2016, 8, 19)
|
112
|
+
calendar = CalendariumRomanum::Calendar.for_day(date)
|
113
|
+
day = calendar[date]
|
114
|
+
|
115
|
+
day.season # => #<CalendariumRomanum::Season:0x00000001d4cfa0 @symbol=:ordinary, @colour=#<CalendariumRomanum::Colour:0x00000001d4d928 @symbol=:green, @i18n_key="colour.green">, @i18n_key="temporale.season.ordinary">
|
116
|
+
day.season.equal? CalendariumRomanum::Seasons::ORDINARY # => true
|
117
|
+
|
118
|
+
day.celebrations
|
119
|
+
# => [#<CalendariumRomanum::Celebration:0x00000001c69cc8 @title="Friday, 20th week in Ordinary Time", @rank=#<CalendariumRomanum::Rank:0x00000001d4c708 @priority=3.13, @desc="rank.3_13", @short_desc="rank.short.ferial">, @colour=#<CalendariumRomanum::Colour:0x00000001d4d928 @symbol=:green, @i18n_key="colour.green">, @symbol=nil>]
|
120
|
+
c = day.celebrations.first
|
121
|
+
c.title # => "Friday, 20th week in Ordinary Time"
|
122
|
+
c.rank # => #<CalendariumRomanum::Rank:0x00000001d4c708 @priority=3.13, @desc="rank.3_13", @short_desc="rank.short.ferial">
|
123
|
+
c.rank.equal? CalendariumRomanum::Ranks::FERIAL # => true
|
124
|
+
c.rank < CalendariumRomanum::Ranks::MEMORIAL_PROPER # => true
|
125
|
+
c.colour
|
126
|
+
# => #<CalendariumRomanum::Colour:0x00000001d4d928 @symbol=:green, @i18n_key="colour.green">
|
127
|
+
```
|
128
|
+
|
129
|
+
`Calendar#[]` returns a single `Day`, describing a liturgical day.
|
130
|
+
Each day belongs to some `#season`; every day, we can choose from
|
131
|
+
one or more `#celebrations` to celebrate.
|
132
|
+
(The only case with multiple choices is combination of a ferial
|
133
|
+
with one or more optional memorials; higher-ranking celebrations
|
134
|
+
are always exclusive.)
|
135
|
+
|
136
|
+
Each `Celebration` is described by a `#title`, `#rank` and `#colour`.
|
137
|
+
|
138
|
+
### 3. But does it take feasts of saints in account?
|
139
|
+
|
140
|
+
Actually, no. Not yet. We need to load some calendar data first:
|
141
|
+
|
142
|
+
```ruby
|
143
|
+
CR = CalendariumRomanum
|
144
|
+
loader = CR::SanctoraleLoader.new
|
145
|
+
sanctorale = loader.load_from_file 'data/universal-en.txt' # insert path to your data file
|
146
|
+
date = Date.new(2016, 8, 19)
|
147
|
+
calendar = CR::Calendar.for_day(date, sanctorale)
|
148
|
+
day = calendar[date]
|
149
|
+
day.celebrations # => [#<CalendariumRomanum::Celebration:0x000000027d9590 @title="Friday, 20th week in Ordinary Time", @rank=#<CalendariumRomanum::Rank:0x000000029e1108 @priority=3.13, ... >, @colour=#<CalendariumRomanum::Colour:0x000000029e1f68 @symbol=:green>>, #<CalendariumRomanum::Celebration:0x000000029c96c0 @title="Saint John Eudes, priest", @rank=#<CalendariumRomanum::Rank:0x000000029e1180 @priority=3.12, ... >, @colour=#<CalendariumRomanum::Colour:0x000000029e1f18 @symbol=:white>>]
|
150
|
+
```
|
151
|
+
|
152
|
+
Unless a sanctorale is loaded, `Calendar` only counts with
|
153
|
+
temporale feasts, Sundays and ferials.
|
154
|
+
|
155
|
+
Note how we saved some typing by defining new constant `CR`
|
156
|
+
referencing the `CalendariumRomanum` module.
|
157
|
+
In fact you can save even more typing by replacing
|
158
|
+
`require 'calendarium-romanum'`
|
159
|
+
by
|
160
|
+
`require 'calendarium-romanum/cr'`
|
161
|
+
which loads the gem *and* defines the `CR` shortcut for you.
|
162
|
+
Following examples expect the `CR` constant to be defined
|
163
|
+
and reference the `CalendariumRomanum` module.
|
164
|
+
|
165
|
+
### 4. Isn't there an easier way to get sanctorale data?
|
166
|
+
|
167
|
+
Yes! There are a few data files bundled in the gem.
|
168
|
+
You can explore them by iterating over `CalendariumRomanum::Data.all`.
|
169
|
+
The more interesting ones are additionally identified by their proper
|
170
|
+
constants, e.g. `CalendariumRomanum::Data::GENERAL_ROMAN_ENGLISH`.
|
171
|
+
Bundled data files can be loaded by a handy shortcut method `#load`:
|
172
|
+
|
173
|
+
```ruby
|
174
|
+
sanctorale = CR::Data::GENERAL_ROMAN_ENGLISH.load # easy loading
|
175
|
+
date = Date.new(2016, 8, 19)
|
176
|
+
calendar = CR::Calendar.for_day(date, sanctorale)
|
177
|
+
day = calendar[date]
|
178
|
+
```
|
179
|
+
|
180
|
+
### 5. I don't want to care about (liturgical) years
|
181
|
+
|
182
|
+
Each Calendar instance is bound to a particular *liturgical* year.
|
183
|
+
Calling `Calendar#[]` with a date out of the year's range
|
184
|
+
results in a `RangeError`:
|
185
|
+
|
186
|
+
```ruby
|
187
|
+
calendar = CR::Calendar.new(2000)
|
188
|
+
begin
|
189
|
+
day = calendar[Date.new(2000, 1, 1)]
|
190
|
+
rescue RangeError
|
191
|
+
STDERR.puts 'ouch' # will happen
|
192
|
+
end
|
193
|
+
```
|
194
|
+
|
195
|
+
The example demonstrates the well known fact,
|
196
|
+
that the **civil and liturgical year don't match:**
|
197
|
+
1st January 2000
|
198
|
+
does not belong to the liturgical year 2000-2001
|
199
|
+
(which will begin on the first Sunday of Advent,
|
200
|
+
i.e. on 3rd December 2000), but to the year 1999-2000.
|
201
|
+
For the sake of simplicity, `calendarium-romanum` denotes
|
202
|
+
liturgical years by the starting year only, so you create
|
203
|
+
a `Calendar` for liturgical year 1999-2000 by calling
|
204
|
+
`Calendar.new(1999)`.
|
205
|
+
|
206
|
+
We have already seen `Calendar.for_day()`, which takes care
|
207
|
+
for finding the liturgical year a particular date belongs to
|
208
|
+
and creating a `Calendar` for this year.
|
209
|
+
But maybe you want to query a calendar without caring about liturgical
|
210
|
+
years altogether, possibly picking days across multiple years.
|
211
|
+
The best tool for such use cases is `PerpetualCalendar`.
|
212
|
+
|
213
|
+
```ruby
|
214
|
+
pcal = CR::PerpetualCalendar.new
|
215
|
+
|
216
|
+
# get days
|
217
|
+
d1 = pcal[Date.new(2000, 1, 1)]
|
218
|
+
d2 = pcal[Date.new(2100, 1, 1)]
|
219
|
+
d3 = pcal[Date.new(1970, 1, 1)]
|
220
|
+
|
221
|
+
# get Calendar instances if you need them
|
222
|
+
calendar = pcal.calendar_for_year(1987)
|
223
|
+
```
|
224
|
+
|
225
|
+
Just like `Calendar` with the default settings (no sanctorale data
|
226
|
+
etc.) is usually of little use, so is a `PerpetualCalendar`
|
227
|
+
creating such `Calendar`s. Of course it is possible to specify
|
228
|
+
configuration which is then applied on the `Calendar`s
|
229
|
+
being created:
|
230
|
+
|
231
|
+
```ruby
|
232
|
+
pcal = CR::PerpetualCalendar.new(
|
233
|
+
# Sanctorale instance
|
234
|
+
sanctorale: CR::Data::GENERAL_ROMAN_ENGLISH.load,
|
235
|
+
# options that will be passed to Temporale.new
|
236
|
+
temporale_options: {
|
237
|
+
transfer_to_sunday: [:epiphany],
|
238
|
+
extensions: [CR::Temporale::Extensions::ChristEternalPriest]
|
239
|
+
}
|
240
|
+
)
|
241
|
+
d = pcal[Date.new(2000, 1, 1)]
|
242
|
+
|
243
|
+
# It is also possible to supply Temporale factory instead of options:
|
244
|
+
pcal = CR::PerpetualCalendar.new(
|
245
|
+
# Proc returning a Temporale instance for the specified year
|
246
|
+
temporale_factory: lambda do |year|
|
247
|
+
CR::Temporale.new(year, transfer_to_sunday: [:ascension])
|
248
|
+
end
|
249
|
+
)
|
250
|
+
pcal[Date.new(2000, 1, 1)]
|
251
|
+
```
|
252
|
+
|
253
|
+
**Memory management note:**
|
254
|
+
Internally, `PerpetualCalendar` builds `Calendar` instances as needed
|
255
|
+
and by default caches them *perpetually.* This is OK in most cases,
|
256
|
+
but it can lead to memory exhaustion if you traverse an excessive
|
257
|
+
amount of liturgical years. In such cases you can supply
|
258
|
+
your own cache (a `Hash` or anything with hash-like interface)
|
259
|
+
and implement some kind of cache size limiting.
|
260
|
+
|
261
|
+
```ruby
|
262
|
+
my_cache = {}
|
263
|
+
pcal = CR::PerpetualCalendar.new(cache: my_cache)
|
264
|
+
```
|
265
|
+
|
266
|
+
## Sanctorale Data
|
267
|
+
|
268
|
+
### Use prepared data or create your own
|
269
|
+
|
270
|
+
The gem expects data files following a custom format -
|
271
|
+
see README in the [data](/data) directory for it's description.
|
272
|
+
The same directory contains a bunch of example data files.
|
273
|
+
(All of them are also bundled in the gem and accessible via
|
274
|
+
`CalendariumRomanum::Data`, as described above.)
|
275
|
+
|
276
|
+
`universal-en.txt` and `universal-la.txt` are data of the General
|
277
|
+
Roman Calendar in English and Latin.
|
278
|
+
|
279
|
+
The `czech-*.txt` files, when layered properly, can be used to assemble
|
280
|
+
proper calendar of any diocese in the Czech Republic.
|
281
|
+
|
282
|
+
### Implement custom loading strategy
|
283
|
+
|
284
|
+
In case you already have sanctorale data in another format,
|
285
|
+
it might be better suited for you to implement your own loading
|
286
|
+
routine instead of migrating them to our custom format.
|
287
|
+
`SanctoraleLoader` is the class to look into for inspiration.
|
288
|
+
|
289
|
+
The important bit is that for each celebration you
|
290
|
+
build a `Celebration` instance and push it in a `Sanctorale`
|
291
|
+
instance by a call to `Sanctorale#add`, which receives a month,
|
292
|
+
a day (as integers) and a `Celebration`:
|
293
|
+
|
294
|
+
```ruby
|
295
|
+
include CalendariumRomanum
|
296
|
+
sanctorale = Sanctorale.new
|
297
|
+
celebration = Celebration.new('Saint John Eudes, priest', Ranks::MEMORIAL_OPTIONAL, Colours::WHITE)
|
298
|
+
sanctorale.add 8, 19, celebration
|
299
|
+
|
300
|
+
date = Date.new(2016, 8, 19)
|
301
|
+
calendar = Calendar.for_day(date, sanctorale)
|
302
|
+
|
303
|
+
day = calendar[date]
|
304
|
+
day.celebrations # => [#<CalendariumRomanum::Celebration:0x000000010deea8 @title="", @rank=#<struct CalendariumRomanum::Rank priority=3.13, desc="Unprivileged ferials", short_desc="ferial">, @colour=:green>, #<CalendariumRomanum::Celebration:0x000000010fec08 @title="Saint John Eudes, priest", @rank=#<struct CalendariumRomanum::Rank priority=3.12, desc="Optional memorials", short_desc="optional memorial">, @colour=:white>]
|
305
|
+
```
|
306
|
+
|
307
|
+
(Note that this time some typing was saved by *including*
|
308
|
+
the `CalendariumRomanum` module into the current namespace.)
|
309
|
+
|
310
|
+
## I18n, or, how to fix names of temporale feasts
|
311
|
+
|
312
|
+
One drawback of the current implementation is that names
|
313
|
+
of *temporale* feasts are totally independent of *sanctorale* feast
|
314
|
+
names. They are hardcoded in the gem, as [i18n][]
|
315
|
+
[translation strings][translations].
|
316
|
+
|
317
|
+
When you load *sanctorale* data in your favourite language,
|
318
|
+
the `Calendar` will by default still produce *temporale*
|
319
|
+
feasts with names in English.
|
320
|
+
This can be fixed by changing locale to match your *sanctorale*
|
321
|
+
data.
|
322
|
+
|
323
|
+
`I18n.locale = :la # or :en, :fr, :it, :cs`
|
324
|
+
|
325
|
+
The gem ships with English, Latin, Italian, French and Czech translation.
|
326
|
+
Contributed translations to other languages are most welcome.
|
327
|
+
|
328
|
+
## Transfer of solemnities to a Sunday
|
329
|
+
|
330
|
+
As specified in
|
331
|
+
[General Norms for the Liturgical Year and the Calendar][gnlyc] 7,
|
332
|
+
the solemnities of Epiphany, Ascension and Corpus Christi
|
333
|
+
can be transferred to a Sunday.
|
334
|
+
`Temporale` by default preserves the regular dates of these
|
335
|
+
solemnities, but it has an option to enable the transfer:
|
336
|
+
|
337
|
+
```ruby
|
338
|
+
# transfer all three to Sunday
|
339
|
+
temporale = CR::Temporale.new(2016, transfer_to_sunday: [:epiphany, :ascension, :corpus_christi])
|
340
|
+
```
|
341
|
+
|
342
|
+
Usually you don't want to work with `Temporale` alone, but with
|
343
|
+
a `Calendar`. In order to create a `Calendar` with non-default
|
344
|
+
`Temporale` settings, it is necessary to provide a `Temporale`
|
345
|
+
as third argument to the constructor.
|
346
|
+
|
347
|
+
```ruby
|
348
|
+
year = 2000
|
349
|
+
sanctorale = CR::Data::GENERAL_ROMAN_ENGLISH.load
|
350
|
+
temporale = CR::Temporale.new(year, transfer_to_sunday: [:epiphany])
|
351
|
+
|
352
|
+
calendar = CR::Calendar.new(year, sanctorale, temporale)
|
353
|
+
```
|
354
|
+
|
355
|
+
## Custom movable feasts
|
356
|
+
|
357
|
+
Some local calendars may include proper movable feasts.
|
358
|
+
In Czech Republic this has recently been the case with the newly
|
359
|
+
introduced feast of *Christ the Priest* (celebrated on Thursday
|
360
|
+
after Pentecost). Support for this feast, celebrated in several other
|
361
|
+
dioceses and religious institutes, is included in the gem
|
362
|
+
as `Temporale` extension.
|
363
|
+
|
364
|
+
In order to build a complete Czech `Calendar` with proper sanctorale
|
365
|
+
feasts and the additional temporale feast of *Christ the Priest*,
|
366
|
+
it is necessary, apart of loading the sanctorale data,
|
367
|
+
to provide a `Temporale` instance with the extension applied:
|
368
|
+
|
369
|
+
```ruby
|
370
|
+
year = 2016
|
371
|
+
sanctorale = CR::Data::CZECH.load
|
372
|
+
temporale =
|
373
|
+
CR::Temporale.new(
|
374
|
+
year,
|
375
|
+
# the important bit: apply the Temporale extension
|
376
|
+
extensions: [CR::Temporale::Extensions::ChristEternalPriest]
|
377
|
+
)
|
378
|
+
|
379
|
+
calendar = CR::Calendar.new(year, sanctorale, temporale)
|
380
|
+
```
|
381
|
+
|
382
|
+
The feast of *Christ the Priest*, by it's nature, extends the cycle of
|
383
|
+
*Feasts of the Lord in the Ordinary Time* and thus clearly belongs
|
384
|
+
to the *temporale.* Even if your proper movable feast
|
385
|
+
is by it's nature a *sanctorale* feast, just having a movable
|
386
|
+
date, the only way to handle it using this gem is to write
|
387
|
+
a *temporale* extension. There is no support for movable feasts
|
388
|
+
in the `Sanctorale` class. Even the single movable sanctorale
|
389
|
+
feast of the General Roman Calendar,
|
390
|
+
the memorial of *Immaculate Heart of Mary,* is, by a little cheat,
|
391
|
+
currently implemented in the `Temporale`.
|
392
|
+
|
393
|
+
Any object defining method `each_celebration`, which yields
|
394
|
+
pairs of "date computer" and `Celebration`, can be used as
|
395
|
+
temporale extension. Unless you have a good reason to do otherwise,
|
396
|
+
a class or module defining `each_celebration` as class/module method
|
397
|
+
is a convenient choice.
|
398
|
+
|
399
|
+
```ruby
|
400
|
+
module MyExtension
|
401
|
+
# yields celebrations defined by the extension
|
402
|
+
def self.each_celebration
|
403
|
+
yield(
|
404
|
+
:my_feast_date, # name of a method computing date of the feast
|
405
|
+
CR::Celebration.new(
|
406
|
+
'My Feast', # feast title
|
407
|
+
CR::Ranks::FEAST_PROPER, # rank
|
408
|
+
CR::Colours::WHITE # colour
|
409
|
+
)
|
410
|
+
)
|
411
|
+
|
412
|
+
yield(
|
413
|
+
# Proc can be used for date computation instead of a method
|
414
|
+
# referenced by name
|
415
|
+
lambda {|year| CR::Temporale::Dates.easter_sunday(year) + 9 },
|
416
|
+
CR::Celebration.new(
|
417
|
+
# It is possible to use a Proc as feast title if you want it
|
418
|
+
# to be determined at runtime - e.g. because you want to
|
419
|
+
# have the feast title translated and follow changes of `I18n.locale`
|
420
|
+
proc { I18n.t('my_feasts.another_feast') },
|
421
|
+
CR::Ranks::MEMORIAL_PROPER,
|
422
|
+
CR::Colours::WHITE
|
423
|
+
)
|
424
|
+
)
|
425
|
+
end
|
426
|
+
|
427
|
+
# computes date of the feast;
|
428
|
+
# the year passed as argument is year when the liturgical
|
429
|
+
# year in question _begun_
|
430
|
+
def self.my_feast_date(year)
|
431
|
+
# the day before Christ the King
|
432
|
+
CR::Temporale::Dates.christ_king(year) - 1
|
433
|
+
end
|
434
|
+
end
|
435
|
+
|
436
|
+
temporale = CR::Temporale.new(2016, extensions: [MyExtension])
|
437
|
+
|
438
|
+
# the feast is there!
|
439
|
+
temporale[Date.new(2017, 11, 25)] # => #<CalendariumRomanum::Celebration:0x0000000246fd78 @title="My Feast", @rank=#<CalendariumRomanum::Rank:0x000000019c27e0 @priority=2.8, ... >, @colour=#<CalendariumRomanum::Colour:0x000000019c31e0 @symbol=:white>>
|
440
|
+
```
|
441
|
+
|
442
|
+
## Internationalization internals
|
443
|
+
|
444
|
+
It was already mentioned earlier in this document that
|
445
|
+
for internationalization of temporale feast names and
|
446
|
+
other "built-in strings"
|
447
|
+
`calendarium-romanum` relies upon the `i18n` gem.
|
448
|
+
Some internal details may be worth a mention:
|
449
|
+
|
450
|
+
On `require 'calendarium-romanum'`, paths of a few translation
|
451
|
+
files bundled in the gem are added to `I18n.config.load_path`.
|
452
|
+
While otherwise we avoid poluting or modifying the environment
|
453
|
+
outside the gem's own scope, in this case we exceptionally
|
454
|
+
modify global configuration in order to make the internationalization
|
455
|
+
easily and conveniently work.
|
456
|
+
If your application requires `calendarium-romanum` to handle
|
457
|
+
languages not bundled in the gem, or if you don't like the default
|
458
|
+
translations, just prepare a [translation file](/config/locales),
|
459
|
+
put it anywhere in your project's tree
|
460
|
+
and add it's path to `I18n.config.load_path`.
|
461
|
+
If, on the other hand, even the officially supported languages
|
462
|
+
don't work for you, check if paths to the gem's translation files
|
463
|
+
are present in `I18n.config.load_path` and possibly search your
|
464
|
+
application (and it's other dependencies) for code which kicked
|
465
|
+
them out.
|
466
|
+
|
467
|
+
## Executable
|
468
|
+
|
469
|
+
This gem provides an executable, `calendariumrom`.
|
470
|
+
It's handful of subcommands can be used to query liturgical calendar
|
471
|
+
from the command line and to check validity of sanctorale data files.
|
472
|
+
|
473
|
+
### 1. Query liturgical calendar from the command line
|
474
|
+
|
475
|
+
- `calendariumrom query --calendar universal-fr 2007-06-25` queries a non-default (French) calendar for any given date. `--calendar` can be omitted, the default calendar (`universal-en`) is used then. The date can be omitted as well, `calendariumrom` will query the current date, then. Please note that the date has to be in format `YYYY-MM-DD` or `YYYY/MM/DD`. If the day, or even the month is omitted, `query` will query a whole month, or even a whole year. The specified calendar has to be one in the resulting list of the `calendarium calendars` command, or a valid filesystem path.
|
476
|
+
- `calendariumrom calendars` will list all available data files known to calendarium-romanum.
|
477
|
+
|
478
|
+
Tip: `calendariumrom query` is a rather bare-bones calendar querying
|
479
|
+
tool. Check out the [`calrom`][calrom] gem for a more feature-rich
|
480
|
+
liturgical calendar for your command line.
|
481
|
+
|
482
|
+
### 2. Check sanctorale data files
|
483
|
+
|
484
|
+
- `calendariumrom cmp FILE1 FILE2` will load 2 data files from the file system and compare them. If there are any differences in rank or colour of corresponding celebrations, it will output them.
|
485
|
+
- `calendariumrom errors FILE1, ...` finds errors in a data file. It tries to load it from file system, and if the parser will fail, for whatever reason, it will print out the reason.
|
486
|
+
|
487
|
+
### 3. Help
|
488
|
+
|
489
|
+
- `calendariumrom` lists available subcommands
|
490
|
+
- `calendariumrom help [COMMAND]` outputs a short help for all available subcommands
|
491
|
+
|
492
|
+
## For Developers
|
493
|
+
|
494
|
+
Get the sources and install development depencencies:
|
495
|
+
|
496
|
+
1. `git clone git@github.com:igneus/calendarium-romanum.git`
|
497
|
+
2. `cd calendarium-romanum`
|
498
|
+
3. `bundle install` or `bundle install --path vendor/bundle`
|
499
|
+
|
500
|
+
### Run from CLI
|
501
|
+
|
502
|
+
`bundle exec ruby -Ilib bin/calendariumrom`
|
503
|
+
|
504
|
+
### Run Tests
|
505
|
+
|
506
|
+
`bundle exec rake spec`
|
507
|
+
|
508
|
+
See also `.travis.yml` for comprehensive tests run on the CI.
|
509
|
+
|
510
|
+
[awesomecc]: https://github.com/calendarium-romanum/awesome-church-calendar
|
511
|
+
[gnlyc]: https://www.ewtn.com/catholicism/library/liturgical-year-2193
|
512
|
+
[i18n]: https://github.com/svenfuchs/i18n
|
513
|
+
[translations]: /tree/master/config/locales
|
514
|
+
[module-included]: http://ruby-doc.org/core-2.2.2/Module.html#method-i-included
|
515
|
+
[calrom]: https://github.com/calendarium-romanum/calrom
|