calendarium-romanum 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cee5ab4345ad34eb849b0024a9d3489b29ebe55e8e960abd44ff858d911fdb32
-  data.tar.gz: e93e85c1e668d5d57a10e0846bdb0ae37e693ac125b3c9d3b09f3dac3d5d806f
+  metadata.gz: 783786a54e37a2d755c2bc0a0fdf1cf21b684ce5e1f186e180fb8513a7be8a8d
+  data.tar.gz: 8c4879981d34a5962f604de47ec4d77faf2b63cec5adf2699cfc9d1a718d045f
 SHA512:
-  metadata.gz: c6a4f20a4ccbb564ee51dcb24e7d354b5a9ed9495951b239ca653631fb08c48d2121989279cc3d9e93e0236721545fc62518c09b9ce8cdbd9e40ca89bff7786f
-  data.tar.gz: ab95329b242615cb3c81bcb31b171c2ba66ffa3e8e544dc1f33721d2e6e4d6e7e0cee68d429e4ff46ce34a550d6be9af969c5ee919da54f1890141f719900d4a
+  metadata.gz: ba211f79a4b79ed8169d15871e8630baf2a536182284ec58e851b061a980dd18a9163a8d8749ab8f1f470f2cdec64f5c236710022f8739862d39eb8efd88bcef
+  data.tar.gz: 7c6be1ff8bee1e4ea3159a7add679dc7b53949dfc086b82fc63335d670f69fdfc4518d020944d3db09a22cfeb6442fe733850adaab29948618a91f3ed93a3e82

data/.travis.yml

@@ -1,20 +1,22 @@
 language: ruby
-
+cache: bundler
 dist: trusty
 
-rvm:
-  - 2.0.0 # oldest MRI we support
-  - 2.5.0 # oldest officially maintained MRI
-  - 2.6.5 # ~ latest MRI
-  #- jruby-9.1.12.0
-
 install: bundle install --jobs=3 --deployment --without development
 
-script: bundle exec rake spec_all_locales && bash spec/build/gem_build_test.sh
+script: bundle exec rake spec
 
-git:
-  depth: 3
+jobs:
+  include:
+    - rvm: 2.6.5 # ~ latest MRI
+      script:
+        - bundle exec rake spec_all_locales
+        - bash spec/build/gem_build_test.sh
+    - rvm: 2.5.0 # oldest officially maintained MRI
+    - rvm: 2.0.0 # oldest MRI we support
+  #   - rvm: jruby-9.1.12.0 # experimental
+  # allow_failures:
+  #   - rvm: jruby-9.1.12.0
 
-#matrix:
-#  allow_failures:
-#    - rvm: jruby-9.1.12.0
+git:
+  depth: 3

data/.yardopts

@@ -1,3 +1,3 @@
 --main doc/yard_readme.rdoc
 --asset doc/images:images
---file README.md,doc/data_readme.md,data/universal-en.txt
+--file README.md,doc/yard_readme.rdoc,doc/data_readme.md,data/universal-en.txt

data/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## [0.8.0] 2020-11-25
+
+### Fixed
+
+- several fixes to the solemnity transfer rules:
+  - the algorithm was searching for free days only forwards,
+	but liturgical law assumes closest free day, even earlier
+  - check that two solemnities are not transferred to the same date,
+    overwriting one another
+  - the special rule on Annunciation from *Normae universales* 60
+	implemented
+- fixed bug in computation of the date of Baptism of the Lord if Epiphany
+  is transferred to Sunday
+- fixed bug in `Sanctorale#update` preventing more than one `Celebration`
+  with nil `#symbol` in a single `Sanctorale`
+- `CelebrationFactory` was setting `Celebration#date` (if not specified)
+  to false instead of expected nil (thus breaking type promises)
+- data: `czech-cs.txt`: typo fixed in the feast *symbol* of St. Bartholomew;
+  spelling of several feast titles corrected
+- data: `czech-cs.txt`: proof-read against official sources, feasts
+  of "BVM, Queen of Angels" and St. Teresa of Calcutta deleted
+  (they are not on the calendar of Czech and Moravian dioceses,
+  incorrect information was copied from Czech Wikipedia at the time
+  of the data file's creation)
+- data: all: Dedication of the Lateran Basilica is feast of the Lord
+  (had incorrect rank of a normal feast so far)
+- data: `universal-en.txt`: several inaccuracies concerning liturgical
+  colour fixed
+
+### Added
+
+- `liturgical_law/`: all documents of liturgical legislation
+  containing the liturgical calendar rules (original Latin text)
+  in Markdown format, with Ruby code examples proving that
+  the rules are implemented correctly;
+  the code examples are all executed as part of the gem's test suite
+- `SanctoraleWriter` (contributed by Mike Kasberg @mkasberg)
+- `PerpetualCalendar.new` accepts keyword argument `vespers`
+  (cf. `Calendar.new` argument of the same name)
+- `Rank#optional_memorial?`, `#obligatory_memorial?`
+- `AbstractDate#in_year` - more readable alias of `#concretize`
+- `Rank#succ` - (among other things) allows constructing `Range` of `Rank`s
+- `Calendar#transferred`
+- `Temporale::Extensions::DedicationBeforeAllSaints` defining the solemnity
+  of Aniversary of Dedication for churches celebrating it on the movable
+  date on the last October Sunday
+- `Temporale::Extensions.all` - method listing all Temporale extensions
+  defined by the gem
+- `Temporale#each_day`
+- `Temporale::EasterTable` - class handling a simple plaintext format
+  for tables of Easter dates
+- `Celebration.new`: new argument `sunday`
+- `SanctoraleLoader`: proper solemnities/feasts/memorials
+  can be specified also by adding suffix `p` to the rank code
+  (instead of rank priority number used so far),
+  similarly suffix `l` can be used to specify proper rank for
+  feasts of the Lord
+- data: `universal-1969-la.txt` - historical first version
+  of the General Roman Calendar
+- module `Constants` containing all the constants from `Colours`,
+  `Seasons` and `Ranks`
+
+### Changed
+
+- the gemspec now declares requirement of Ruby >= 2.0
+- `Calendar.new` can be called also without the `year` argument if `Temporale`
+  is provided (thus calling `Calendar.new(temporale, sanctorale)`
+  instead of `Calendar.new(year, sanctorale, temporale)`)
+- Easter Triduum is now dealt with as a separate `Season`,
+  because *Normae universales* 18-21 clearly set the Triduum apart from
+  both Lent and Eastertide
+- `Temporale::Extensions::ChristEternalPriest` specifies celebration
+  symbol (so far it was nil)
+- `Celebration.new` supports keyword arguments (as an alternative to
+  or even in combination with the positional ones)
+- `Temporale`: business logic guaranteeing that `Celebration#sunday?`
+  is true also for privileged Sundays (Advent, Lent)
+- `calendariumrom` executable: all subcommands dealing with sanctorale
+  data files accept special file name `-` and load sanctorale data
+  from stdin in that case
+- `Enum`, `Colours`, `Seasons`, `Ranks` and `Data` changed from classes
+  to modules
+
+### Acknowledgements
+
+Improvements not affecting the gem's public interface (and thus not listed
+in the changelog) contributed by
+
+- Ihor Voloshyn @Snick555
+- Dmitry Zhmurko @zhmurko
+
 ## [0.7.1] 2020-06-28
 
 ### Fixed

data/README.md

@@ -4,8 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/calendarium-romanum.svg)](https://badge.fury.io/rb/calendarium-romanum)
 
 API documentation:
-[master](http://www.rubydoc.info/github/igneus/calendarium-romanum/master)
-[0.7.0](http://www.rubydoc.info/gems/calendarium-romanum/0.7.0)
+[0.8.0](http://www.rubydoc.info/gems/calendarium-romanum/0.8.0)
+[0.7.1](http://www.rubydoc.info/gems/calendarium-romanum/0.7.1)
 [0.6.0](http://www.rubydoc.info/gems/calendarium-romanum/0.6.0)
 [0.5.0](http://www.rubydoc.info/gems/calendarium-romanum/0.5.0)
 [0.4.0](http://www.rubydoc.info/gems/calendarium-romanum/0.4.0)
@@ -13,28 +13,47 @@ API documentation:
 [0.2.0](http://www.rubydoc.info/gems/calendarium-romanum/0.2.0)
 
 Ruby gem for
-calendar computations according to the Roman Catholic liturgical
-calendar as instituted by
-[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).
-The rules are defined in
-*General Norms for the Liturgical Year and the Calendar*
-([English translation][gnlyc]).
-
-calendarium-romanum aspires to become the most complete
+calendar computations according to the Roman Catholic liturgical calendar as instituted by
+[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),
+defined in *General Norms for the Liturgical Year and the Calendar*
+([English translation][gnlyc])
+and subsequent [documents of liturgical legislation][liturgical_law].
+
+`calendarium-romanum` aspires to become the most complete and most accurate
 FOSS implementation of this calendar system
 (see [list of implementations available][awesomecc]).
 
 ## Features
 
-- [x] liturgical season
-- [x] Sundays, temporale feasts
-- [x] sanctorale calendars: data format, example data files, their loading
-- [x] resolution of precedence of concurrent celebrations
-- [x] octave days
-- [x] commemorations in the privileged seasons where memorials are suppressed
-- [x] transfer of suppressed solemnities
-- [x] optional transfer of important solemnities to a Sunday
-- [x] additional temporale feasts (Christ the Eternal Priest and similar)
+`calendarium-romanum` is now a **feature-complete** implementation of the abovementioned calendar
+system, capable of generating a complete and (at least mostly) correct Roman Catholic liturgical
+calendar for any year according to the most recent calendar rules and data
+(i.e. today's state of the calendar is used also for years in the past - for historically accurate
+computations see a [related project][crhistorical]).
+
+It is **continuously kept up-to-date** with latest developments of the liturgical
+legislation and newly introduced feasts.
+
+**Accuracy** is highly valued. Therefore just a very limited set of calendar data
+is bundled in the library, but with a guarantee that a theologian continuously takes care
+of them being up-to-date and correct. Users of the library will usually want to prepare
+and maintain their own data files representing their local calendars.
+(For ready-to-use calendar data without guarantees of correctness
+see a [related repository][data-contrib].)
+
+The project's scope is strictly limited to computing **liturgical calendar in a narrow sense.**
+It doesn't provide functionality specific for individual liturgical books, unless it is
+dealt with in general liturgical norms regarding the calendar.
+(Liturgical colours being an exception from this rule, as it is very common to include
+them in all kinds of liturgical calendars.)
+But the library is designed with machine-readability in mind, so that additional layers
+of functionality, implementing book-specific calculations, can be built upon it.
+
+Strings are **localized** (using the [i18n][i18n] Ruby gem). Translations to six languages
+(Latin, English, Spanish, French, Italian, Czech)
+are provided. The built-in translations can be both replaced and/or supplemented
+with translations to additional languages without having to modify the gem's code.
 
 ## Credits
 
@@ -46,14 +65,19 @@ See also changelog for list of contributions and their authors.
 
 ## License
 
-freely choose between GNU/LGPL 3 and MIT
+dual licensed: freely choose between GNU/LGPL 3 and MIT
 
-## Project status, Backward compatibility
+## Project status
 
-The gem's public interface still evolves and each minor release
-contains several breaking changes. There is no backward compatibility
-between minor versions.
-This will continue until release of v1.0.0.
+The library is currently considered feature-complete for release 1.0.0
+and it's public API mostly stabilized.
+Development focuses on reaching higher degree of certainty regarding
+correctness by means of making the test suite more comprehensive and rigorous.
+
+## Backward compatibility
+
+The gem's public interface has now been mostly stabilized, but until v1.0.0 release
+there is still no guaranteed backward compatibility between minor versions.
 
 When using the gem in your projects, it is recommended to lock
 the dependency to a particular minor version.
@@ -61,13 +85,13 @@ the dependency to a particular minor version.
 In your app's Gemfile
 
 ```
-gem 'calendarium-romanum', '~>0.6.0'
+gem 'calendarium-romanum', '~>0.8.0'
 ```
 
 or in gemspec of your gem
 
 ```
-spec.add_dependency 'calendarium-romanum', '~>0.6.0'
+spec.add_dependency 'calendarium-romanum', '~>0.8.0'
 ```
 
 ## Usage
@@ -162,11 +186,23 @@ which loads the gem *and* defines the `CR` shortcut for you.
 Following examples expect the `CR` constant to be defined
 and reference the `CalendariumRomanum` module.
 
+Another possible way of saving some typing (if you don't care about
+possible name clashes or polluting current namespace)
+is including `CalendariumRomanum` module in the current module.
+Then `CalendariumRomanum` classes can be referenced unqualified:
+
+```ruby
+include CalendariumRomanum
+
+loader = SanctoraleLoader.new
+# etc.
+```
+
 ### 4. Isn't there an easier way to get sanctorale data?
 
 Yes! There are a few data files bundled in the gem.
 You can explore them by iterating over `CalendariumRomanum::Data.all`.
-The more interesting ones are additionally identified by their proper
+Those of general interest are additionally identified by their proper
 constants, e.g. `CalendariumRomanum::Data::GENERAL_ROMAN_ENGLISH`.
 Bundled data files can be loaded by a handy shortcut method `#load`:
 
@@ -204,7 +240,7 @@ a `Calendar` for liturgical year 1999-2000 by calling
 `Calendar.new(1999)`.
 
 We have already seen `Calendar.for_day()`, which takes care
-for finding the liturgical year a particular date belongs to
+of finding the liturgical year a particular date belongs to
 and creating a `Calendar` for this year.
 But maybe you want to query a calendar without caring about liturgical
 years altogether, possibly picking days across multiple years.
@@ -283,7 +319,7 @@ proper calendar of any diocese in the Czech Republic.
 
 In case you already have sanctorale data in another format,
 it might be better suited for you to implement your own loading
-routine instead of migrating them to our custom format.
+routine instead of transforming them to our custom format.
 `SanctoraleLoader` is the class to look into for inspiration.
 
 The important bit is that for each celebration you
@@ -292,20 +328,59 @@ instance by a call to `Sanctorale#add`, which receives a month,
 a day (as integers) and a `Celebration`:
 
 ```ruby
-include CalendariumRomanum
-sanctorale = Sanctorale.new
-celebration = Celebration.new('Saint John Eudes, priest', Ranks::MEMORIAL_OPTIONAL, Colours::WHITE)
+sanctorale = CR::Sanctorale.new
+celebration = CR::Celebration.new('Saint John Eudes, priest', CR::Ranks::MEMORIAL_OPTIONAL, CR::Colours::WHITE)
 sanctorale.add 8, 19, celebration
 
 date = Date.new(2016, 8, 19)
-calendar = Calendar.for_day(date, sanctorale)
+calendar = CR::Calendar.for_day(date, sanctorale)
 
 day = calendar[date]
 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>]
 ```
 
-(Note that this time some typing was saved by *including*
-the `CalendariumRomanum` module into the current namespace.)
+### Proper calendar of a church
+
+One common case of preparing custom sanctorale data is
+implementing proper calendar of a church
+(cf. *General Norms for the Liturgical Year and the Calendar* par. 52 c).
+Proper calendar of a church is built by adding to the calendar
+of the diocese (or religious institute) the church'es proper celebration,
+which are usually just two solemnities: anniversary of dedication
+and titular solemnity.
+
+Let's say you have calendar of your diocese in sanctorale data file
+`my-diocese.txt`.
+You could copy the file to a new location and add the two proper solemnities,
+but your programmer better self won't allow you to do that.
+What options are left? You can create a new sanctorale file
+with the two proper celebrations and then load it over the calendar
+of the diocese, as explained in [data](/data).
+Or, if you need the calendar just for that single little script
+and don't care about creating data files, you can build the two
+proper solemnities in code:
+
+```ruby
+# here you would load your 'diocese.txt' instead
+diocese = CR::SanctoraleLoader.new.load_from_file 'data/universal-en.txt'
+
+dedication = CR::Celebration.new('Anniversary of Dedication of the Parish Church', CR::Ranks::SOLEMNITY_PROPER, CR::Colours::WHITE)
+titular = CR::Celebration.new('Saint Nicholas, Bishop, Titular Solemnity of the Parish Church', CR::Ranks::SOLEMNITY_PROPER, CR::Colours::WHITE)
+
+# solution 1 - directly modify the loaded Sanctorale
+
+diocese.replace(10, 25, [dedication])
+diocese.replace(12, 6, [titular])
+
+# solution 2 - create a new Sanctorale with just the two solemnities,
+# then create a third instance merging contents of the two without modifying them
+
+proper_solemnities = CR::Sanctorale.new
+proper_solemnities.replace(10, 25, [dedication])
+proper_solemnities.replace(12, 6, [titular])
+
+complete_proper_calendar = CR::SanctoraleFactory.create_layered(diocese, proper_solemnities)
+```
 
 ## I18n, or, how to fix names of temporale feasts
 
@@ -322,7 +397,7 @@ data.
 
 `I18n.locale = :la # or :en, :fr, :it, :cs`
 
-The gem ships with English, Latin, Italian, French and Czech translation.
+The gem ships with English, Latin, Italian, Spanish, French and Czech translation.
 Contributed translations to other languages are most welcome.
 
 ## Transfer of solemnities to a Sunday
@@ -426,7 +501,7 @@ module MyExtension
 
   # computes date of the feast;
   # the year passed as argument is year when the liturgical
-  # year in question _begun_
+  # year in question _began_
   def self.my_feast_date(year)
     # the day before Christ the King
     CR::Temporale::Dates.christ_king(year) - 1
@@ -449,7 +524,7 @@ Some internal details may be worth a mention:
 
 On `require 'calendarium-romanum'`, paths of a few translation
 files bundled in the gem are added to `I18n.config.load_path`.
-While otherwise we avoid poluting or modifying the environment
+While otherwise we avoid polluting or modifying the environment
 outside the gem's own scope, in this case we exceptionally
 modify global configuration in order to make the internationalization
 easily and conveniently work.
@@ -472,8 +547,9 @@ from the command line and to check validity of sanctorale data files.
 
 ### 1. Query liturgical calendar from the command line
 
- - `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.
- - `calendariumrom calendars` will list all available data files known to calendarium-romanum.
+- `calendariumrom query` prints calendar entries for today or a specified day, month or year.
+  See `calendariumrom help query` for available options and arguments.
+- `calendariumrom calendars` lists data files bundled in `calendarium-romanum`.
 
 Tip: `calendariumrom query` is a rather bare-bones calendar querying
 tool. Check out the [`calrom`][calrom] gem for a more feature-rich
@@ -481,13 +557,16 @@ liturgical calendar for your command line.
 
 ### 2. Check sanctorale data files
 
- - `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. 
- - `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. 
+- `calendariumrom cmp FILE1 FILE2` loads two data files and prints any differences between them
+  (excepting differences in celebration titles)
+- `calendariumrom errors FILE1, ...` attempts loading a data file (or several of them),
+  reports eventual errors
 
 ### 3. Help
 
- - `calendariumrom` lists available subcommands
- - `calendariumrom help [COMMAND]` outputs a short help for all available subcommands
+- `calendariumrom` lists available subcommands
+- `calendariumrom help [COMMAND]` outputs a short help for all available subcommands
+- `calendariumrom version` prints installed version of the gem
 
 ## For Developers
 
@@ -511,5 +590,9 @@ See also `.travis.yml` for comprehensive tests run on the CI.
 [gnlyc]: https://www.ewtn.com/catholicism/library/liturgical-year-2193
 [i18n]: https://github.com/svenfuchs/i18n
 [translations]: /tree/master/config/locales
+[liturgical_law]: /tree/master/liturgical_law
 [module-included]: http://ruby-doc.org/core-2.2.2/Module.html#method-i-included
 [calrom]: https://github.com/calendarium-romanum/calrom
+[crhistorical]: https://github.com/calendarium-romanum/historical
+[data-contrib]: https://github.com/calendarium-romanum/data-contrib
+[i18n]: https://github.com/ruby-i18n/i18n

data/Rakefile

@@ -7,3 +7,10 @@ task :spec_all_locales do
     sh "LOCALE=#{locale} rake spec"
   end
 end
+
+desc 'Generates calendar dumps for regression tests anew'
+task :regression_refresh do
+  2020.upto(2030).each do |year|
+    sh "ruby -Ilib bin/calendariumrom dump #{year} > spec/regression_dumps/#{year}.txt"
+  end
+end