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

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

Parameters:

  • year (Fixnum)

    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

Raises:

  • (RangeError)

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


32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
# File 'lib/calendarium-romanum/calendar.rb', line 32

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

Instance Attribute Details

#sanctoraleSanctorale (readonly)

Returns:


99
100
101
# File 'lib/calendarium-romanum/calendar.rb', line 99

def sanctorale
  @sanctorale
end

#temporaleTemporale (readonly)

Returns:


96
97
98
# File 'lib/calendarium-romanum/calendar.rb', line 96

def temporale
  @temporale
end

#yearFixnum (readonly)

Returns:

  • (Fixnum)

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

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:


77
78
79
# File 'lib/calendarium-romanum/calendar.rb', line 77

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.


51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# File 'lib/calendarium-romanum/calendar.rb', line 51

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)


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

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:


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

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 (Fixnum)
    • month (Fixnum)
    • day (Fixnum)

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)


152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
# File 'lib/calendarium-romanum/calendar.rb', line 152

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


196
197
198
199
200
201
# File 'lib/calendarium-romanum/calendar.rb', line 196

def each
  return to_enum(__method__) unless block_given?

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

#ferial_lectionary1, 2

Ferial lectionary cycle

Returns:

  • (1, 2)

214
215
216
# File 'lib/calendarium-romanum/calendar.rb', line 214

def ferial_lectionary
  @year % 2 + 1
end

#freezeObject

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.


224
225
226
227
228
# File 'lib/calendarium-romanum/calendar.rb', line 224

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

#lectionarySymbol

Sunday lectionary cycle

Returns:


207
208
209
# File 'lib/calendarium-romanum/calendar.rb', line 207

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


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

def populates_vespers?
  @populate_vespers
end

#range_check(date) ⇒ void

This method returns an undefined value.

Parameters:

  • date

See Also:


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

def_delegators :@temporale, :range_check, :season

#season(date) ⇒ Season

Parameters:

  • date

Returns:

See Also:


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

def_delegators :@temporale, :range_check, :season