pericope 0.5.4 → 0.6.0

data/README.mdown

@@ -1,13 +1,62 @@
-Pericope
-========
+# Pericope
 
-Introduction goes here.
+Pericope is a gem for parsing Bible references.
 
+It recognizes common abbreviations and misspellings for names of the books of the Bible and a variety of ways of denoting ranges of chapters and verses. It can parse pericopes singly or out of a block of text. It's useful for comparing two pericopes for intersection and normalizing them into a well-formatted string.
 
-Example
-=======
+# Examples
 
-Example goes here.
+### Recognize common abbreviations and misspellings for names of the books of the Bible
 
+```ruby
+  Pericope.new("ps 118:17").to_s # => Psalm 118:17
+  Pericope.new("jas 3:1-5").to_s # => James 3:1-5
+  Pericope.new("1 jn 4:4").to_s  # => 1 John 4:4
+```
 
-Copyright (c) 2009 [name of plugin creator], released under the MIT license
+### Compare two pericopes to see if they intersect
+
+```ruby
+  a = Pericope.new("Mark 13:1-6")
+  b = Pericope.new("Mark 13:5")
+  c = Pericope.new("Mark 13:6, 7")
+  
+  a.intersects?(b) # => true
+  a.intersects?(c) # => true
+  b.intersects?(c) # => false
+```
+
+### Parse pericopes out of a block of text
+
+```ruby
+  text = <<-TEXT
+  If then, the Word is so significant, great important attaches to its exact form. It has the form of a promise as in Isaiah 43:1: "Do not fear, for I have redeemed you; I have called you by name, you are mine," or as in Luke 2:10-11, "Do not be afraid..to you is born this day...a Savior." (Bayer, p51)
+  TEXT
+  
+  Pericope.parse(text) # => [Isaiah 43:1, Luke 2:10-11]
+  
+  Pericope.split(text) # => ["  If then, the Word is so significant, great important attaches to its exact form. It has the form of a promise as in ", Isaiah 43:1, ": \"Do not fear, for I have redeemed you; I have called you by name, you are mine,\" or as in ", Luke 2:10-11, ", \"Do not be afraid..to you is born this day...a Savior.\" (Bayer, p51)\n"]
+```
+
+### Converts pericopes into arrays of verses and reconstructs them from arrays of verses
+
+```ruby
+  array = Pericope.new("gen 1:1-3").to_a # => [1001001, 1001002, 1001003]
+  Pericope.new(array) # => Genesis 1:1-3
+```
+
+
+# History
+
+# 0.6.0
+
+ - Removed the `index` attribute
+ - Deprecated the `pattern` argument to the method `Pericope.split(text, pattern=nil)`
+ - Improved performance by 2x
+ - Added this README
+ - Fixed a bug with parsing inverted [invalid] ranges (e.g. Mark 3-1)
+
+
+# License
+
+Copyright (c) 2012 Bob Lail, released under the MIT license

data/data/book_abbreviations.txt

@@ -1,5 +1,5 @@
 1	genesis	gen?	gn
-2	exodus	exo?d?	ex	
+2	exodus	exo?d?	ex
 3	leviticus	le?v	levi	le
 4	numbers?	nu?m	nu	numb
 5	deuteronomy	deut?	dt

data/lib/pericope.rb

@@ -1,70 +1,75 @@
 # encoding: UTF-8
 
-require 'yaml'
 require 'pericope/version'
 
 class Pericope
   attr_reader :book,
               :book_chapter_count,
               :book_name,
-              :index,
               :original_string,
               :ranges
   
   
   def self.book_names
-    @@book_names ||= ["Genesis", "Exodus", "Leviticus", "Numbers", "Deuteronomy", "Joshua", "Judges", "Ruth", "1 Samuel", "2 Samuel", "1 Kings", "2 Kings", "1 Chronicles", "2 Chronicles", "Ezra", "Nehemiah", "Esther", "Job", "Psalm", "Proverbs", "Ecclesiastes", "Song of Songs", "Isaiah", "Jeremiah", "Lamentations", "Ezekiel", "Daniel",  "Hosea", "Joel", "Amos", "Obadiah", "Jonah", "Micah", "Nahum", "Habakkuk", "Zephaniah", "Haggai", "Zechariah", "Malachi", "Matthew", "Mark", "Luke", "John", "Acts", "Romans", "1 Corinthians", "2 Corinthians", "Galatians", "Ephesians", "Philippians", "Colossians", "1 Thessalonians", "2 Thessalonians", "1 Timothy", "2 Timothy", "Titus", "Philemon", "Hebrews", "James", "1 Peter", "2 Peter", "1 John ", "2 John", "3 John", "Jude", "Revelation"]
+    @book_names ||= ["Genesis", "Exodus", "Leviticus", "Numbers", "Deuteronomy", "Joshua", "Judges", "Ruth", "1 Samuel", "2 Samuel", "1 Kings", "2 Kings", "1 Chronicles", "2 Chronicles", "Ezra", "Nehemiah", "Esther", "Job", "Psalm", "Proverbs", "Ecclesiastes", "Song of Songs", "Isaiah", "Jeremiah", "Lamentations", "Ezekiel", "Daniel",  "Hosea", "Joel", "Amos", "Obadiah", "Jonah", "Micah", "Nahum", "Habakkuk", "Zephaniah", "Haggai", "Zechariah", "Malachi", "Matthew", "Mark", "Luke", "John", "Acts", "Romans", "1 Corinthians", "2 Corinthians", "Galatians", "Ephesians", "Philippians", "Colossians", "1 Thessalonians", "2 Thessalonians", "1 Timothy", "2 Timothy", "Titus", "Philemon", "Hebrews", "James", "1 Peter", "2 Peter", "1 John ", "2 John", "3 John", "Jude", "Revelation"]
   end
   
   def self.book_name_regexes
-    @@book_name_regexes ||= begin
-      book_abbreviations.map do |book|
-        [book, Regexp.new("\\b#{book[1]}\\b.? (#{ValidReference})", true)]
-      end
-    end
+    @book_name_regexes ||= book_abbreviations.map { |book_number, book_regex| [book_number, /\b#{book_regex}\b/] }
   end
   
   
   
-  def initialize(string_or_array)
-    case string_or_array
-    when String, MatchData
-      match = string_or_array.is_a?(String) ? Pericope.match_one(string_or_array) : string_or_array
-      raise "no pericope found in #{string_or_array} (#{string_or_array.class})" if match.nil?
+  def initialize(arg)
+    case arg
+    when String
+      attributes = Pericope.match_one(arg)
+      raise "no pericope found in #{arg} (#{arg.class})" if attributes.nil?
       
-      @original_string = match.to_s
-      @index = match.begin(0)
-      set_book match.instance_variable_get('@book')
-      @ranges = parse_reference(match[1])
+      @original_string = attributes[:original_string]
+      set_book attributes[:book]
+      @ranges = attributes[:ranges]
       
     when Array
-      set_book Pericope.get_book(string_or_array.first)
-      @ranges = Pericope.group_array_into_ranges(string_or_array)
+      set_book Pericope.get_book(arg.first)
+      @ranges = Pericope.group_array_into_ranges(arg)
       
     else
-      raise ArgumentError, "#{string_or_array.class} is not a recognized input for pericope"
+      attributes = arg
+      @original_string = attributes[:original_string]
+      set_book attributes[:book]
+      @ranges = attributes[:ranges]
+      
     end
   end
   
   
   
+  def self.book_has_chapters?(book)
+    book_chapter_counts[book - 1] > 1
+  end
+  
   def book_has_chapters?
-    (book_chapter_count > 1)
+    book_chapter_count > 1
   end
   
   
   
+  # Differs from Pericope.new in that it won't raise an exception
+  # if text does not contain a pericope but will return nil instead.
   def self.parse_one(text)
-    match = match_one(text)
-    match ? Pericope.new(match) : nil
+    parse(text) do |pericope|
+      return pericope
+    end
+    nil
   end
   
   
   
-  def self.parse(text, &block)
+  def self.parse(text)
     pericopes = []
-    match_all text do |match|
-      pericope = Pericope.new(match)
+    match_all(text) do |attributes|
+      pericope = Pericope.new(attributes)
       if block_given?
         yield pericope
       else
@@ -77,23 +82,47 @@ class Pericope
   
   
   def self.split(text, pattern=nil)
-    matches = match_all(text) # find every pericope in the text
-    matches = matches.sort {|a,b| a.begin(0) <=> b.begin(0)} # put them in the order of their occurrence
-    
+    puts "DEPRECATION NOTICE: split will no longer accept a 'pattern' argument in Pericope 0.7.0" if pattern
     segments = []
     start = 0
-    for match in matches
+    
+    match_all(text) do |attributes, match|
+      
       pretext = text.slice(start...match.begin(0))
-      segments.concat(pattern ? pretext.split(pattern).delete_if{|s| s.length==0} : [pretext]) if (pretext.length>0)
-      segments << Pericope.new(match)
+      if pretext.length > 0
+        segments << pretext
+        yield pretext if block_given?
+      end
+      
+      pericope = Pericope.new(attributes)
+      segments << pericope
+      yield pericope if block_given?
+      
       start = match.end(0)
     end
+    
     pretext = text.slice(start...text.length)
-    segments.concat(pattern ? pretext.split(pattern).delete_if{|s| s.length==0} : [pretext]) if (pretext.length>0)
+    if pretext.length > 0
+      segments << pretext
+      yield pretext if block_given?
+    end
     
+    segments = ___split_segments_by_pattern(segments, pattern) if pattern
     segments
   end
   
+  def self.___split_segments_by_pattern(segments, pattern)
+    segments2 = []
+    segments.each do |segment|
+      if segment.is_a? Pericope
+        segments2 << segment
+      else
+        segments2.concat(segment.split(pattern))
+      end
+    end
+    segments2
+  end
+  
   
   
   def self.extract(text)
@@ -149,19 +178,19 @@ class Pericope
   def to_a
     # one range per chapter
     chapter_ranges = []
-    for range in ranges
-      min_chapter = Pericope.get_chapter(range.min)
-      max_chapter = Pericope.get_chapter(range.max)
-      if (min_chapter==max_chapter)
+    ranges.each do |range|
+      min_chapter = Pericope.get_chapter(range.begin)
+      max_chapter = Pericope.get_chapter(range.end)
+      if min_chapter == max_chapter
         chapter_ranges << range
       else
-        chapter_ranges << Range.new(range.min, Pericope.get_last_verse(book, min_chapter))
+        chapter_ranges << Range.new(range.begin, Pericope.get_last_verse(book, min_chapter))
         for chapter in (min_chapter+1)...max_chapter
           chapter_ranges << Range.new(
             Pericope.get_first_verse(book, chapter),
             Pericope.get_last_verse(book, chapter))
         end
-        chapter_ranges << Range.new(Pericope.get_first_verse(book, max_chapter), range.max)
+        chapter_ranges << Range.new(Pericope.get_first_verse(book, max_chapter), range.end)
       end
     end
     
@@ -172,19 +201,17 @@ class Pericope
   
   def well_formatted_reference
     recent_chapter = nil # e.g. in 12:1-8, remember that 12 is the chapter when we parse the 8
-    recent_chapter = 1 if !self.book_has_chapters?
+    recent_chapter = 1 unless book_has_chapters?
     ranges.map do |range|
-      min_chapter = Pericope.get_chapter(range.min)
-      min_verse = Pericope.get_verse(range.min)
-      max_chapter = Pericope.get_chapter(range.max)
-      max_verse = Pericope.get_verse(range.max)
+      min_chapter = Pericope.get_chapter(range.begin)
+      min_verse = Pericope.get_verse(range.begin)
+      max_chapter = Pericope.get_chapter(range.end)
+      max_verse = Pericope.get_verse(range.end)
       s = ""
       
-      if (min_verse==1) and (max_verse>=Pericope.get_max_verse(book, max_chapter))
+      if min_verse == 1 and max_verse >= Pericope.get_max_verse(book, max_chapter)
         s << min_chapter.to_s
-        if max_chapter > min_chapter
-          s << "-#{max_chapter}"
-        end
+        s << "-#{max_chapter}" if max_chapter > min_chapter
       else
         if recent_chapter == min_chapter
           s << min_verse.to_s
@@ -214,12 +241,14 @@ class Pericope
   def intersects?(pericope)
     return false unless pericope.is_a?(Pericope)
     return false unless (self.book == pericope.book)
-    for self_range in self.ranges
-      for other_range in pericope.ranges
-        return true if (self_range.max >= other_range.min) and (self_range.min <= other_range.max)
+    
+    self.ranges.each do |self_range|
+      pericope.ranges.each do |other_range|
+        return true if (self_range.end >= other_range.begin) and (self_range.begin <= other_range.end)
       end
     end
-    return false
+    
+    false
   end
   
   
@@ -241,23 +270,8 @@ private
   
   def set_book(value)
     @book = value || raise(ArgumentError, "must specify book")
-    @book_name = Pericope.book_names[@book-1]
-    @book_chapter_count = Pericope.book_chapter_counts[@book-1]    
-  end
-  
-  
-  
-  def parse_reference(reference)
-    reference = normalize_reference(reference)
-    (reference.nil? || reference.empty?) ? [] : parse_ranges(reference.split(/[,;]/))
-  end
-  
-  def normalize_reference(reference)
-    [ [%r{(\d+)[".](\d+)},'\1:\2'],       # 12"5 and 12.5 -> 12:5
-      [%r{(–|—)},'-'],                     # convert em dash and en dash to -
-      [%r{[^0-9,:;\-–—]},'']              # remove everything but [0-9,;:-]
-    ].each { |pattern, replacement| reference.gsub!(pattern, replacement) }
-    reference
+    @book_name = Pericope.book_names[@book - 1]
+    @book_chapter_count = Pericope.book_chapter_counts[@book - 1]
   end
   
   
@@ -352,8 +366,8 @@ private
   
   # matches the first valid Bible reference in the supplied string
   def self.match_one(text)
-    match_all(text) do |match|
-      return match
+    match_all(text) do |attributes|
+      return attributes
     end
     nil
   end
@@ -361,41 +375,63 @@ private
   
   
   # matches all valid Bible references in the supplied string
-  # ! will not necessarily return references in order !
-  def self.match_all(text, &block)
-    matches = []
-    unmatched = text
-    
-    for book_regex in book_name_regexes
-      rx = book_regex[1]
-      while (match = unmatched.match rx) # find all occurrences of pericopes in this book
-        length = match.end(0) - match.begin(0)
-        
-        # after matching "2 Peter" don't match "Peter" again as "1 Peter"
-        # but keep the same number of characters in the string so indices work
-        unmatched = match.pre_match + ("*" * length) + match.post_match
-        match.instance_variable_set('@book', book_regex[0][0])
-        if block_given?
-          yield match
-        else
-          matches << match
-        end
-      end
+  def self.match_all(text)
+    text.scan(Pericope::PERICOPE_PATTERN) do
+      match = Regexp.last_match
+      
+      book = recognize_book(match[1])
+      next unless book
+      
+      ranges = parse_reference(book, match[2])
+      next if ranges.empty?
+      
+      attributes = {
+        :original_string => match.to_s,
+        :book => book,
+        :ranges => ranges
+      }
+      
+      yield attributes, match
     end
-    block_given? ? text : matches
   end
   
+  def self.recognize_book(book)
+    book = book.to_s.downcase
+    book_name_regexes.each do |book_regex|
+      return book_regex[0] if book =~ book_regex[1]
+    end
+    nil
+  end
+  
+  def self.parse_reference(book, reference)
+    reference = normalize_reference(reference)
+    (reference.nil? || reference.empty?) ? [] : parse_ranges(book, reference.split(/[,;]/))
+  end
   
+  def self.normalize_reference(reference)
+    [ [%r{(\d+)[".](\d+)},'\1:\2'],       # 12"5 and 12.5 -> 12:5
+      [%r{(–|—)},'-'],                     # convert em dash and en dash to -
+      [%r{[^0-9,:;\-–—]},'']              # remove everything but [0-9,;:-]
+    ].each { |pattern, replacement| reference.gsub!(pattern, replacement) }
+    reference
+  end
   
-  def parse_ranges(ranges)
+  def self.parse_ranges(book, ranges)
     recent_chapter = nil # e.g. in 12:1-8, remember that 12 is the chapter when we parse the 8
-    recent_chapter = 1 if !self.book_has_chapters?
+    recent_chapter = 1 if !book_has_chapters?(book)
     ranges.map do |range|
       range = range.split('-') # parse the low end of a verse range and the high end separately
       range << range[0] if (range.length < 2) # treat 12:4 as 12:4-12:4
       lower_chapter_verse = range[0].split(':').map(&:to_i) # parse "3:28" to [3,28]
       upper_chapter_verse = range[1].split(':').map(&:to_i) # parse "3:28" to [3,28]
       
+      # treat Mark 3-1 as Mark 3-3 and, eventually, Mark 3:1-35
+      if (lower_chapter_verse.length == 1) &&
+         (upper_chapter_verse.length == 1) &&
+         (upper_chapter_verse[0] < lower_chapter_verse[0])
+        upper_chapter_verse = lower_chapter_verse.dup
+      end
+      
       # make sure the low end of the range and the high end of the range
       # are composed of arrays with two appropriate values: [chapter, verse]
       chapter_range = false
@@ -435,10 +471,14 @@ private
   
   
   def self.load_chapter_verse_counts
-    path = File.expand_path(File.dirname(__FILE__) + "/../data/chapter_verse_count.yml")
+    path = File.expand_path(File.dirname(__FILE__) + "/../data/chapter_verse_count.txt")
+    chapter_verse_counts = []
     File.open(path) do |file|
-      return YAML.load(file)
+      file.each do |text|
+        chapter_verse_counts << text.chomp.split("\t")[0..1].map(&:to_i)
+      end
     end
+    Hash[chapter_verse_counts]
   end
   
   
@@ -459,7 +499,7 @@ private
         end
       end
     end
-    book_abbreviations
+    Hash[book_abbreviations]
   end
   
   
@@ -471,13 +511,13 @@ private
   
   
   def self.book_abbreviations
-    @@book_abbreviations ||= load_book_abbreviations
+    @book_abbreviations ||= load_book_abbreviations
   end
   
   
   
   def self.book_chapter_counts
-    @@book_chapter_counts ||= [
+    @book_chapter_counts ||= [
     # Chapters    Book Name        Book Number
       50,       # Genesis          1
       40,       # Exodus           2
@@ -547,9 +587,12 @@ private
       22]       # Revelation      66
   end
   
-  ValidReference = begin
-    reference = '((\s*\d{1,3})(\s*[:\"\.]\s*\d{1,3}(a|b)?(\s*(,|;)\s*(\d{1,3}[:\"\.])?\s*\d{1,3}(a|b)?)*)?(\s*(-|–|—)\s*(\d{1,3}\s*[:\"\.])?(\d{1,3}(a|b)?)(\s*(,|;)\s*(\d{1,3}\s*[:\"\.])?\s*\d{1,3}(a|b)?)*)*)'
-  end
+  
+  BOOK_PATTERN = /\b(?:(?:1|2|3|i+|first|second|third|1st|2nd|3rd) )?(?:\w+| of )\b/
+  
+  REFERENCE_PATTERN = '(?:\s*\d{1,3})(?:\s*[:\"\.]\s*\d{1,3}[ab]?(?:\s*[,;]\s*(?:\d{1,3}[:\"\.])?\s*\d{1,3}[ab]?)*)?(?:\s*[-–—]\s*(?:\d{1,3}\s*[:\"\.])?(?:\d{1,3}[ab]?)(?:\s*[,;]\s*(?:\d{1,3}\s*[:\"\.])?\s*\d{1,3}[ab]?)*)*'
+  
+  PERICOPE_PATTERN = /(#{BOOK_PATTERN})\.? (#{REFERENCE_PATTERN})/i