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, transfers: nil) ⇒ Calendar #initialize(temporale, sanctorale = nil, vespers: false, transfers: nil) ⇒ 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, transfers: nil) ⇒ 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

    • transfers (#call, nil) (defaults to: nil) —

      Object with the same public interface as the Transfers class (really class, not instance!), responsible for handling transfers of conflicting solemnities. Only useful for overriding the default solemnity transfer logic with a custom one.

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

    Parameters:

    • temporale (Temporale)
    • sanctorale (Sanctorale, nil) (defaults to: nil)
    • vespers (Boolean) (defaults to: false)
    • transfers (#call, nil) (defaults to: nil)

    Since:

    • 0.8.0

Raises:

  • (RangeError) —

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



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

def initialize(year, sanctorale = nil, temporale = nil, vespers: false, transfers: nil)
  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 || Transfers).call(@temporale, @sanctorale).freeze
end

Instance Attribute Details

#sanctorale ⇒ Sanctorale (readonly)

Returns:



116
117
118
 
# File 'lib/calendarium-romanum/calendar.rb', line 116

def sanctorale
  @sanctorale
end

#temporale ⇒ Temporale (readonly)

Returns:



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

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



123
124
125
 
# File 'lib/calendarium-romanum/calendar.rb', line 123

def transferred
  @transferred
end

#year ⇒ Integer (readonly)

Returns:

  • (Integer) 


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

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:



94
95
96
 
# File 'lib/calendarium-romanum/calendar.rb', line 94

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. 



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

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)



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

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:



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

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)



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
210
211
 
# File 'lib/calendarium-romanum/calendar.rb', line 176

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



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

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) 


238
239
240
 
# File 'lib/calendarium-romanum/calendar.rb', line 238

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.



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

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

#lectionary ⇒ Symbol

Sunday lectionary cycle

Returns:



231
232
233
 
# File 'lib/calendarium-romanum/calendar.rb', line 231

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



129
130
131
 
# File 'lib/calendarium-romanum/calendar.rb', line 129

def populates_vespers?
  @populate_vespers
end

#range_check(date) ⇒ void

This method returns an undefined value.

Parameters:

  • date

See Also:



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

def_delegators :@temporale, :range_check, :season

#season(date) ⇒ Season

Parameters:

  • date

Returns:

See Also:



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

def_delegators :@temporale, :range_check, :season