Class: CalendariumRomanum::Sanctorale

Inherits:
Object
  • Object
show all
Defined in:
lib/calendarium-romanum/sanctorale.rb

Overview

One of the two main Calendar components. Contains celebrations with fixed date, mostly feasts of saints.

Basically a mapping AbstractDate => Array<Celebration> additionally enforcing some constraints:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Sanctorale

Returns a new instance of Sanctorale.



18
19
20
21
22
23
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 18

def initialize
  @days = {}
  @solemnities = {}
  @symbols = Set.new
  @metadata = nil
end

Instance Attribute Details

#metadata ⇒ Hash?

Sanctorale metadata.

Data files may contain YAML front matter. If provided, it’s loaded by CalendariumRomanum::SanctoraleLoader and stored in this property. All data files bundled in the gem (see Data) have YAML front matter which is a Hash with a few standardized keys. While YAML also supports top-level content of other types, sanctorale data authors should stick to the convention of using Hash as the top-level data structure of their front matters.

Returns:

  • (Hash, nil)

Since:

  • 0.7.0



58
59
60
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 58

def metadata
  @metadata
end

#solemnities ⇒ Hash<AbstractDate=>Celebration> (readonly)

Content subset - only Celebrations in the rank(s) of solemnity.

Returns:



42
43
44
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 42

def solemnities
  @solemnities
end

Instance Method Details

#==(b) ⇒ Boolean

Returns:

  • (Boolean)

Since:

  • 0.6.0



227
228
229
230
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 227

def ==(b)
  self.class == b.class &&
    days == b.days
end

#[](date) ⇒ Array<Celebration>

Retrieves Celebrations for the given date

Parameters:

Returns:

Since:

  • 0.6.0



166
167
168
169
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 166

def [](date)
  adate = date.is_a?(AbstractDate) ? date : AbstractDate.from_date(date)
  @days[adate] || []
end

#add(month, day, celebration) ⇒ void

This method returns an undefined value.

Adds a new Celebration

Parameters:

  • month (Integer)
  • day (Integer)
  • celebration (Celebration)

Raises:

  • (ArgumentError) —

    when performing the operation would break the object’s invariant



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 68

def add(month, day, celebration)
  date = AbstractDate.new(month, day)

  unless @days[date].nil? || @days[date].empty?
    present = @days[date][0]
    if present.rank != Ranks::MEMORIAL_OPTIONAL
      raise ArgumentError.new("On #{date} there is already a #{present.rank}. No more celebrations can be added.")
    elsif celebration.rank != Ranks::MEMORIAL_OPTIONAL
      raise ArgumentError.new("Celebration of rank #{celebration.rank} cannot be grouped, but there is already another celebration on #{date}")
    end
  end

  unless celebration.symbol.nil?
    if @symbols.include? celebration.symbol
      raise ArgumentError.new("Attempted to add Celebration with duplicate symbol #{celebration.symbol.inspect}")
    end

    @symbols << celebration.symbol
  end

  unless @days.has_key? date
    @days[date] = []
  end

  if celebration.solemnity?
    @solemnities[date] = celebration
  end

  @days[date] << celebration
end

#by_symbol(symbol) ⇒ Array<AbstractDate, Celebration>?

If the instance contains a Celebration identified by the specified symbol, returns it’s date and the Celebration itself, nil otherwise.

Parameters:

  • symbol (Symbol)

Returns:

Since:

  • 0.9.0



247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 247

def by_symbol(symbol)
  return nil unless provides_celebration? symbol

  @days.each_pair do |date, celebrations|
    found = celebrations.find {|c| c.symbol == symbol }
    return [date, found] if found
  end

  # reaching this point would mean that contents of @symbols and @days are not consistent
  raise 'this point should never be reached'
end

#dup ⇒ Sanctorale

Returns a copy of the receiver with properly copied internal data structures, i.e. a copy which can be safely modified without danger of unintentionally modifying the original instance.

Returns:




# File 'lib/calendarium-romanum/sanctorale.rb', line 25

#each_day {|AbstractDate, Array<Celebration>| ... } ⇒ void, Enumerator

Enumerates dates for which any Celebrations are available

Yields:

Returns:

  • (void, Enumerator) —

    if called without a block, returns Enumerator



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

def each_day
  return to_enum(__method__) unless block_given?

  @days.each_pair do |date, celebrations|
    yield date, celebrations
  end
end

#empty? ⇒ Boolean

It is empty if it doesn’t contain any Celebration

Returns:

  • (Boolean) 


213
214
215
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 213

def empty?
  @days.empty?
end

#freeze ⇒ Object

Freezes the instance



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

def freeze
  @days.freeze
  @days.values.each(&:freeze)
  @solemnities.freeze
  super
end

#get(date) ⇒ Array<Celebration> #get(month, day) ⇒ Array<Celebration>

Retrieves Celebrations for the given date

Overloads:

Returns:



179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 179

def get(*args)
  if args.size == 1 && args[0].is_a?(Date)
    month = args[0].month
    day = args[0].day
  else
    month, day = args
  end

  date = AbstractDate.new(month, day)
  self[date]
end

#initialize_dup(other) ⇒ 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. 



32
33
34
35
36
37
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 32

def initialize_dup(other)
  @days = other.days.dup
  @solemnities = other.solemnities.dup
  @symbols = other.symbols.dup
  @metadata = Marshal.load Marshal.dump other.metadata # deep copy
end

#merge(other) ⇒ Sanctorale

Returns a new copy containing Celebrations from both self and other.

Parameters:

Returns:

Since:

  • 0.9.0



157
158
159
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 157

def merge(other)
  dup.tap {|dupped| dupped.update other }
end

#provides_celebration?(symbol) ⇒ Boolean

Does this instance provide celebration identified by symbol symbol?

Parameters:

  • symbol (Symbol)

Returns:

  • (Boolean)

Since:

  • 0.9.0



237
238
239
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 237

def provides_celebration?(symbol)
  @symbols.include? symbol
end

#replace(month, day, celebrations, symbol_uniqueness: true) ⇒ void

This method returns an undefined value.

Replaces content of the given day by given Celebrations

Parameters:

  • month (Integer)
  • day (Integer)
  • celebrations (Array<Celebration>)
  • symbol_uniqueness (true|false) (defaults to: true) —

    allows disabling symbol uniqueness check. Internal feature, not intended for use by client code.

Raises:

  • (ArgumentError) —

    when performing the operation would break the object’s invariant



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 110

def replace(month, day, celebrations, symbol_uniqueness: true)
  date = AbstractDate.new(month, day)

  symbols_without_day = @symbols
  unless @days[date].nil?
    old_symbols = @days[date].collect(&:symbol).compact
    symbols_without_day = @symbols - old_symbols
  end

  new_symbols = celebrations.collect(&:symbol).compact
  duplicate = symbols_without_day.intersection new_symbols
  if symbol_uniqueness && !duplicate.empty?
    raise ArgumentError.new("Attempted to add Celebrations with duplicate symbols #{duplicate.to_a.inspect}")
  end

  @symbols = symbols_without_day
  @symbols.merge new_symbols

  if celebrations.first.solemnity?
    @solemnities[date] = celebrations.first
  elsif @solemnities.has_key? date
    @solemnities.delete date
  end

  @days[date] = celebrations.dup
end

#size ⇒ Integer

Returns count of days with Celebrations filled

Returns:

  • (Integer) 


206
207
208
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 206

def size
  @days.size
end

#update(other) ⇒ void

This method returns an undefined value.

Updates the receiver with Celebrations from another instance.

For each date contained in other the content of self is replaced by that of other.

Parameters:

Raises:

  • (ArgumentError) —

    when performing the operation would break the object’s invariant



145
146
147
148
149
150
 
# File 'lib/calendarium-romanum/sanctorale.rb', line 145

def update(other)
  other.each_day do |date, celebrations|
    replace date.month, date.day, celebrations, symbol_uniqueness: false
  end
  rebuild_symbols
end