Class: CalendariumRomanum::Calendar

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/calendarium-romanum/calendar.rb

Overview

Provides complete information concerning a liturgical year, it’s days and celebrations occurring on them.

Calendar‘s business logic is mostly about correctly combining information from Temporale and Sanctorale.

Constant Summary collapse

EFFECTIVE_FROM =

Day when the implemented calendar system became effective

Date.new(1970, 1, 1).freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(year, sanctorale = nil, temporale = nil, vespers: false) ⇒ Calendar #initialize(temporale, sanctorale = nil, vespers: false) ⇒ Calendar

Returns a calendar for the liturgical year beginning with Advent of the specified civil year.

Overloads:

  • #initialize(year, sanctorale = nil, temporale = nil, vespers: false) ⇒ Calendar

    Parameters:

    • year (Integer) —

      Civil year when the liturgical year begins.

    • sanctorale (Sanctorale, nil) (defaults to: nil) —

      If not provided, the Calendar will only know celebrations of the temporale cycle, no feasts of the saints!

    • temporale (Temporale, nil) (defaults to: nil) —

      If not provided, Temporale for the given year with default configuration will built.

    • vespers (Boolean) (defaults to: false) —

      Set to true if you want the Calendar to populate Day#vespers

  • #initialize(temporale, sanctorale = nil, vespers: false) ⇒ Calendar

    Parameters:

    • temporale (Temporale)
    • sanctorale (Sanctorale, nil) (defaults to: nil) —

      If not provided, the Calendar will only know celebrations of the temporale cycle, no feasts of the saints!

    • vespers (Boolean) (defaults to: false) —

      Set to true if you want the Calendar to populate Day#vespers

    Since:

    • 0.8.0

Raises:

  • (RangeError) —

    if year is specified for which the implemented calendar system wasn’t in force



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/calendarium-romanum/calendar.rb', line 42

def initialize(year, sanctorale = nil, temporale = nil, vespers: false)
  unless year.is_a? Integer
    temporale = year
    year = temporale.year
  end

  if year < (EFFECTIVE_FROM.year - 1)
    raise system_not_effective
  end

  if temporale && temporale.year != year
    raise ArgumentError.new('Temporale year must be the same as year.')
  end

  @year = year
  @sanctorale = sanctorale || Sanctorale.new
  @temporale = temporale || Temporale.new(year)
  @populate_vespers = vespers

  @transferred = Transfers.call(@temporale, @sanctorale).freeze
end

Instance Attribute Details

#sanctorale ⇒ Sanctorale (readonly)

Returns:



114
115
116
 
# File 'lib/calendarium-romanum/calendar.rb', line 114

def sanctorale
  @sanctorale
end

#temporale ⇒ Temporale (readonly)

Returns:



111
112
113
 
# File 'lib/calendarium-romanum/calendar.rb', line 111

def temporale
  @temporale
end

#transferred ⇒ Hash<Date=>Celebration> (readonly)

Solemnities transferred to a date different from the usual one due to occurrence with a higher-ranking celebration.

Returns:

Since:

  • 0.8.0



121
122
123
 
# File 'lib/calendarium-romanum/calendar.rb', line 121

def transferred
  @transferred
end

#year ⇒ Integer (readonly)

Returns:

  • (Integer) 


108
109
110
 
# File 'lib/calendarium-romanum/calendar.rb', line 108

def year
  @year
end

Class Method Details

.for_day(date, *constructor_args) ⇒ Calendar

Creates a new instance for the liturgical year which includes given date

Parameters:

  • date (Date)
  • constructor_args —

    arguments that will be passed to #initialize

Returns:



92
93
94
 
# File 'lib/calendarium-romanum/calendar.rb', line 92

def for_day(date, *constructor_args)
  new(Temporale.liturgical_year(date), *constructor_args)
end

.mk_date(*args) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/calendarium-romanum/calendar.rb', line 66

def mk_date(*args)
  ex = TypeError.new('Date, DateTime or three Integers expected')

  if args.size == 3
    args.each do |a|
      raise ex unless a.is_a? Integer
    end
    return Date.new(*args)

  elsif args.size == 1
    a = args.first
    raise ex unless a.is_a? Date
    return a

  else
    raise ex
  end
end

Instance Method Details

#==(b) ⇒ Object

Two Calendars are equal if they have equal settings (which means that to equal input they return equal data)



133
134
135
136
137
138
139
 
# File 'lib/calendarium-romanum/calendar.rb', line 133

def ==(b)
  b.class == self.class &&
    year == b.year &&
    populates_vespers? == b.populates_vespers? &&
    temporale == b.temporale &&
    sanctorale == b.sanctorale
end

#[](date) ⇒ Day #[](range) ⇒ Array<Day>

Retrieve liturgical calendar information for the specified day or range of days.

Overloads:

  • #[](date) ⇒ Day

    Parameters:

    • date (Date)

    Returns:

  • #[](range) ⇒ Array<Day>

    Parameters:

    • range (Range<Date>)

    Returns:



150
151
152
153
154
155
156
 
# File 'lib/calendarium-romanum/calendar.rb', line 150

def [](args)
  if args.is_a?(Range)
    args.map {|date| day(date) }
  else
    day(args)
  end
end

#day(date, vespers: false) ⇒ Day #day(year, month, day, vespers: false) ⇒ Day

Retrieve liturgical calendar information for the specified day

Overloads:

  • #day(date, vespers: false) ⇒ Day

    Parameters:

    • date (Date)
  • #day(year, month, day, vespers: false) ⇒ Day

    Parameters:

    • year (Integer)
    • month (Integer)
    • day (Integer)

Parameters:

Returns:

Raises:

  • (RangeError) —

    If a date is specified on which the implemented calendar system was not yet in force (it became effective during the liturgical year 1969/1970)



174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/calendarium-romanum/calendar.rb', line 174

def day(*args, vespers: false)
  if args.size == 2
    date = Date.new(@year, *args)
    unless @temporale.date_range.include? date
      date = Date.new(@year + 1, *args)
    end
  else
    date = self.class.mk_date(*args)
    range_check date
  end

  if date < EFFECTIVE_FROM
    raise system_not_effective
  end

  celebrations = celebrations_for(date)
  vespers_celebration = nil
  if @populate_vespers || vespers
    begin
      vespers_celebration = first_vespers_on(date, celebrations)
    rescue RangeError
      # there is exactly one possible case when
      # range_check(date) passes and range_check(date + 1) fails:
      vespers_celebration = Temporale::CelebrationFactory.first_advent_sunday
    end
  end

  s = @temporale.season(date)
  Day.new(
    date: date,
    season: s,
    season_week: @temporale.season_week(s, date),
    celebrations: celebrations,
    vespers: vespers_celebration
  )
end

#each {|Day| ... } ⇒ void, Enumerator

Iterate over the whole liturgical year, day by day, for each day yield calendar data. If called without a block, returns Enumerator.

Yields:

Returns:

  • (void, Enumerator)

Since:

  • 0.6.0



218
219
220
221
222
223
 
# File 'lib/calendarium-romanum/calendar.rb', line 218

def each
  return to_enum(__method__) unless block_given?

  temporale.date_range
    .each {|date| yield(day(date)) }
end

#ferial_lectionary ⇒ 1, 2

Ferial lectionary cycle

Returns:

  • (1, 2) 


236
237
238
 
# File 'lib/calendarium-romanum/calendar.rb', line 236

def ferial_lectionary
  @year % 2 + 1
end

#freeze ⇒ Object

Freezes the instance.

WARNING: Temporale and Sanctorale instances passed to the Calendar on initialization will be frozen, too! This is necessary, because a Calendar would not really be frozen were it possible to mutate it’s key components.



246
247
248
249
250
 
# File 'lib/calendarium-romanum/calendar.rb', line 246

def freeze
  @temporale.freeze
  @sanctorale.freeze
  super
end

#lectionary ⇒ Symbol

Sunday lectionary cycle

Returns:



229
230
231
 
# File 'lib/calendarium-romanum/calendar.rb', line 229

def lectionary
  LECTIONARY_CYCLES[@year % 3]
end

#populates_vespers? ⇒ Boolean

Do Day instances returned by this Calendar have Day#vespers populated?

Returns:

  • (Boolean)

Since:

  • 0.6.0



127
128
129
 
# File 'lib/calendarium-romanum/calendar.rb', line 127

def populates_vespers?
  @populate_vespers
end

#range_check(date) ⇒ void

This method returns an undefined value.

Parameters:

  • date

See Also:



105
 
# File 'lib/calendarium-romanum/calendar.rb', line 105

def_delegators :@temporale, :range_check, :season

#season(date) ⇒ Season

Parameters:

  • date

Returns:

See Also:



105
 
# File 'lib/calendarium-romanum/calendar.rb', line 105

def_delegators :@temporale, :range_check, :season