bible_reference_parser 0.1.1

data/lib/bible_reference_parser/parser.rb

@@ -0,0 +1,24 @@
+# TODO doc me
+module BibleReferenceParser  
+  
+  # TODO doc me 
+  def self.parse(passage)
+    BookReference.parse_books(passage)
+  end
+
+  # See BookReference.parse_books    
+  def self.parse_books(passage)
+    BookReference.parse_books(passage)
+  end
+
+  # See ChapterReference.parse_chapters
+  def self.parse_chapters(passage)
+    ChapterReference.parse_chapters(passage)
+  end
+
+  # See VerseReference.parse_verses
+  def self.parse_verses(string)
+    VerseReference.parse_verses(string)
+  end 
+  
+end

data/lib/bible_reference_parser/reference/behavior/tracks_errors.rb

@@ -0,0 +1,46 @@
+module BibleReferenceParser
+  
+  # This module encapsulates shared behavior for classes that keep track of parsing errors. 
+  # For example, a BookReference may encounter a parsing error due to a book that doesn't
+  # exist. A ChapterReference may have a parsing error because the chapter number isn't valid 
+  # for the book it is referencing. 
+  module TracksErrors
+ 
+    def initialize(*args, &block) 
+      super
+   
+      # A collection of error messages.                         
+      @errors = []
+    end
+ 
+    # Add an error message.
+    def add_error(message)
+      @errors << message
+    end 
+    
+    # Erase all error messages.
+    def clear_errors
+      @errors = []
+    end
+   
+    # Get the list of error messages. This will include any errors in child references
+    # if include_child_errors is true (by default it's true).
+    def errors(include_child_errors = true)
+      if(include_child_errors && respond_to?("children") && children)
+        return @errors + children.errors(true)
+      end
+      
+      @errors
+    end
+
+    # Whether any errors occured when parsing.
+    def has_errors?
+      !errors.empty?
+    end
+
+    # Convienence method for the reverse of "has_errors?"
+    def no_errors?
+      errors.empty?
+    end     
+  end 
+end

data/lib/bible_reference_parser/reference/book_reference.rb

@@ -0,0 +1,168 @@
+module BibleReferenceParser
+ 
+  # This class handles parsing the books in a passage reference.
+  # 
+  # Each BookReference contains the book's name, short name (abbreviation), and a ReferenceCollection
+  # of chapters.
+  # 
+  # The main method of interest is BookReference.parse_books. This will 
+  # parse a passage and return a ReferenceCollection containing BookReference objects;
+  # one object for every book found in the passage. Example:                                                                     
+  # 
+  #     books = BookReference.parse_books("Matt. 1:1-10, Revelation 5:6-11, Luke 7:7")
+  #     books[0].name # => "Matthew"
+  #     books[1].short_name # => "Rev."
+  #     books[2].name # => "Luke"
+  # 
+  # Access the chapter references found through the chapter_references method:
+  # 
+  #     books.chapter_references
+  #     books.children # => alias for chapter_references
+  #
+  # You can see if there were any errors in parsing by checking the "has_errors?" method on the returned
+  # ReferenceCollection. Example:
+  # 
+  #     books = BookReference.parse_books("Gethensis 1:1, Matthew 1:5000")
+  #     books.has_errors? # => true
+  #     books.no_errors? # => false
+  #     books.errors # => ["The book 'Genthesis' could not be found", "The verse '5000' does not exist for Matthew 1"]
+  # 
+  # You can check if an individiual BookReference has errors as well:
+  # 
+  #     books = BookReference.parse_books("Gethensis 1:1, Matthew 1:5000")
+  #     books.first.has_errors? # => true
+  #     books.first.errors # => ["The book 'Genthesis' could not be found"]
+  
+  class BookReference
+    include TracksErrors
+    
+    attr_reader :name, :short_name, :raw_content, :chapter_references, :metadata
+    
+    alias :children :chapter_references  
+     
+    # Instance Initialization
+    #----------------------------------------------------------------------------
+    
+    # Initializes a new BookReference object. If the book cannot be found, a parsing error will occur.
+    # 
+    # Parameters:
+    # book_name   - can be either the full name or the abbreviation.
+    # raw_content - the raw string of chapters/verses selected for this book reference (ex. "1:1-10").                    
+    def initialize(book_name, raw_content = nil)
+      super
+            
+      # get the metadata for the given book name
+      @metadata = BibleMetadata[book_name]
+      
+      # if the book doesn't exist add a parsing error and stop processing
+      if @metadata.nil?
+        add_error "The book '#{book_name}' could not be found" and return
+      end
+      
+      # name of the book, ex. Genesis
+      @name = metadata["name"]
+      
+      # abbreviated name of the book, ex. Gen.
+      @short_name = metadata["short_name"]
+      
+      # the string representing the chapters/verses for this reference, ex. "1:1-10"
+      @raw_content = raw_content
+      
+      parse_contents
+    end 
+     
+        
+    # Class Methods
+    #----------------------------------------------------------------------------           
+                               
+    # Parse the books in a passage. Returns a ReferenceCollection of BookReference objects.
+    # 
+    # Parameters:
+    # passage - The passage to parse, ex. "Genesis 1:1-10, Exodus 1:5-7"
+    # 
+    # Example:
+    # 
+    #     books = BookReference.parse_books("Genesis 1:1-10, mark 1:5-7")
+    #     books.first.name # => "Genesis"  
+    # 
+    # The above example will return a ReferenceCollection of two BookReference objects, one for
+    # each book identified in the passage.
+    # 
+    # More Examples:
+    # 
+    #     Book.parse_books("Matt 1")
+    #     Book.parse_books("Gen. 1-5, Ex. 7:14")
+    #     Book.parse_books("Genesis 1:1-15, 2:12, Exod. 7:14")
+    #     Book.parse_books("gen 5, exodus") # => will assume Exodus 1
+    #     Book.parse_books("gen. 1-5, gen 9:1") # => two different references to genesis 
+    #     Book.parse_books("[rev1:15][daniel  12: 1]") # => white space and unnecessary punctuation is ignored
+    def self.parse_books(passage)
+
+      books = ReferenceCollection.new
+      
+      # remove everything except for numbers, letters and these punctuation marks -> -,;:    
+      passage_slim = passage.gsub(/[^0-9a-zA-Z:;,\-]/, "")
+                       
+      # This pattern matches for book name and chapter/verses pairs. It consists of two capture groups:
+      # 
+      # Group 1: Book's name ([0-9]?[a-zA-Z]+)      
+      # - An optional digit. Some books like "1 Samuel" begin with a single digit.
+      # - Any letter, one or more times.
+      #  
+      # Group 2: Chapters and verses ([^a-zA-Z]+(?![a-zA-Z]))?
+      # - Any non-letter character (like digits and punctuation) one or more times.
+      # 
+      # - Don't capture the last character if it's followed by a letter. Which basically means
+      #   don't capture the last character. Usually the last character will be punctuation, like
+      #   a comma or semi-colon. We don't need to capture that information. Sometimes it will
+      #   be a number, like in "Matt. 1:1, 2 Sam 1:1", where "2" would be the last character.
+      #   In this case we want to assume the last character belongs with the next book anyway,
+      #   so we shouldn't include it with this one. 
+      # 
+      # - The last question mark indicates that the chapters/verses are optional. If it's not 
+      #   there, then we assume just the first chapter is wanted. So the passage 
+      #   "John", is the same as "John 1". This assumption comes
+      #   from what BibleGateway does for the same scenario. 
+      pattern = /([0-9]?[a-zA-Z]+)([^a-zA-Z]+(?![a-zA-Z]))?/
+                                                                      
+      # find the books
+      passage_slim.scan pattern do |book_name, contents|
+        
+        # remove all characters from the end util we get to a number.
+        # This basically removes any extraneous punctation at the end.        
+        contents = contents.gsub(/[^0-9]+$/, "") unless contents.nil?
+                
+        books << BookReference.new(book_name, contents)     
+      end
+     
+      books
+    end   
+    
+    
+    # Instance Methods
+    #----------------------------------------------------------------------------    
+    
+    # Whether this reference itself is valid. Please note this does not consider the chapters inside
+    # the book, just the book itself.
+     def valid_reference?
+       !name.nil?
+     end 
+     
+     # Parse the raw_content in order to find the chapters in this book.
+     def parse_contents
+       @chapter_references = ChapterReference.parse_chapters_in_reference self
+     end
+     
+    # Cleans invalid chapter references. After calling this, the chapter_references method will only return good
+    # chapter references. You can access the invalid references through chapater_references.invalid_references. 
+    # See ReferenceCollection.clean for more information.
+    # 
+    # If the chain parameter is true (which it is by default) it will also tell valid chapters
+    # to clean their verse references. In this case chapter_references.invalid_references will include both bad
+    # chapters and bad verses.
+    def clean(chain = true)            
+      chapter_references.clean(chain)
+    end
+       
+  end
+end

data/lib/bible_reference_parser/reference/chapter_reference.rb

@@ -0,0 +1,242 @@
+module BibleReferenceParser
+  # This class handles the parsing of chapters in a passage or string.
+  # 
+  # Each ChapterReference object contains the chapter number and a ReferenceCollection of
+  # verses.
+  # 
+  # The main method of interest is ChapterReference.parse_chapters. This will parse a passage
+  # or string and return a ReferenceCollection of ChapterReference objects. One object for 
+  # each chapter identified. Example:
+  # 
+  #     chapters = ChapterReference.parse_chapters("1:1-10, 5:6")
+  #     chapters[0].number # => 1
+  #     chapters[1].number # => 5
+  #
+  # Although less useful, parse_chapters can even parse just the chapters in a complete passage:
+  # 
+  #     chapters = ChapterReference.parse_chapters("Genesis 1:1-10, Mark 5:6")
+  #     chapters[0].number # => 1
+  #     chapters[1].number # => 5 
+  #
+  # 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"]),
+  # The ChapterReference will add an error message if the chapter doesn't exist for the book.
+  # 
+  # If you want to parse chapters for a particular book, its better to use the 
+  # parse_chapters_in_reference method. This method takes an existing book reference. 
+  # Example:
+  # 
+  #     book = BookReference.new("Genesis", "1:1000, 51:10")
+  #     chapters = ChapterReference.parse_chapters_in_reference(book)
+  #     chapters.has_errors? # => true
+  #     chapters.no_errors? # => false
+  #     chapters.errors # => ["The verse '1000' does not exist for Genesis 1",
+  #                           "Chapter '51' does not exist for the book Genesis"]
+  #
+  # You can check if an individiual ChapterReference has errors as well:
+  # 
+  #     book = BookReference.new("Genesis", "1:1000, 51:10")
+  #     chapters = ChapterReference.parse_chapters_in_reference(book)
+  #     chapters.first.has_errors? # => true
+  #     chapters.first.no_errors # => false
+  #     chapters.first.errors # => ["The verse '1000' does not exist for Genesis 1"]
+  
+  class ChapterReference 
+    include TracksErrors
+    
+    attr_reader :number, :raw_content, :verse_references, :metadata 
+    
+    alias :children :verse_references
+    
+    # Instance Initialization
+    #----------------------------------------------------------------------------
+    
+    # Initializes a new ChapterReference object.
+    #
+    # Parameters:
+    # number        - The chapter number. Can either be an string or integer
+    # raw_content   - A string representing the verses referenced, ex. "1-10"
+    # metadata      - (optional) An array of metadata information for a particular
+    #                 book, ex. BibleMetadata["Genesis"]. This is used to check if
+    #                 the chapter number is valid for a book.
+    def initialize(number, raw_content = nil, metadata = 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 chapter number '#{number}' is not valid" and return
+      end
+      
+      # metadata info for a particular book in the bible
+      @metadata = metadata
+      
+      # if the metadata is given, we can verify if the chapter exists for the book
+      unless @metadata.nil?        
+        total_chapters_in_book = @metadata["chapter_info"].length
+        
+        if number > total_chapters_in_book
+          add_error "Chapter '#{number}' does not exist for the book #{@metadata['name']}" and return
+        end
+      end        
+      
+      # The chapter number
+      @number = number
+      
+      # The string representing the verses referenced in this chapter    
+      @raw_content = raw_content
+      
+      parse_contents      
+    end
+    
+    # Class Methods
+    #----------------------------------------------------------------------------        
+                                                          
+    # Works similar to parse_chapters, however this should be used instead if you want
+    # to associate the chapter references with a book. This will decide what chapters 
+    # are referenced based on the raw_content of the book reference. If the raw_content
+    # is nil, it will assume only the first chapter is desired.
+    def self.parse_chapters_in_reference(book_reference)
+      if book_reference.raw_content.nil?                          
+        # if the raw_content is nil, assume we want just the first chapter. This is what
+        # Bible Gateway does if you just give a book name.
+        return self.parse_chapters(1, book_reference.metadata)        
+      else
+        return self.parse_chapters(book_reference.raw_content, book_reference.metadata)        
+      end
+    end
+    
+    # Parse the chapters in a passage or string. Returns a ReferenceCollection
+    # of ChapterReference objects.
+    # 
+    # Parameters:
+    # passage         - The passage to parse, ex. "1:1-10, 2:5-7"
+    # 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. 
+    # 
+    # Example:
+    # 
+    #     chapters = ChapterReference.parse_chapters("1:1-10, 2:5-7")
+    #     chapters.first.number # => 1
+    # 
+    # This can also parse just the chapters in a whole passage. It will ignore the book names:
+    # 
+    #     chapters = ChapterReference.parse_chapters("Genesis 1:1-10; mark 1:5-7")
+    #     chapters.first.number # => 1
+    #
+    # More Examples:
+    # 
+    #     ChapterReference.parse_chapters("1:1")
+    #     ChapterReference.parse_chapters("1:1-10")
+    #     ChapterReference.parse_chapters("1:1-10; 5-10")
+    #     ChapterReference.parse_chapters("1:5,8,11; 2:10, 5-20")
+    #     ChapterReference.parse_chapters(10)
+    # 
+    # XXX allow option to remove duplicate chapters
+    def self.parse_chapters(passage, metadata = nil)
+      passage = passage.to_s # allows for integer passage
+      
+      chapters = ReferenceCollection.new
+      
+      # ~ Do some massaging of the data before we scan it...
+      
+      # Replace letters with a semi-colon. We would just remove all letters, but in cases
+      # where books are separated by just a space, it will cause errors. For example
+      # "Genesis 1 Exodus 1" would end up as "11".
+      passage = passage.gsub(/[a-zA-Z]+/, ";") 
+      
+      # Next remove everything except for numbers and these punctuation marks -> -,;:
+      # We don't care about spaces or any other characters.   
+      passage = passage.gsub(/[^0-9:;,\-]/, "")
+      
+      # Finally insert a semi-colon before digits that precede a colon. This is for chapters
+      # that reference specific verses, like "15:1". Semi-colons are used to indicate
+      # the following sequence is separate from the preceding sequence. This is important
+      # for back-to-back chapters with verses, ex. "1:5,10,5:10". Here we want chapter 1
+      # verses 5 and 10, then chapter 5 verse 10. The way we know it's not chapter 1 verse
+      # 5, 10, and 5 is if there is a semi-colon there: "1:5,10,;5:10".
+      passage = passage.gsub(/[0-9]+:/, ';\0')
+      
+      # This will look for digits followed by a semi-colon. If we match that,
+      # we know what's before the colon is the chapter, and we know every digit or dash
+      # directly after it are the verses.       
+      match_chapter_with_verses = /([0-9]+:)([0-9,\-]+)/
+      
+      # This will match a chapter range, like "1-10"
+      match_chapter_range = /([0-9]+\-[0-9]+)/
+      
+      # This will match a single chapter selection that doesn't specify any verses.
+      # Something like "Genesis 1, 2" tells us we want chapters 1 and chapter 2. 
+      # It looks for any digits directly followed by an optional comma or semi-colon. 
+      # It's optional because it won't be there if it's the last or only chapter.
+      match_single_chapter = /([0-9]+[,;]?)/
+      
+      # First try to match the chapter with verses, then the chapter range, then finally the single chapter
+      pattern = Regexp.union(match_chapter_with_verses, match_chapter_range, match_single_chapter)
+      
+      # Let's find the chapters already!
+      passage.scan pattern do |with_verses, verses, chapter_range, without_verses|
+       
+        if chapter_range
+          # get the beginning and end of the range
+          range = chapter_range.split "-"
+          first = range.first.to_i
+          last = range.last.to_i
+          
+          # add each chapter in the range
+          (first..last).each do |number|
+            chapters << ChapterReference.new(number, nil, metadata)
+          end
+        else
+          number = with_verses ? with_verses.to_i : without_verses.to_i
+          
+          # remove all characters from the end util we get to a number.
+          # This basically removes any extraneous punctation at the end.        
+          verses = verses.gsub(/[^0-9]+$/, "") unless verses.nil?
+          
+          chapters << ChapterReference.new(number, verses, metadata)      
+        end
+      end
+      
+      chapters      
+    end                                  
+    
+    # Instance Methods
+    #----------------------------------------------------------------------------
+    
+    # Whether this reference itself is valid. Please note this does not consider the verses inside
+    # the chapter, just the chapter itself.
+    def valid_reference?
+      !number.nil?
+    end
+    
+    # Parse the raw_content in order to find the verses referenced for this chapter. 
+    def parse_contents
+      @verse_references = VerseReference.parse_verses_in_reference self
+    end
+    
+    # Cleans invalid verse references. After calling this, the verse_references method will only return good
+    # verse references. You can access the invalid references through verse_references.invalid_references. 
+    # See ReferenceCollection.clean for more information.
+    # 
+    # If the chain parameter is true (which it is by default) it will also tell valid verses to do a clean. 
+    # Since verses are leaf-nodes so to speak, they don't contain any references to clean so it won't do anything.
+    def clean(chain = true)
+      verse_references.clean(chain)
+    end
+    
+    # TODO write specs
+    # Get an array of ints containing the verse numbers referenced
+    def verse_numbers  
+      verses = []
+      @verse_references.each do |ref|
+        verses << ref.number
+      end
+      verses
+    end
+
+  end  
+end