bible_reference_parser 0.1.1

data/lib/bible_reference_parser/reference/reference_collection.rb

@@ -0,0 +1,179 @@
+module BibleReferenceParser 
+   
+  # 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.
+
+  class ReferenceCollection
+    include TracksErrors
+    
+    attr_reader :references, :invalid_references
+    
+    # Initialization
+    #----------------------------------------------------------------------------
+    
+    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 Methods
+    #----------------------------------------------------------------------------
+    
+    # Get all the errors in this reference collection. 
+    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
+    
+    # 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
+    # 
+    #   
+    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    
+    
+    
+    # Delegate Methods
+    #----------------------------------------------------------------------------
+    
+    # Accepts either an Array or ReferenceCollection
+    def +(collection)
+      new_references = collection.kind_of?(ReferenceCollection) ? collection.references : collection
+      combined_references = references + new_references
+      ReferenceCollection.new(combined_references, invalid_references)
+    end      
+    
+    # Accepts either an Array or ReferenceCollection
+    def -(collection)
+      new_references = collection.kind_of?(ReferenceCollection) ? collection.references : collection
+      combined_references = references - new_references
+      ReferenceCollection.new(combined_references, invalid_references)
+    end
+    
+    def [](index) 
+      references[index]
+    end
+
+    def each(*args, &block)
+       references.each(*args, &block)
+    end
+ 
+    def <<(reference)
+      references << reference
+    end
+    
+    def length
+      references.length
+    end
+    
+    def first
+      references.first
+    end
+    
+    def last 
+      references.last
+    end
+    
+    def empty?
+      references.empty?
+    end
+
+  end           
+end

data/lib/bible_reference_parser/reference/verse_reference.rb

@@ -0,0 +1,184 @@
+
+module BibleReferenceParser
+  
+  # This class handles the parsing of verses in a string. 
+  # 
+  # The main method of interest is VerseReference.parse_verses. This will parse a string
+  # and return a ReferenceCollection of VerseReference objects. One object for 
+  # each verse identified. Example:
+  # 
+  #     verses = VerseReference.parse_verses("1-10, 15")
+  #     verses[0].number # => 1
+  #     verses[1].number # => 2
+  #     verses.last.number # => 15
+  #
+  # You can see if there were any errors in parsing by checking the "has_errors?" method on the
+  # returned ReferenceCollection. Without specify metadata to validate against, only simple 
+  # validation is possible. If you do provide metadata (ex. BibleMetadata["Genesis"]) and a
+  # chapter number, it can validate that the verse number actually exists for the book and chapter.
+  # 
+  # If you want to validate the verse references against a book reference, it's better to use
+  # the parse_verses_in_reference method. This will parse the verses in a chapter reference and provide
+  # the right metadata information for validation. Example:
+  # 
+  #     chapter = ChapterReference(1, 500, BibleMetadata["Genesis"])
+  #     verses = VerseReference.parse_verses_in_reference(chapter)
+  #     verses.has_errors? # => true
+  #     verses.no_errors? # => false
+  #     verses.errors # => ["The verse '500' does not exist for Genesis 1"]
+  #
+  # You can check if an individiual VerseReference has errors as well:
+  #     
+  #     verses.first.has_errors? # => true
+  
+  class VerseReference
+    include TracksErrors
+    
+    attr_accessor :number
+    
+    # Initialization
+    #----------------------------------------------------------------------------
+    
+    # Initializes a new VerseReference object. if metadata and chapter_number is provided, it will validate
+    # that the verse number exists for the book and chapter.
+    # 
+    # You probably shouldn't be calling VerseReference.new directly. Instead, see
+    # VerseReference.parse_verses or VerseReference.parse_verses_in_reference.
+    # 
+    # Parameters:
+    # number          - The verse number.
+    # metadata        - An array of metadata information for a particular book, ex. BibleMetadata["Genesis"].
+    #                   This is used to validate the verse number exists for a book and chapter. If you provide
+    #                   this, also provide the chapter_number parameter.
+    # chapter_number  - The chapter number this verse is for. Used to validate the verse number exists for a
+    #                   book and chapter. 
+    def initialize(number, metadata = nil, chapter_number = nil)
+      super
+      
+      number = number.to_i # allows passing the number parameter as string
+      
+      # if number is less than 1 add a parsing error and stop processing
+      if number < 1
+        add_error "The verse number '#{number}' is not valid"
+        return
+      end
+      
+      # if metadata and chapter number is given, we can check if the verse exists for the book and chapter.
+      unless metadata.nil? || chapter_number.nil?
+        total_verses_in_chapter = metadata["chapter_info"][chapter_number - 1] # subtract 1 for array offset
+        if number > total_verses_in_chapter
+          add_error "The verse '#{number}' does not exist for #{metadata['name']} #{chapter_number}" and return
+        end
+      end
+  
+      @number = number
+    end             
+    
+    
+    # Class Methods
+    #----------------------------------------------------------------------------
+    
+    # Works similar to parse_verses. Use this if you want to parse the verses
+    # in a ChapterReference object. It will assume we want all of the verses
+    # if a chapter's raw_content is nil. But the only way we can do this is if
+    # the chapter reference has metadata defined. If not, we will just assume
+    # the first verse is wanted. Otherwise if raw_content is not nil, we will
+    # use that. 
+    def self.parse_verses_in_reference(chapter_ref)   
+      unless chapter_ref.raw_content.nil?
+        return self.parse_verses(chapter_ref.raw_content, chapter_ref.metadata, chapter_ref.number) 
+      else      
+        unless chapter_ref.metadata.nil?
+          # select all the verses in the chapter
+          chapter_info = chapter_ref.metadata["chapter_info"]
+          total_verses = chapter_info[chapter_ref.number - 1] # -1 for the array offset          
+          return self.parse_verses("1-#{total_verses}", chapter_ref.metadata, chapter_ref.number)         
+        else
+          # no real solution here, just assume the first verse
+          return self.parse_verses 1        
+        end
+      end
+    end  
+    
+    # Parse the verses in a string. Returns a ReferenceCollection
+    # of VerseReference objects.
+    # 
+    # Parameters:
+    # string          - The string to parse, ex. "1-10, 15"
+    # metadata        - An array of metadata information for a particular book, ex. BibleMetadata["Genesis"].
+    #                   NOTE: if you are passing this in, you probably should
+    #                   be calling parse_chapters_in_reference instead of this one.
+    # chapter_number  - The chapter number for the verse. Should be provided in conjunction with the metadata. 
+    # 
+    # Example:
+    # 
+    #     verses = VerseReference.parse_verses("1-10, 15")
+    #     verses.first.number # => 1
+    #     verses.last.number # => 15
+    #     verses.length # => 11
+    #
+    # More Examples:
+    # 
+    #     VerseReference.parse_verses("1")
+    #     VerseReference.parse_verses("1-10")
+    #     VerseReference.parse_verses("1,5,7")
+    #     VerseReference.parse_verses("1;5;7") # => same as above
+    #     VerseReference.parse_verses("1-5, 10, 15-20")
+    # 
+    # XXX we could add an option to allow a "beginning" or "end" for ranges.
+    # XXX we could allow an option to remove duplicates
+    def self.parse_verses(string, metadata = nil, chapter_number = nil) 
+      string = string.to_s # allows string to be passed as an int
+      
+      verses = ReferenceCollection.new
+      
+      # remove everything except for numbers and these punctuation marks -> -,;    
+      string_slim = string.gsub(/[^0-9;,\-]/, "")                        
+     
+      # This pattern matches for verses. It first tries to match a range of verses,
+      # then single verses.
+      # 
+      # Group 1: Verse Range ([0-9]+\-[0-9]+)
+      # - Any digits then a dash then any digits
+      # 
+      # Group 2: Single Verse ([0-9]+)
+      # - any digits
+      pattern = /([0-9]+\-[0-9]+)|([0-9]+)/
+      
+      # find the verses
+      string_slim.scan pattern do |verse_range, single_verse|        
+        if verse_range
+          # get the beginning and end of the range
+          range = verse_range.split "-"
+          first = range.first.to_i
+          last = range.last.to_i
+
+          # add each verse in the range
+          (first..last).each do |number|
+            verses << VerseReference.new(number, metadata, chapter_number)
+          end
+        else
+          verses << VerseReference.new(single_verse, metadata, chapter_number)          
+        end         
+      end
+      
+      verses       
+    end            
+       
+    
+    # Instance Methods
+    #----------------------------------------------------------------------------
+
+    # Whether this reference itself is valid.
+     def valid_reference?
+       !number.nil?
+     end
+     
+     # The standard clean method that all references must have. Because verses are leaf nodes and don't
+     # contain other references, this method will just return an empty array. 
+     def clean(chain = true)
+       []
+     end
+              
+  end  
+end

data/spec/bible_metadata_spec.rb

@@ -0,0 +1,66 @@
+require "spec_helper"
+  
+include BibleReferenceParser
+
+describe BibleMetadata do
+  before :all do
+    @matthew = "Matthew"
+  end
+  
+  it "should find the correct book for an all lower-cased name" do
+    info = BibleMetadata["matthew"]
+    info.should_not be_nil
+    info["name"].should eql @matthew
+  end                                                       
+  
+  it "should find the correct book for a title-cased name" do
+    info = BibleMetadata["Matthew"]
+    info.should_not be_nil
+    info["name"].should eql @matthew  
+  end 
+  
+  it "should find the correct book for an all upper-cased name" do
+    info = BibleMetadata["MATTHEW"]
+    info.should_not be_nil    
+    info["name"].should eql @matthew
+  end
+  
+  it "should find the correct book for an abbreviated name" do
+    info = BibleMetadata["matt"]
+    info.should_not be_nil
+    info["name"].should eql @matthew    
+  end
+  
+  it "should find the correct book for an abbreviated name with a period at the end" do
+    info = BibleMetadata["Matt."]
+    info.should_not be_nil
+    info["name"].should eql @matthew    
+  end
+  
+  it "should find the correct book for a name given with spaces" do
+    info = BibleMetadata["Song of Solomon"]
+    info.should_not be_nil
+    info["name"].should eql "Song of Solomon"    
+  end
+  
+  it "should find the correct book for a name beginning with a number" do
+    info = BibleMetadata["1 Samuel"]
+    info.should_not be_nil
+    info["name"].should eql "1 Samuel"    
+  end
+  
+  it "should return nil for a name that can't be found" do
+    info = BibleMetadata["anathema"]
+    info.should be_nil
+  end
+  
+  it "should return the book's name, short_name, number of chapters and an chapter info array" do
+    info = BibleMetadata["genesis"]
+    info.should_not be_nil
+    info["name"].should eql "Genesis"    
+    info["short_name"].should eql "Gen."
+    info["chapter_info"].should be_kind_of Array
+    info["chapter_info"].length.should eql 50
+  end
+
+end

data/spec/book_reference_spec.rb

@@ -0,0 +1,205 @@
+require 'spec_helper'
+
+include BibleReferenceParser
+
+describe BookReference do         
+  
+  it_should_behave_like "it tracks errors", BookReference.new("Matthew", "1:1")
+  
+  describe "initialization" do
+
+    it "should set the 'metadata' field" do
+      ref = BookReference.new "Genesis", "1:1"
+      ref.metadata.should_not be_nil
+      ref.metadata["name"].should eql "Genesis"
+    end
+    
+    context "for a valid book" do     
+      before :each do
+        @name = "Matthew"
+        @short_name = "Matt."
+        @raw = "1:1-10"
+        @ref = BookReference.new @name, @raw
+      end
+         
+      it "should set the 'name' field" do
+        @ref.name.should eql @name
+      end
+    
+      it "should set the 'short_name' field" do
+        @ref.short_name.should eql @short_name      
+      end   
+    
+      it "should set the 'raw_content' field" do
+        @ref.raw_content.should eql @raw
+      end
+    
+      it "should parse it's raw content" do
+        @ref.chapter_references.length.should eql 1
+        @ref.chapter_references.first.number.should eql 1
+      end 
+    end
+    
+    context "for an invalid book" do
+      before :each do
+        @ref = BookReference.new "anathema"
+      end
+      
+      it "should add a parsing error for an invalid book name" do
+        @ref.errors.first.should eql "The book 'anathema' could not be found"
+      end
+      
+      it "should not set the 'name' field" do
+        @ref.name.should be_nil
+      end
+      
+      it "should not set the 'short_name' field" do
+        @ref.short_name.should be_nil
+      end
+      
+      it "should not set the 'raw_content' field" do
+        @ref.raw_content.should be_nil
+      end
+      
+      it "should not parse its raw_content" do
+        @ref.chapter_references.should be_nil
+      end         
+    end
+  end
+  
+  describe "the valid_reference? method" do
+    it "should return true if the name is set" do
+      book = BookReference.new "Genesis"
+      book.should be_valid_reference
+    end
+    
+    it "should return false if the name is not set" do
+      book = BookReference.new "Genthesis"
+      book.should_not be_valid_reference
+    end
+  end
+  
+  describe "the 'parse_contents' method" do    
+    it "should set the chapter references" do
+      book = BookReference.new "Matthew", "1:1-10"
+      book.parse_contents     
+      book.chapter_references.should_not be_nil     
+    end
+  end
+  
+  describe "when parsing the books in a passage" do
+    
+    describe "the parse_books method" do
+      it "should correctly identify when there is only 1 book" do
+        books = BookReference.parse_books("Genesis 1:1")
+        books.length.should eql 1
+      end
+
+      it "should correctly identify when there are 2 books" do
+        books = BookReference.parse_books("Genesis 1:1, Exodus 1:1")
+        books.length.should eql 2    
+      end
+
+      it "should correctly identify when there are 10 books" do
+        passage = "Genesis 1:1, Exodus 1:1, Leviticus 1:1, Matthew 1:1, Mark 1:1,
+                   Luke 1:1;John 1:1;Rev. 1:1, 1 Sam 1:1, Prov 1:1"
+                   
+        books = BookReference.parse_books(passage)
+        books.length.should eql 10
+      end
+
+      it "should parse names beginning with a number" do
+        books = BookReference.parse_books("1 samuel 1:1, 2 samuel, 1cor 3, 2cor")
+        books.length.should eql 4 
+        books[0].name.should eql "1 Samuel"
+        books[1].name.should eql "2 Samuel"
+        books[2].name.should eql "1 Corinthians"
+        books[3].name.should eql "2 Corinthians"      
+      end
+
+      it "should correctly identify the raw_content for a book" do
+        books = BookReference.parse_books("Genesis 1:1-10, 25, 6:13; Exodus 5:14, Leviticus 1, James")
+        books[0].raw_content.should eql "1:1-10,25,6:13"
+        books[1].raw_content.should eql "5:14"
+        books[2].raw_content.should eql "1"   
+        books[3].raw_content.should be_nil
+      end
+
+      it "should correctly identify books and raw content in a complex passage, in the correct order" do
+        # Books should include Genesis, Mark, Proverbs, Isaiah, Revelation, Galatians, Exodus, Hebrews, 1 Samuel
+        passage = "Genesis 1:5-10, 11-15;25,;, Mark 10-21, 22,24,25, 28-32;prov2:2,\nisa9:9,rev10000,"
+        passage += "galatians, exod.12-19, 21,     22;25;28,32;29,,,, hebrews1:1-10002 1 samuel 10"      
+        books = BookReference.parse_books(passage)
+
+        books.length.should eql 9
+
+        books[0].name.should eql "Genesis"
+        books[0].raw_content.should eql "1:5-10,11-15;25"
+
+        books[1].name.should eql "Mark"
+        books[1].raw_content.should eql "10-21,22,24,25,28-32"
+
+        books[2].name.should eql "Proverbs"
+        books[2].raw_content.should eql "2:2"
+
+        books[3].name.should eql "Isaiah"
+        books[3].raw_content.should eql "9:9"
+
+        books[4].name.should eql "Revelation"
+        books[4].raw_content.should eql "10000"
+
+        books[5].name.should eql "Galatians"
+        books[5].raw_content.should be_nil
+
+        books[6].name.should eql "Exodus"
+        books[6].raw_content.should eql "12-19,21,22;25;28,32;29"
+
+        books[7].name.should eql "Hebrews"
+        books[7].raw_content.should eql "1:1-10002"
+
+        books[8].name.should eql "1 Samuel"
+        books[8].raw_content.should eql "10"
+      end
+    end
+    
+    describe "each returned book" do
+      it "should correctly set the name attribute" do
+         books = BookReference.parse_books("Matthew 1")
+         books.first.name.should eql "Matthew"
+      end
+        
+      it "should correctly set the raw_content attribute" do
+        books = BookReference.parse_books("Matthew 1:15, 2:2-20, 25")
+        books.first.raw_content.should eql "1:15,2:2-20,25"
+      end      
+    end
+    
+    describe "the returned value" do
+      it "should be a reference collection" do
+        books = BookReference.parse_books("Genesis 1:1-10, Mark 1")
+        books.should be_kind_of ReferenceCollection
+      end
+      
+      it "should only contain BookReference objects" do
+        books = BookReference.parse_books("Genesis 1:1-10, Mark 1")
+        books.each do |book|
+          book.should be_kind_of BookReference
+        end
+      end
+    end 
+      
+  end
+  
+  describe "the clean method" do                        
+    it "should call clean on it's chapter_references" do
+      book = BookReference.new "Genesis", "1:1, 51:1"
+      book.chapter_references.length.should eql 2
+      
+      book.clean
+      book.chapter_references.length.should eql 1
+      book.chapter_references.invalid_references.length.should eql 1      
+    end
+
+  end
+    
+end