calendarium-romanum 0.5.0 → 0.9.0

data/data/universal-pt.txt

@@ -0,0 +1,248 @@
+---
+title: Calendário Romano Geral
+locale: pt
+# source: https://pt.wikipedia.org/wiki/Calendário_Romano_Geral,
+#         Roman Missal (Portuguese edition),
+#         and https://www.liturgia.pt/
+---
+
+= 1
+2 m basil_gregory : Ss. Basílio Magno e Gregório de Nazianzo, bispos e doutores da Igreja
+3 name_jesus : Santíssimo Nome de Jesus
+7 raymond : S. Raimundo de Peñafort. presbítero
+13 hilary : S. Hilário, bispo e doutor da Igreja
+17 m anthony_of_egypt : S. Antão, abade
+20 R fabian : S. Fabião, papa e mártir
+20 R sebastian : S. Sebastião, mártir
+21 m R agnes : S. Inês, virgem e mártir
+22 R vincent_deacon : S. Vicente, diácono e mártir
+24 m francis_de_sales : S. Francisco de Sales, bispo e doutor da Igreja
+25 f paul_conversion : Conversão de S. Paulo, apóstolo
+26 m timothy_titus : Ss. Timóteo e Tito, bispos
+27 merici : S. Angela Merici, virgem
+28 m aquinas : S. Tomás de Aquino, presbítero e doutor da Igreja 
+31 m bosco : S. João Bosco, presbítero
+
+= 2
+2 f2.5 presentation_of_lord : Apresentação do Senhor
+3 R blase : S. Brás, bispo e mártir
+3 ansgar : S. Ansgário, bispo
+5 m R agatha : S. Águeda (ou Ágata), virgem e mártir
+6 m R paul_miki : Ss. Paulo Miki e companheiros, mártires 
+8 jerome_emiliani : S. Jerónimo Emiliano, presbítero
+8 josephine_bakhita : S. Josefina Bakhita, virgem
+10 m scholastica : S. Escolástica, virgem
+11 bvm_lourdes : Nossa Senhora de Lourdes
+14 m cyril_methodius : Ss. Cirilo, monge, e Metódio, bispo
+17 servite_founders : Ss. Sete Fundadores da Ordem dos Servitas
+21 peter_damian : S. Pedro Damião, bispo e doutor da Igreja
+22 f chair_of_peter : Cátedra de S. Pedro, apóstolo
+23 m R polycarp : S. Policarpo, bispo e mártir
+27 gregory_of_narek : S. Gregório de Narek, abade e doutor da Igreja
+
+= 3
+4 casimir : S. Casimiro
+7 m R perpetua_felicity : Santas Perpétua e Felicidade, mártires
+8 john_of_god : S. João de Deus, religiosos
+9 frances_of_rome : S. Francisca Romana, religiosa
+17 patrick : S. Patrício, bispo
+18 cyril_of_jerusalem : S. Cirilo de Jerusalém, bispo e doutor da Igreja
+19 s joseph : S. José, esposo da Virgem S. Maria
+23 turibius :  S. Turíbio de Mongrovejo, bispo
+25 s annunciation : Anunciação do Senhor
+
+= 4
+2 francis_of_paola :  S. Francisco de Paula, eremita
+4 isidore : S. Isidoro, bispo e doutor da Igreja
+5 vincent_ferrer : S. Vicente Ferrer, presbítero
+7 m de_la_salle : S. João Batista de La Salle, presbítero
+11 m R stanislaus : S. Estanislau, bispo e mártir
+13 R martin_i : S. Martinho I, papa e mártir
+21 anselm : S. Anselmo, bispo e doutor da Igreja
+23 R george : S. Jorge, mártir
+23 R adalbert : S. Adalberto de Praga, bispo e mártir
+24 R fidelis : S. Fiel de Sigmaringa, presbítero e mártir
+25 f R mark : S. Marcos, evangelista
+28 R peter_chanel : S. Pedro Chanel, presbítero e mártir
+28 de_montfort : S. Luís Maria Grignion de Montfort, presbítero
+29 m catherine_of_siena : S. Catarina de Siena, virgem e doutora da Igreja
+30 pius_v : S. Pio V, papa
+
+= 5
+1 joseph_worker : S. José operário
+2 m athanasius : S. Atanásio, bispo e doutor da Igreja
+3 f R philip_james : Ss. Filipe e Tiago, apóstolos
+10 john_de_avila : S. João de Ávila, presbítero e doutor da Igreja
+12 R nereus_achilleus : Ss. Nereu e Aquileu, mártires
+12 R pancras : S. Pancrácio, mártir
+13 bvm_fatima : Nossa Senhora de Fátima
+14 f R matthias : S. Matias, apóstolo
+18 R john_i : S. João I, papa e mártir
+20 bernardine : S. Bernardino de Sena, presbítero
+21 R magallanes : Ss. Cristóvão de Magalhães e companheiros, mártires
+22 rita : S. Rita de Cássia, religiosa
+25 bede_venerable : S. Beda Venerável, presbítero e doutor da Igreja
+25 gregory_vii : S. Gregório VII, papa
+25 de_pazzi : S. Maria Madalena de Pazzi, virgem
+26 m neri : S. Filipe Néri, presbítero
+27 augustine_of_canterbury : S. Agostinho de Cantuária, bispo
+29 paul_vi : Sãp Paulo VI, papa
+31 f visitation :  Visitação da Virgem S. Maria
+
+= 6
+1 m R justin : S. Justino, mártir
+2 R marcellinus_peter : Ss. Marcelino e Pedro, mártires
+3 m R ugandan_martyrs : Ss. Carlos Lwanga e companheiros, mártires
+5 m R boniface : S. Bonifácio, bispo e mártir
+6 norbert : S. Norberto, bispo
+9 ephrem : S. Efrém, diácono e doutor da Igreja
+11 m R barnabas : S. Barnabé, apóstolo
+13 m anthony_of_padua : S. António de Lisboa, presbítero e doutor da Igreja
+19 romuald : S. Romualdo, abade
+21 m aloysius : S. Luís de Gonzaga, religioso
+22 paulinus : S. Paulino de Nola, bispo
+22 R fisher_more : Ss. João Fisher, bispo e mártir, e Tomás Moro, mártir
+24 s baptist_birth : Nascimento de João Batista
+27 cyril_of_alexandria : S. Cirilo de Alexandria, bispo e doutor da Igreja
+28 m R irenaeus : S. Ireneu, bispo e mártir
+29 s R peter_paul : Ss. Pedro e Paulo, apóstolos
+30 R first_martyrs_of_rome : Primeiros Ss. Mártires da Igreja de Roma
+
+= 7
+3 f R thomas_apostle : S. Tomé, apóstolo
+4 elizabeth_of_portugal : S. Isabel de Portugal
+5 anthony_zaccaria : S. António Maria Zacarias, presbítero
+6 R goretti : S. Maria Goretti, virgem e mártir
+9 R chinese_martyrs : Ss. Agostinho Zhao Rong e companheiros, mártires
+11 m benedict : S. Bento, abade
+13 henry : S. Henrique
+14 camillus_de_lellis : S. Camilo de Lelis, presbítero
+15 m bonaventure : S. Boaventura, bispo e doutor da Igreja
+16 bvm_mount_carmel : Virgem S. Maria do Monte Carmelo
+20 R apollinaris : S. Apolinário, bispo e mártir
+21 lawrence_of_brindisi : S. Lourenço de Brindes, presbítero e doutor da Igreja
+22 f mary_magdalene : S. Maria Madalena
+23 birgitta : S. Brígida, religiosa
+24 sharbel : S. Sarbélio Makhluf, presbítero
+25 f R james : S. Tiago, Apóstolo 
+26 m joachim_anne : S. Joaquim e S. Ana, pais da Virgem S. Maria 
+29 m martha_mary_lazarus : SS. Marta, Maria e Lázaro
+30 peter_chrysologus : S. Pedro Crisólogo, bispo e doutor da Igreja
+31 m ignatius_of_loyola : S. Inácio de Loiola, presbítero
+
+= 8
+1 m alphonsus : S. Afonso Maria de Ligório, bispo e doutor da Igreja
+2 eusebius : S. Eusébio de Vercelas, bispo
+2 eymard : S. Pedro Juliano Eymard, presbítero
+4 m vianney : S. João Maria Vianney, presbítero
+5 mary_major : Dedicação da Basílica de Santa Maria Maior
+6 f2.5 transfiguration : Transfiguração do Senhor
+7 R sixtus_ii : SS. Sisto II, papa, e Companheiros, mártires
+7 cajetan : S. Caetano, presbítero
+8 m dominic : S. Domingos, presbítero, Fundador da Ordem dos Pregadores
+9 R stein : S. Teresa Benedita da Cruz, virgem e mártir
+10 f R lawrence : S. Lourenço, diácono e mártir
+11 m clare : S. Clara, virgem
+12 de_chantal : S. Joana Francisca de Chantal, religiosa
+13 R pontian_hippolytus : S. Ponciano, papa, e S. Hipólito, presbítero, mártires
+14 m R kolbe : S. Maximiliano Maria Kolbe, presbítero e mártir
+15 s assumption : ASSUNÇÃO DA VIRGEM SANTA MARIA
+16 stephen_hungary : S. Estêvão da Hungria
+19 eudes : S. João Eudes, presbítero
+20 m bernard : S. Bernardo, abade e doutor da Igreja
+21 m pius_x : S. Pi0 X, papa
+22 m bvm_queenship : Virgem Santa Maria, Rainha
+23 rose_lima : S. Rosa de Lima, virgem
+24 f R bartholomew : S. Bartolomeu, Apóstolo
+25 louis : S. Luís de França
+25 joseph_calasanz : S. José de Calasanz, presbítero
+27 m monica : S. Mónica
+28 m augustine : S. Agostinho, bispo e doutor da Igreja
+29 m R baptist_beheading : Martírio de S. João Baptista
+
+= 9
+3 m gregory_great : S. Gregório Magno, papa e doutor da Igreja
+8 f bvm_birth : Natividade da Virgem Santa Maria
+9 claver : S. Pedro Claver, presbítero
+12 bvm_name : Santíssimo Nome de Maria
+13 m john_chrysostom : S. João Crisóstomo, bispo e doutor da Igreja
+14 f2.5 R cross : Exaltação da Santa Cruz
+15 m bvm_sorrows : Virgem Santa Maria das Dores
+16 m R cornelius_cyprian : S. Cornélio, papa, e S. Cipriano, bispo, mártires
+17 bellarmine : S. Roberto Belarmino, bispo e doutor da Igreja
+17 hildegard : S. Hildegarda de Bingen, virgem e doutora da Igreja
+19 R januarius : S. Januário, bispo e mártir
+20 m R korean_martyrs : SS. André Kim Taegon, presbítero, Paulo Chang Hasang, e Companheiros, mártires
+21 f R matthew : S. Mateus, Apóstolo e Evangelista
+23 m padre_pio : S. Pio de Pietrelcina, presbítero
+26 R cosmas_damian : S. Cosme e S. Damião, mártires
+27 m vincent_de_paul : S. Vicente de Paulo, presbítero
+28 R wenceslaus : S. Venceslau, mártir
+28 R ruiz : SS. Lourenço Ruiz e Companheiros, mártires
+29 f archangels : S. Miguel, S. Gabriel e S. Rafael, Arcanjos
+30 m jerome : S. Jerónimo, presbítero e doutor da Igreja
+
+= 10
+1 m therese_lisieux : S. Teresa do Menino Jesus, virgem e doutora da Igreja
+2 m guardian_angels : Santos Anjos da Guarda
+4 m francis_assisi : S. Francisco de Assis
+5 faustina_kowalska : Santa Faustina Kowalska
+6 bruno : S. Bruno, presbítero
+7 m bvm_rosary : Virgem Santa Maria do Rosário
+9 R denis : SS. Dionísio, bispo, e Companheiros, mártires
+9 leonardi : S. João Leonardo, presbítero
+11 john_xxiii : S. João XXIII, papa
+14 R callistus_i : S. Calisto I, papa e mártir
+15 m teresa_avila : S. Teresa de Jesus, virgem e doutora da Igreja
+16 hedwig : S. Hedwiges, religiosa
+16 alacoque : S. Margarida Maria Alacoque, virgem
+17 m R ignatius_of_antioch : S. Inácio de Antioquia, bispo e mártir
+18 f R luke : S. Lucas, Evangelista
+19 R brebeuf_jogues : SS. João de Brébeuf e Isaac Jogues, presbíteros, e Companheiros, mártires
+19 paul_of_cross : S. Paulo da Cruz, presbítero
+22 john_paul_ii : S. João Paulo II, papa
+23 john_capistrano : S. João de Capistrano, presbítero
+24 claret : S. António Maria Claret, bispo
+28 f R simon_jude : S. Simão e S. Judas, Apóstolos
+
+= 11
+1 s all_saints : TODOS OS SANTOS
+2 s V all_souls : Comemoração de Todos os Fiéis Defuntos 
+3 de_porres : S. Martinho de Porres, religioso
+4 m borromeo : S. Carlos Borromeu, bispo
+9 f2.5 lateran_basilica : Dedicação da Basílica de Latrão
+10 m leo_great : S. Leão Magno, papa e doutor da Igreja
+11 m martin : S. Martinho de Tours, bispo
+12 m R josaphat : S. Josafat, bispo e mártir
+15 albert : S. Alberto Magno, bispo e doutor da Igreja
+16 margaret_of_scotland : S. Margarida da Escócia
+16 gertrude : S. Gertrudes, virgem
+17 m elizabeth_of_hungary : S. Isabel da Hungria, religiosa 
+18 peter_paul_basilicas : Dedicação das Basílicas de S. Pedro e de S. Paulo, Apóstolos
+21 m bvm_presentation : Apresentação de Nossa Senhora
+22 m R cecilia : S. Cecília, virgem e mártir
+23 R clement_i : S. Clemente I, papa e mártir
+23 columban : S. Columbano, abade
+24 m R vietnamese_martyrs : SS. André Dung-Lac, presbítero, e Companheiros, mártires
+25 R catherine_of_alexandria : S. Catarina Alexandrina, virgem e mártir 
+30 f R andrew : S. André, Apóstolo
+
+= 12
+3 m francis_xavier : S. Francisco Xavier, presbítero, Padroeiro das Missões
+4 john_damascene : S. João Damasceno, presbítero e doutor da Igreja
+6 nicholas : S. Nicolau, bispo
+7 m ambrose : S. Ambrósio, bispo e doutor da Igreja
+8 s bvm_immaculate : IMACULADA CONCEIÇÃO DA VIRGEM SANTA MARIA
+9 juan_diego : S. João Diogo
+10 bvm_loreto : Virgem Santa Maria de Loreto
+11 damasus_i : S. Dâmaso I, papa
+12 bvm_guadalupe : Nossa Senhora de Guadalupe
+13 m R lucy : S. Luzia, virgem e mártir
+14 m john_of_cross : S. João da Cruz, presbítero e doutor da Igreja
+21 canisius : S. Pedro Canísio, presbítero e doutor da Igreja
+23 john_of_kanty : S. João de Quenty (Câncio), presbítero
+26 f R stephen : S. Estêvão, Primeiro Mártir
+27 f john_evangelist : S. João, Apóstolo e Evangelista
+28 f R innocents : Santos Inocentes, mártires
+29 R becket : S. Tomás Becket (de Cantuária), bispo e mártir
+31 sylvester_i : S. Silvestre I, papa

data/doc/data_readme.md

@@ -0,0 +1,2 @@
+# @title data/README.md
+{include:file:data/README.md}

data/doc/images/class_diagram.puml

@@ -0,0 +1,44 @@
+@startuml
+object Calendar {
+    year
+}
+object PerpetualCalendar
+
+object Temporale
+object Sanctorale
+
+object Day {
+    date
+    season
+    season_week
+    celebrations
+    vespers
+}
+object Celebration {
+    title
+    colour
+    rank
+    date
+    cycle
+    symbol
+}
+object AbstractDate
+object Season
+object Rank
+object Colour
+
+Calendar o-- Temporale
+Calendar o-- Sanctorale
+
+PerpetualCalendar *-- Calendar
+
+Calendar ..> Day : produces
+Temporale ..> Celebration : produces
+Sanctorale "1" --> "0..*" Celebration
+
+Day "1" --> "1..*" Celebration
+Celebration --> Season
+Celebration --> Rank
+Celebration --> Colour
+Celebration --> AbstractDate
+@enduml

data/doc/yard_readme.rdoc

@@ -0,0 +1,76 @@
+= calendarium-romanum
+
+Ruby gem for
+calendar computations according to the Roman Catholic liturgical
+calendar as instituted by
+MP <em>{Mysterii Paschalis}[http://w2.vatican.va/content/paul-vi/en/motu_proprio/documents/hf_p-vi_motu-proprio_19690214_mysterii-paschalis.html]</em> of Paul VI. (AAS 61 (1969), pp. 222-226).
+The rules are defined in
+<em>{General Norms for the Liturgical Year and the Calendar}[https://www.ewtn.com/catholicism/library/liturgical-year-2193]</em>.
+
+== Quickstart
+
+For usage instructions with copy-pastable code examples see {file:README.md}
+
+== Object model overview
+
+rdoc-image:images/class_diagram.png
+
+<b>{CalendariumRomanum::Calendar Calendar}</b> is the library's main functional unit.
+It represents calendar for a single liturgical year and allows retrieving calendar data
+for any of the year's days.
+Calendar basically consists of
+a {CalendariumRomanum::Temporale Temporale} and a {CalendariumRomanum::Sanctorale Sanctorale}
+and it's main task is to combine information from both and for any day of the year produce
+a fully and correctly populated {CalendariumRomanum::Day Day} instance,
+containing one or more {CalendariumRomanum::Celebration Celebrations}
+(see {CalendariumRomanum::Calendar#[] Calendar#[]}).
+
+(+Calendar+ does not own either +Temporale+ or +Sanctorale+ - it is possible to pass them
+on initialization and they are treated as read-only. The only exception is method
+{CalendariumRomanum::Calendar#freeze #freeze}, which freezes all the +Calendar+'s contents,
+including +Temporale+ and +Sanctorale+.)
+
+<b>{CalendariumRomanum::PerpetualCalendar PerpetualCalendar}</b> is a higher-level API
+for retrieving calendar data
+without bothering about liturgical years. It builds {CalendariumRomanum::Calendar Calendar}
+instances internally and passes method calls to them.
+
+<b>{CalendariumRomanum::Day Day}</b> contains complete calendar data of a liturgical day.
+It owns one or more {CalendariumRomanum::Celebration Celebrations}.
+If there are multiple it means that any one of them can be chosen and celebrated
+that day.
+
+<b>{CalendariumRomanum::Celebration Celebration}</b> represents a celebration
+(particular solemnity / feast / memorial / Sunday / ferial)
+and holds it's liturgical properties, encoded mostly by value objects.
+
+(Unlike +Day+, +Celebration+ instances are not bound to a particular date,
+they represent "celebration C in general", not "celebration C in year Y".
+The latter is represented only by a combination of +Celebration+ and +Day+.
++Celebration+ instances are immutable and some may be used repeatedly in context of various
+days and calendars.)
+
+<b>{CalendariumRomanum::Season Season}</b>,
+<b>{CalendariumRomanum::Rank Rank}</b>,
+<b>{CalendariumRomanum::Colour Colour}</b>
+are value objects representing values
+of {CalendariumRomanum::Celebration Celebration} properties.
+Immutable instances representing the standard values are referenced by constants and
+normally there should be no need to create any more.
+
+<b>{CalendariumRomanum::Temporale Temporale}</b> represents the temporale cycle of a single liturgical
+year, computes movable feasts, determines liturgical seasons.
+For any day of the year it provides a temporale {CalendariumRomanum::Celebration Celebration}.
+
+<b>{CalendariumRomanum::Sanctorale Sanctorale}</b> represents the sanctorale cycle, i.e. the fixed-date
+celebrations, mostly feasts of saints. It is not bound to a particular year, hence a single
+instance can be used by many {CalendariumRomanum::Calendar Calendar} instances representing
+various liturgical years. For any day it provides zero or more
+{CalendariumRomanum::Celebration Celebrations}.
+
+Most particular calendars (calendars of countries, provinces, dioceses, churches, religious
+institutes) share the same temporale definition and differ in sanctorale contents.
+Therefore the task of implementing a particular calendar usually consists of populating
+a {CalendariumRomanum::Sanctorale Sanctorale} instance with the desired data.
+A convenient way to do so is preparing a {file:data/README.md sanctorale data file}
+and loading it using {CalendariumRomanum::SanctoraleLoader SanctoraleLoader}.

data/lib/calendarium-romanum.rb

@@ -1,6 +1,16 @@
+# Module wrapping the gem's classes
+#
+# If you hate typing the long module name, see {CR}
+module CalendariumRomanum
+end
+
+require 'date'
+
 %w(
   version
   i18n_setup
+  abstract_date
+  rank_predicates
   rank
   enum
   enums
@@ -9,15 +19,19 @@
   day
   calendar
   perpetual_calendar
+  temporale/date_helper
   temporale/dates
   temporale/celebration_factory
+  temporale/easter_table
+  temporale/extensions
   temporale/extensions/christ_eternal_priest
+  temporale/extensions/dedication_before_all_saints
   temporale
   sanctorale
-  sanctoraleloader
+  sanctorale_loader
+  sanctorale_writer
   sanctorale_factory
   transfers
-  abstract_date
   util
   ordinalizer
 ).each do |f|

data/lib/calendarium-romanum/abstract_date.rb

@@ -4,12 +4,20 @@ module CalendariumRomanum
   class AbstractDate
     include Comparable
 
+    # @param month [Integer]
+    # @param day [Integer]
+    # @raise [RangeError] on invalid +month+/+day+ value
     def initialize(month, day)
       validate! month, day
       @month = month
       @day = day
     end
 
+    # Build a new instance from a +Date+ (or an object with
+    # similar public interface).
+    #
+    # @param date [Date]
+    # @return [AbstractDate]
     def self.from_date(date)
       new(date.month, date.day)
     end
@@ -32,10 +40,17 @@ module CalendariumRomanum
       month == other.month && day == other.day
     end
 
+    # Produce a +Date+ by providing a year to an +AbstractDate+
+    #
+    # @param year [Integer]
+    # @return [Date]
     def concretize(year)
       Date.new(year, month, day)
     end
 
+    # @since 0.8.0
+    alias in_year concretize
+
     private
 
     def validate!(month, day)