bible_bot 2.0.0

data/lib/bible_bot/book.rb

@@ -0,0 +1,80 @@
+module BibleBot
+  # Represents one of the 66 books in the bible (Genesis - Revelation).
+  # You should never need to initialize a Book, they are initialized in {Bible}.
+  class Book
+    attr_reader :id # @return [Integer]
+    attr_reader :name # @return [String]
+    attr_reader :abbreviation # @return [String]
+    attr_reader :regex # @return [String]
+    attr_reader :chapters # @return [Array<Integer>]
+    attr_reader :testament # @return [String]
+
+    # Uses the same Regex pattern to match as we use in {Reference.parse}.
+    # So this supports the same book name abbreviations.
+    #
+    # @param name [String]
+    # @return [Book]
+    # @example
+    #   Book.find_by_name("Genesis")
+    def self.find_by_name(name)
+      return nil if name.nil? || name.strip == ""
+
+      Bible.books.find { |book| name.match(Regexp.new('\b'+book.regex+'\b', Regexp::IGNORECASE)) }
+    end
+
+    # Find by the Book ID defined in {Bible}.
+    #
+    # @param id [Integer]
+    # @return [Book]
+    def self.find_by_id(id)
+      Bible.books.find { |book| book.id == id }
+    end
+
+    def initialize(id:, name:, abbreviation:, regex:, chapters: [] , testament:)
+      @id = id
+      @name = name
+      @abbreviation = abbreviation
+      @regex = regex
+      @chapters = chapters
+      @testament = testament
+    end
+
+    # @return [String]
+    def formatted_name
+      case name
+      when 'Psalms' then 'Psalm'
+      else name
+      end
+    end
+
+    # Single chapter book like Jude
+    # @return [Boolean]
+    def single_chapter?
+      chapters.length == 1
+    end
+
+    # A reference containing the entire book
+    # @return [Reference]
+    def reference
+      @reference ||= Reference.new(start_verse: start_verse, end_verse: end_verse)
+    end
+
+    # @return [Verse]
+    def start_verse
+      @first_verse ||= Verse.from_id("#{id}001001".to_i)
+    end
+
+    # @return [Verse]
+    def end_verse
+      @last_verse ||= Verse.from_id(
+        "#{id}#{chapters.length.to_s.rjust(3, '0')}#{chapters.last.to_s.rjust(3, '0')}".to_i
+      )
+    end
+
+    # @return [Book, nil]
+    def next_book
+      return @next_book if defined? @next_book
+      @next_book = Book.find_by_id(id + 1)
+    end
+  end
+end

data/lib/bible_bot/errors.rb

@@ -0,0 +1,17 @@
+module BibleBot
+  class BibleBotError < StandardError
+  end
+
+  # Raised if Reference is not valid.
+  # @example
+  #   "Genesis 4-2"
+  class InvalidReferenceError < BibleBotError
+  end
+
+  # Raised if Verse is not valid.
+  # In other words, if a chapter or verse are referenced that don't actually exist.
+  # @example
+  #   "Genesis 100:2"
+  class InvalidVerseError < BibleBotError
+  end
+end

data/lib/bible_bot/reference.rb

@@ -0,0 +1,148 @@
+module BibleBot
+  # A Reference represents a range of verses.
+  class Reference
+    attr_reader :start_verse # @return [Verse]
+    attr_reader :end_verse # @return [Verse]
+
+    # Initialize a {Reference} from {Verse} IDs. If no end_verse_id is provided, it will
+    # set end_verse to equal start_verse.
+    #
+    # @param start_verse_id [Integer]
+    # @param end_verse_id [Integer]
+    # @return [Reference]
+    # @example
+    #   BibleBot::Reference.from_verse_ids(1001001, 1001010) #=> (Gen 1:1-10)
+    def self.from_verse_ids(start_verse_id, end_verse_id=nil)
+      new(
+        start_verse: Verse.from_id(start_verse_id),
+        end_verse: Verse.from_id(end_verse_id || start_verse_id),
+      )
+    end
+
+    # Parse text into an array of scripture References.
+    #
+    # @param text [String] ex: "John 1:1 is the first but Romans 8:9-10 is another."
+    # @param validate [Boolean, :raise_errors]
+    #   * true - Skip invalid references (default)
+    #   * false - Include invalid references
+    #   * :raise_errors - Raise error if any references are invalid
+    # @return [Array<Reference>]
+    def self.parse(text, validate: true)
+      return [] if text.nil? || text.strip == ""
+
+      ReferenceMatch.scan(text).map(&:reference).select do |ref|
+        ref.validate! if validate == :raise_errors
+
+        !validate || ref.valid?
+      end
+    end
+
+    # @param start_verse [Verse]
+    # @param end_verse [Verse] Defaults to start_verse if no end_verse is provided
+    def initialize(start_verse:, end_verse: nil)
+      @start_verse = start_verse
+      @end_verse   = end_verse || start_verse
+    end
+
+    # Returns a formatted string of the {Reference}.
+    #
+    # @return [String]
+    # @example
+    #   reference.formatted #=> "Genesis 2:4-5:9"
+    def formatted
+      formatted_verses = [start_verse.formatted(include_verse: !full_chapters?)]
+
+      if end_verse && end_verse > start_verse && !(same_start_and_end_chapter? && full_chapters?)
+        formatted_verses << end_verse.formatted(
+          include_book: !same_start_and_end_book?,
+          include_chapter: !same_start_and_end_chapter?,
+          include_verse: !full_chapters?,
+        )
+      end
+
+      formatted_verses.join('-')
+    end
+
+    # @return [Boolean]
+    def same_start_and_end_book?
+      start_verse.book == end_verse&.book
+    end
+
+    # @return [Boolean]
+    def same_start_and_end_chapter?
+      same_start_and_end_book? &&
+      start_verse.chapter_number == end_verse&.chapter_number
+    end
+
+    # One or multiple full chapters.
+    #
+    # @return [Boolean]
+    def full_chapters?
+      start_verse.verse_number == 1 && end_verse&.last_verse_in_chapter?
+    end
+
+    # @return [string]
+    def to_s
+      "BibleBot::Reference — #{formatted}"
+    end
+
+    # Returns true if the given verse is within the start and end verse of the Reference.
+    #
+    # @param verse [Verse]
+    # @return [Boolean]
+    def includes_verse?(verse)
+      return false unless verse.is_a?(Verse)
+
+      start_verse <= verse && verse <= end_verse
+    end
+
+    # Return true if the two references contain any of the same verses.
+    # @param other [Reference]
+    # @return [Boolean]
+    def intersects_reference?(other)
+      return false unless other.is_a?(Reference)
+
+      start_verse <= other.end_verse && end_verse >= other.start_verse
+    end
+
+    # Returns an array of all the verses contained in the Reference.
+    #
+    # @return [Array<Verse>]
+    def verses
+      return @verses if defined? @verses
+
+      @verses = []
+      return @verses unless valid?
+
+      verse = start_verse
+
+      loop do
+        @verses << verse
+        break if end_verse.nil? || verse == end_verse
+        verse = verse.next_verse
+      end
+
+      @verses
+    end
+
+    # @return [Hash]
+    def inspect
+      {
+        start_verse: start_verse&.formatted,
+        end_verse: end_verse&.formatted,
+      }
+    end
+
+    # @return [Boolean]
+    def valid?
+      start_verse&.valid? && end_verse&.valid? && end_verse >= start_verse
+    end
+
+    # Raises error if reference is invalid
+    def validate!
+      start_verse&.validate!
+      end_verse&.validate!
+      raise InvalidReferenceError.new "Reference is not vaild: #{inspect}" unless valid?
+    end
+  end
+end

data/lib/bible_bot/reference_match.rb

@@ -0,0 +1,141 @@
+module BibleBot
+  # This class contains all the logic for mapping the different parts of a scripture Match into an actual {Reference}.
+  # It wraps the Match returned from the regular expression defined in {Bible.scripture_re}.
+  #
+  # A scripture reference can take many forms, but the least abbreviated form is:
+  #
+  #   Genesis 1:1 - Genesis 1:2
+  #
+  # Internally, this class represents this form using the following variables:
+  #
+  #   b1 c1:v1 - b2 c2:v2
+  #
+  # See Readme for list of supported abbreviation rules.
+  #
+  # == Advanced Use Cases
+  #
+  # This is a low level class used internally by {Reference.parse}.
+  # There are however some advanced use cases which you might want to use it for.
+  # For example, if you want to know where in the parsed String certain matches occur.
+  #
+  # For this there are a few convenience attributes:
+  #
+  # * {#match}
+  # * {#length}
+  # * {#offset}
+  #
+  # @example
+  #   matches = ReferenceMatch.scan("Mark 1:5 and another Romans 4:1")
+  #   matches[0].match[0]   #=> "Mark 1:5"
+  #   matches[0].offset     #=> 0
+  #   matches[0].length     #=> 8
+  #   matches[0].match[0]   #=> "Romans 4:1"
+  #   matches[1].offset     #=> 21
+  #   matches[1].length     #=> 10
+  #
+  # @note You shouldn't need to use this class directly. For the majority of use cases, just use {Reference.parse}.
+  class ReferenceMatch
+    attr_reader :match # @return [Match] The Match instance returned from the Regexp
+    attr_reader :length # @return [Integer] The length of the match in the text string
+    attr_reader :offset # @return [Integer] The starting position of the match in the text string
+
+    # Converts a string into an array of ReferenceMatches.
+    # Note: Does not validate References.
+    #
+    # @param text [String]
+    # @return [Array<ReferenceMatch>]
+    def self.scan(text)
+      scripture_reg = Bible.scripture_re
+      Array.new.tap do |matches|
+        text.scan(scripture_reg){ matches << self.new($~, $~.offset(0)[0]) }
+      end
+    end
+
+    # @return [Reference] Note: Reference is not yet validated
+    def reference
+      @reference ||= Reference.new(
+        start_verse: Verse.new(book: start_book, chapter_number: start_chapter.to_i, verse_number: start_verse.to_i),
+        end_verse: Verse.new(book: end_book, chapter_number: end_chapter.to_i, verse_number: end_verse.to_i),
+      )
+    end
+
+    private
+
+    attr_reader :b1 # @return [String]
+    attr_reader :c1 # @return [String] Represents the number after the start Book name, could be either chapter or verse number.
+    attr_reader :v1 # @return [String, nil] Represents the number after the colon, will always be start_verse if present.
+    attr_reader :b2 # @return [String, nil]
+    attr_reader :c2 # @return [String, nil] Represents the number after the end Book name, could be either chapter or verse number.
+    attr_reader :v2 # @return [String, nil] Represents the number after the colon, will always be end_verse if present.
+
+    # @param match [Match]
+    # @param offset [Integer]
+    def initialize(match, offset)
+      @match = match
+      @length = match.to_s.length
+      @offset = offset
+      @b1 = match[:BookTitle]
+      @c1 = match[:ChapterNumber]
+      @v1 = match[:VerseNumber]
+      @b2 = match[:EndBookTitle]
+      @c2 = match[:EndChapterNumber]
+      @v2 = match[:EndVerseNumber]
+    end
+
+    # @return [Book]
+    def start_book
+      # There will always be a starting book.
+      Book.find_by_name(@b1)
+    end
+
+    # @return [Book]
+    def end_book
+      # The end book is optional. If not provided, default to starting book.
+      Book.find_by_name(@b2) || start_book
+    end
+
+    # @return [Integer]
+    def start_chapter
+      # Start chapter should always be provided, except in the case of single chapter books.
+      # Jude 5 for example, c1==5 but the chapter should actually be 1.
+      return 1 if start_book.single_chapter?
+      c1
+    end
+
+    # @return [Integer]
+    def start_verse
+      # If there is a number in the v1 position, it will always represent the starting verse.
+      # There are a few cases where the start_verse will be in a different position or inferred.
+      # * Jude 4    (start_verse is in the c1 position)
+      # * Genesis 5 (start_verse is inferred to be 1, and end_verse is the last verse in Genesis 5)
+      v1 || (start_book.single_chapter? ? c1 : 1)
+    end
+
+    # @return [Integer]
+    def end_chapter
+      return start_chapter if single_verse_ref? # Ex: Genesis 1:3 => "1"
+      return 1 if end_book.single_chapter? # Ex: Jude 2-4 => "1"
+      return c1 if !b2 && !v2 && v1  # Ex: Genesis 1:2-3 => "1"
+      c2 ||   # Ex: Genesis 1:1 - 2:4 => "4"
+      c1      # Ex: Genesis 5 => "5"
+    end
+
+    # @return [Integer]
+    def end_verse
+      return start_verse if single_verse_ref? # Ex: Genesis 1:3 => "3"
+      v2 || # Ex: Genesis 1:4 - 2:5 => "5"
+      (
+        (v1 && !b2) ?
+        c2 : # Ex: Gen 1:4-8  => "8"
+        end_book.chapters[end_chapter.to_i - 1] # Genesis 1 => "31"
+      )
+    end
+
+    # @return [Boolean]
+    def single_verse_ref?
+      !b2 && !c2 && !v2 &&
+      (v1 || start_book.single_chapter?) # Ex: Genesis 5:1 || Jude 5
+      # Genesis 5 is not a single verse ref
+    end
+  end
+end

data/lib/bible_bot/verse.rb

@@ -0,0 +1,156 @@
+module BibleBot
+  # Verse represents a single verse in the bible.
+  class Verse
+    include Comparable
+
+    attr_reader :book # @return [Book]
+    attr_reader :chapter_number # @return [Integer]
+    attr_reader :verse_number # @return [Integer]
+
+    # Turns an Inteter into a Verse
+    # For more details, see note above the `id` method.
+    #
+    # @param id [Integer]
+    # @return [Verse]
+    # @example
+    #   Verse.from_id(19_105_001) #=> <Verse book="Psalms" chapter_number=105 verse_number=1>
+    def self.from_id(id)
+      return from_string_id(id) if id.is_a?(String)
+      return nil if id.nil?
+      raise BibleBot::InvalidVerseError unless id.is_a?(Integer)
+
+      book_id        = id / 1_000_000
+      chapter_number = id / 1_000 % 1_000
+      verse_number   = id % 1_000
+      book           = BibleBot::Book.find_by_id(book_id)
+
+      new(book: book, chapter_number: chapter_number, verse_number: verse_number)
+    end
+
+    # @param book [Book]
+    # @param chapter_number [Integer]
+    # @param verse_number [Integer]
+    def initialize(book:, chapter_number:,  verse_number:)
+      @book = book
+      @chapter_number = chapter_number
+      @verse_number = verse_number
+    end
+
+    # Returns an Integer in the from of
+    #
+    #   |- book.id
+    #   |   |- chapter_number
+    #   |   |   |- verse_number
+    #   XX_XXX_XXX
+    #
+    # Storing as an Integer makes it super convenient to store in a database
+    # and compare verses and verse ranges using simple database queries
+    #
+    # @return [Integer]
+    # @example
+    #   verse.id #=> 19_105_001
+    #                 #-> this represents "Psalm 105:1"
+    def id
+      @id ||= "#{book.id}#{chapter_number.to_s.rjust(3, '0')}#{verse_number.to_s.rjust(3, '0')}".to_i
+    end
+
+    # @deprecated Use {id} instead
+    # @return [String] ex: "psalms-023-001"
+    def string_id
+      "#{book.name.downcase.gsub(' ', '_')}-#{chapter_number.to_s.rjust(3, '0')}-#{verse_number.to_s.rjust(3, '0')}"
+    end
+
+    # The Comparable mixin uses this to define all the other comparable methods
+    #
+    # @param other [Verse]
+    # @return [Integer] Either -1, 0, or 1
+    #   * -1: this verse is less than the other verse
+    #   * 0: this verse is equal to the other verse
+    #   * 1: this verse is greater than the other verse
+    def <=>(other)
+      id <=> other.id
+    end
+
+    # @param include_book [Boolean]
+    # @param include_chapter [Boolean]
+    # @param include_verse [Boolean]
+    # @return [String]
+    # @example
+    #   verse.formatted #=> "Genesis 5:23"
+    def formatted(include_book: true, include_chapter: true, include_verse: true)
+      str = String.new # Using String.new because string literals will be frozen in Ruby 3.0
+      str << "#{book.formatted_name} " if include_book
+
+      if book.single_chapter?
+        str << "#{verse_number}" if include_verse
+      else
+        str << "#{chapter_number}" if include_chapter
+        str << ":" if include_chapter && include_verse
+        str << "#{verse_number}" if include_verse
+      end
+
+      str.strip.freeze
+    end
+
+    # Returns next verse. It will reach into the next chapter or the next book
+    # until it gets to the last verse in the bible,
+    # at which point it will return nil.
+    #
+    # @return [Verse, nil]
+    def next_verse
+      return Verse.new(book: book, chapter_number: chapter_number, verse_number: verse_number + 1) unless last_verse_in_chapter?
+      return Verse.new(book: book, chapter_number: chapter_number + 1, verse_number: 1) unless last_chapter_in_book?
+      return Verse.new(book: book.next_book, chapter_number: 1, verse_number: 1) if book.next_book
+      nil
+    end
+
+    # @return [Boolean]
+    def last_verse_in_chapter?
+      verse_number == book.chapters[chapter_number - 1]
+    end
+
+    # @return [Boolean]
+    def last_chapter_in_book?
+      chapter_number == book.chapters.length
+    end
+
+    # @return [Hash]
+    def inspect
+      {
+        book: book&.name,
+        chapter_number: chapter_number,
+        verse_number: verse_number
+      }
+    end
+
+    # @return [Boolean]
+    def valid?
+      book.is_a?(BibleBot::Book) &&
+      chapter_number.is_a?(Integer) && chapter_number >= 1 && chapter_number <= book.chapters.length &&
+      verse_number.is_a?(Integer) && verse_number >= 1 && verse_number <= book.chapters[chapter_number-1]
+    end
+
+    # Raises error if reference is invalid
+    def validate!
+      raise InvalidVerseError.new "Verse is not valid: #{inspect}" unless valid?
+    end
+
+    private
+
+    # This gets called by {from_id} to allow it to be backwards compatible for a while.
+    # @deprecated Use {from_id} instead.
+    # @param verse_id [String] ex: "genesis-001-001"
+    # @return [Verse] ex: <Verse book="Genesis" chapter_number=1 verse_number=1>
+    def self.from_string_id(string_id)
+      parts = string_id.split( '-' )
+
+      book_name      = parts[0].gsub( '_', ' ' )
+      chapter_number = parts[1].to_i
+      verse_number   = parts[2].to_i
+
+      book = BibleBot::Bible.books.select{ |b| b.name.downcase == book_name }.first
+
+      new(book: book, chapter_number: chapter_number, verse_number: verse_number)
+    end
+  end
+end