Class: BibleReferenceParser::ReferenceCollection

Inherits:
Object
  • Object
show all
Includes:
TracksErrors
Defined in:
lib/bible_reference_parser/reference/reference_collection.rb

Overview

This class is used to hold collections of reference objects. It functions similar to an array, augmented with information about whether any parsing errors occured in the items it contains.

A ReferenceCollection is returned from the following methods:

  • All BibleReferenceParser.parse methods

  • BookReference.parse_books

  • ChapterReference.parse_chapters

  • VerseReference.parse_verses

Also, child references are ReferenceCollection objects. For example:

books = BibleReferenceParser.parse "Genesis 1:1"
books.first.chapter_references # => a reference collection
books.first.children # => an alias for chapter_references, so also a reference collection
books.first.chapter_references.first.verse_references # => another reference collection

ReferenceCollections let you quickly see all the errors in the items it contains. Example:

books = BibleReferenceParser.parse("Genthesis 1:1-10, Matthew 1:5, Rev. 5000") # books is a ReferenceCollection
books.length # => 3
books.has_errors? # => true
books.no_errors? # => false
books.errors.length # => 2
books.errors # => ["The book 'Genthesis' could not be found", "Chapter '5000' does not exist for the book Revelation"]
bad_books = books.clean
books.length # => 1 (Matthew 1:5)
books.invalid_references.length # => 2

After calling the clean method, bad references are move to the invalid_references field. Please note that a reference will still be left in the collection as long as itself is valid. So a valid book could possibly only contain invalid chapters:

books = BibleReferenceParser.parse("Genesis 51") # genesis is valid, but chapter 51 isn't
books.clean
books.length # => 1 (still contains the reference to Genesis)
books.first.has_errors? # => true
books.first.chapter_references.length # => 0
books.first.chapter_references.invalid_references.length # => 1 
books.invalid_references.length # => 1 (returns the same as above, just less explicit)
books.errors # => ["Chapter '51' does not exist for the book Genesis"]

XXX next we can add a method for sorting items in the collection.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from TracksErrors

#add_error, #clear_errors, #has_errors?, #no_errors?

Constructor Details

#initialize(initial_references = [], initial_invalid_references = []) ⇒ ReferenceCollection

Initialization



55
56
57
58
59
60
61
62
63
64
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 55

def initialize(initial_references = [], initial_invalid_references = [])
  super 
                  
  # Array of reference objects this collection contains
  @references = initial_references
              
  # Holds references that are invalid. The "clean" method finds all invalid
  # references and moves them to this collection.
  @invalid_references = initial_invalid_references
end

Instance Attribute Details

#invalid_references ⇒ Object (readonly)

Returns the value of attribute invalid_references.



50
51
52
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 50

def invalid_references
  @invalid_references
end

#references ⇒ Object (readonly)

Returns the value of attribute references.



50
51
52
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 50

def references
  @references
end

Instance Method Details

#+(collection) ⇒ Object

Accepts either an Array or ReferenceCollection



137
138
139
140
141
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 137

def +(collection)
  new_references = collection.kind_of?(ReferenceCollection) ? collection.references : collection
  combined_references = references + new_references
  ReferenceCollection.new(combined_references, invalid_references)
end

#-(collection) ⇒ Object

Accepts either an Array or ReferenceCollection



144
145
146
147
148
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 144

def -(collection)
  new_references = collection.kind_of?(ReferenceCollection) ? collection.references : collection
  combined_references = references - new_references
  ReferenceCollection.new(combined_references, invalid_references)
end

#<<(reference) ⇒ Object 



158
159
160
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 158

def <<(reference)
  references << reference
end

#[](index) ⇒ Object 



150
151
152
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 150

def [](index) 
  references[index]
end

#clean(chain = true) ⇒ Object

Moves invalid references into the special “invalid_references” collection. A reference is valid if it’s “valid_reference?” method returns true. This is useful if you want to loop through the valid references only, and deal with the invalid ones separately:

books = BibleReferenceParser.parse("Matthew 1:1, Mark 1:1, Lkue 1:1")
books.length # => 3 (all three references)
books.clean
books.length # => 2 ("Lkue" is now in the invalid_references collection)
books.each do |book| ... # => loop through just the good references
books.invalid_refernces.each do |invalid| ... # now deal with the bad ones

The chain paremeter indicates whether child references should also be cleaned. For example, if you have a collection of book references, if chain is true it will also call clean on the chapter and verse references. Chain is true by default.

Please note that a valid reference may not actually contain valid references. For example:

books = BibleReferenceParser.parse("Genesis 51") # genesis is valid, but chapter 51 isn't
books.chapter_references.length # => 1    
books.clean
books.chapter_references.length # => 0
books.chapter_references.invalid_references.length # => 1



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 112

def clean(chain = true)
  removed = []
  removed_through_chain = []
  
  @references.each do |reference|
    if reference.valid_reference?
      removed_through_chain += reference.clean if chain
    else
      removed << reference
    end
  end
  
  @references -= removed
  
  all_removed = (removed + removed_through_chain)
  @invalid_references += all_removed
  
  all_removed
end

#each(*args, &block) ⇒ Object 



154
155
156
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 154

def each(*args, &block)
   references.each(*args, &block)
end

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


174
175
176
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 174

def empty?
  references.empty?
end

#errors(include_child_errors = true) ⇒ Object

Get all the errors in this reference collection.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 71

def errors(include_child_errors = true)
  # start with errors added directly to this reference collection
  all_errors = super(include_child_errors)
  
  # include the errors from invalid references
  @invalid_references.each do |reference|
    all_errors += reference.errors(include_child_errors)
  end
  
  # include the errors from references
  @references.each do |reference|
    all_errors += reference.errors(include_child_errors)
  end

  all_errors.uniq      
end

#first ⇒ Object 



166
167
168
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 166

def first
  references.first
end

#last ⇒ Object 



170
171
172
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 170

def last 
  references.last
end

#length ⇒ Object 



162
163
164
 
# File 'lib/bible_reference_parser/reference/reference_collection.rb', line 162

def length
  references.length
end