bible_ref_parser 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 925e15f2c8fe0edb168af8bb3037d888fadec26ea67b9cdf5204be3ed0f2b00d
-  data.tar.gz: a6dc3b012dbc430302a4b75d83afb3c003042c1233b002f41eb921628d61226c
+  metadata.gz: 8881964f74bd9d7be1e27232326be473469e457a5fbe8c9a5d234e668198e717
+  data.tar.gz: 9681a524b8b4f0936b4956aed6ba2918b00c66528cf5f7cb4393ddd13d7d5bfc
 SHA512:
-  metadata.gz: 96aad3474367886425c9eaa962ea0a00885a35481b1e85ea12f790fafef0b40a09270cae2aa02f805fbb4b1565ddcc9c0182c1f78e24b1e05e8f1de58db7527d
-  data.tar.gz: e03fe4f88db255410405296c1df3632dbc30dc370de075bbb258aa7d994f3fb4e203ac869e88aa7ad89b4094eec5ab678dee276675cbe1966c57011a67107ec6
+  metadata.gz: 4a560d88938857aa86f7c2b6a981e42b7c09e23ac101d2a1e058f91fb7713c817a1e0f4a8dcf28f8e271a4115cbad83a60be820ed6d71f8e36da9a4c26af28f7
+  data.tar.gz: c96e8ecbd32d8c51529512641283ca8485871e8810cae044589f8bdbe40f6b0bea3016b4247c1a33c9d59530be0c1b1158fe243b36bf6bb30b0f0f7d8ec104e1

data/.standard.yml

@@ -1,4 +1,4 @@
-ruby_version: 2.7
+ruby_version: 3.1
 ignore:
   - "bin/**/*"
   - "db/**/*"

data/CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Ruby gem that parses Bible references from text using Parslet (~> 2.0) PEG parser. Given a string like `"Read John 3:16 and Romans 8:28"`, it segments the text into reference and plain-text parts with character positions.
+
+## Commands
+
+```bash
+rake                              # Default: runs ci (spec + standard + yard)
+rake spec                         # Run all RSpec tests
+bundle exec rspec spec/lib/bible_ref_parser/parser_spec.rb  # Run a single spec file
+bundle exec rspec spec/lib/bible_ref_parser/parser_spec.rb:42  # Run a single example by line
+rake standard                     # Lint with StandardRB
+bundle exec standardrb --fix      # Auto-fix lint issues
+rake yard                         # Generate YARD docs
+bin/console                       # Pry REPL with gem loaded
+```
+
+## Architecture
+
+**Parsing pipeline:** `BibleReferenceText.new(text)` → `SegmentParser.parse(text)` → `Parser` (Parslet grammar) → array of `Segment` objects.
+
+- **Parser** (`lib/bible_ref_parser/parser.rb`) — Parslet grammar defining rules for book names, chapter:verse notation, ranges, cross-book ranges, and verse lists. Case-insensitive matching with abbreviation support.
+- **SegmentParser** (`lib/bible_ref_parser/segment_parser.rb`) — Converts the Parslet parse tree into `Segment` objects, tracking character positions in the original text.
+- **Segment** (`lib/bible_ref_parser/segment.rb`) — Represents a `:reference` or `:text` segment with original text and position offsets.
+- **BibleReferenceText** (`lib/bible_ref_parser/bible_reference_text.rb`) — Main API class. Includes `Enumerable` and delegates array-like methods to its segments array.
+- **BibleReference** (`lib/bible_ref_parser/bible_reference.rb`) — `Data` class holding text, start_offset, end_offset.
+- **Books** (`lib/bible_ref_parser/books.rb`) — Dictionary of 66 Bible books (39 OT, 27 NT) with abbreviation variants.
+
+On parse failure, the library gracefully degrades to a single text segment rather than raising.
+
+## Testing
+
+RSpec with custom matchers in `spec/support/matchers/reference_parser_matchers.rb`. The custom `parse` matcher validates Parslet rule output. Tests cover unit, integration, and edge cases (Unicode, HTML tags, invalid input).
+
+## Linting
+
+StandardRB configured in `.standard.yml` targeting Ruby 2.7. Max method length: 15 lines.
+
+## CI
+
+GitHub Actions (`.github/workflows/main.yml`): Ruby 3.4.2 on ubuntu-latest, runs `bundle exec rake` on push to main and PRs.

data/lib/bible_ref_parser/bible_reference.rb

@@ -1,5 +1,34 @@
 module BibleRefParser
-  BibleReference = Data.define(:text, :start_offset, :end_offset) do
+  BibleReference = Data.define(:text, :start_offset, :end_offset, :book_name, :chapter, :_parts) do
+    def initialize(text:, start_offset:, end_offset:, book_name: nil, chapter: nil, parts: [])
+      super(text:, start_offset:, end_offset:, book_name:, chapter:, _parts: parts.freeze)
+    end
+
+    def parts
+      _parts.empty? ? [self] : _parts
+    end
+
+    def compound?
+      parts.size > 1
+    end
+
+    def same_chapter?
+      return false unless compound?
+
+      chapters = parts.map(&:chapter)
+      !chapters.first.nil? && chapters.uniq.size == 1
+    end
+
+    def qualified_text
+      return text unless book_name && !text.start_with?(book_name)
+
+      if chapter && !text.match?(/\A\d+:/)
+        "#{book_name} #{chapter}:#{text}"
+      else
+        "#{book_name} #{text}"
+      end
+    end
+
     def to_s
       text
     end

data/lib/bible_ref_parser/parser.rb

@@ -73,12 +73,20 @@ module BibleRefParser
       (explicit_verse.as(:start) >> range_sep >> explicit_verse.as(:end)).as(:explicit_verse_range)
     end
 
-    rule(:verse_list) do
-      (verse >> (list_sep >> verse).repeat(1)).as(:verse_list)
+    # A verse number that is not followed by a colon, preventing
+    # it from consuming a chapter number in a chapter:verse pair
+    rule(:standalone_verse) do
+      (reference_int >> colon.absent?).as(:verse)
     end
 
-    rule(:chapter_with_verse_list) do
-      (chapter >> colon >> verse_list).as(:chapter_with_verse_list)
+    rule(:verse_specifier) { verse_range | standalone_verse }
+
+    rule(:verse_specifier_list) do
+      (verse_specifier >> (list_sep >> verse_specifier).repeat(1)).as(:verse_specifier_list)
+    end
+
+    rule(:chapter_with_mixed_verses) do
+      (chapter >> colon >> verse_specifier_list).as(:chapter_with_mixed_verses)
     end
 
     rule(:chapter_with_verse_range) do
@@ -86,7 +94,7 @@ module BibleRefParser
     end
 
     rule(:chapter_with_verses) do
-      chapter_with_verse_list | chapter_with_verse_range
+      chapter_with_mixed_verses | chapter_with_verse_range
     end
 
     rule(:indicator) do
@@ -94,8 +102,8 @@ module BibleRefParser
     end
 
     rule(:indicator_list) do
-      indicator.repeat(1).as(:indicator_list) |
-        (indicator >> (list_sep >> indicator).repeat(1)).as(:indicator_list)
+      (indicator >> (list_sep >> indicator).repeat(1)).as(:indicator_list) |
+        indicator.repeat(1).as(:indicator_list)
     end
 
     rule(:cross_book_range) do

data/lib/bible_ref_parser/reference_node.rb

@@ -0,0 +1,133 @@
+module BibleRefParser
+  # Wraps a raw reference hash from the Parslet parse tree.
+  # Encapsulates all slice traversal and position extraction logic,
+  # so callers can work with named concepts instead of raw nested hashes.
+  class ReferenceNode
+    def initialize(ref_hash)
+      @ref_hash = ref_hash
+    end
+
+    def book_name
+      book&.to_s
+    end
+
+    # Character range covered by this reference in the original text
+    def position
+      book.offset...end_offset(indicators.last)
+    end
+
+    def compound?
+      multiple_indicators? || one_chapter_verse_list?
+    end
+
+    def to_bible_reference(text)
+      BibleReference.new(
+        text: text[position],
+        start_offset: position.begin,
+        end_offset: position.end,
+        book_name: book_name,
+        parts: extract_parts(text)
+      )
+    end
+
+    private
+
+    def book
+      @ref_hash[:book]
+    end
+
+    def indicators
+      @ref_hash[:indicator_list]
+    end
+
+    def extract_parts(text)
+      return [] unless compound?
+
+      if one_chapter_verse_list?
+        extract_verse_list_parts(text)
+      else
+        extract_parts_per_indicator(text)
+      end
+    end
+
+    def multiple_indicators?
+      indicators in [_, _, *]
+    end
+
+    def one_chapter_verse_list?
+      indicators in [{chapter_with_mixed_verses: {verse_specifier_list: [_, _, *]}}]
+    end
+
+    def extract_parts_per_indicator(text)
+      indicators.flat_map.with_index do |indicator, idx|
+        if indicator in {chapter_with_mixed_verses: {chapter: chapter_slice, verse_specifier_list: specifiers}}
+          first_start = (idx == 0) ? book.offset : chapter_slice.offset
+          extract_mixed_verse_parts(text, chapter_slice, specifiers, first_part_start: first_start)
+        else
+          end_pos = end_offset(indicator)
+          start_pos = (idx == 0) ? book.offset : start_offset(indicator)
+
+          BibleReference.new(
+            text: text[start_pos...end_pos],
+            start_offset: start_pos,
+            end_offset: end_pos,
+            book_name: book_name
+          )
+        end
+      end
+    end
+
+    def extract_verse_list_parts(text)
+      indicators => [{chapter_with_mixed_verses: {chapter: chapter_slice, verse_specifier_list: specifiers}}]
+      extract_mixed_verse_parts(text, chapter_slice, specifiers, first_part_start: book.offset)
+    end
+
+    def extract_mixed_verse_parts(text, chapter_slice, specifiers, first_part_start:)
+      specifiers.each_with_index.map do |spec, idx|
+        case spec
+        in {verse_range: {start: {verse: start_verse}, end: {verse: end_verse}}}
+          end_pos = end_verse.offset + end_verse.size
+          start_pos = (idx == 0) ? first_part_start : start_verse.offset
+        in {verse: verse_slice}
+          end_pos = verse_slice.offset + verse_slice.size
+          start_pos = (idx == 0) ? first_part_start : verse_slice.offset
+        end
+
+        BibleReference.new(
+          text: text[start_pos...end_pos],
+          start_offset: start_pos,
+          end_offset: end_pos,
+          book_name: book_name,
+          chapter: chapter_slice.to_s
+        )
+      end
+    end
+
+    def start_offset(indicator)
+      case indicator
+      in {chapter: first_slice}
+      in {explicit_verse: {chapter: first_slice}}
+      in {chapter_range: {start: {chapter: first_slice}}}
+      in {chapter_with_verse_range: {chapter: first_slice}}
+      in {chapter_with_mixed_verses: {chapter: first_slice}}
+      in {explicit_verse_range: {start: {explicit_verse: {chapter: first_slice}}}}
+      end
+
+      first_slice.offset
+    end
+
+    def end_offset(indicator)
+      case indicator
+      in {chapter: last_slice}
+      in {explicit_verse: {verse: last_slice}}
+      in {chapter_range: {end: {chapter: last_slice}}}
+      in {chapter_with_verse_range: {verse_range: {end: {verse: last_slice}}}}
+      in {chapter_with_mixed_verses: {verse_specifier_list: [*, {verse: last_slice}]}}
+      in {chapter_with_mixed_verses: {verse_specifier_list: [*, {verse_range: {end: {verse: last_slice}}}]}}
+      in {explicit_verse_range: {end: {explicit_verse: {verse: last_slice}}}}
+      end
+
+      last_slice.offset + last_slice.size
+    end
+  end
+end

data/lib/bible_ref_parser/segment.rb

@@ -8,10 +8,11 @@ module BibleRefParser
     # @param type [Symbol] :reference or :text
     # @param original_text [String] The original text segment
     # @param position [Range] The character positions in the original string
-    def initialize(type, original_text, position)
+    def initialize(type, original_text, position, bible_reference: nil)
       @type = type
       @original_text = original_text
       @position = position
+      @bible_reference = bible_reference
       validate!
     end
 
@@ -37,6 +38,7 @@ module BibleRefParser
     # @return [BibleReference, nil] a BibleReference for reference segments, nil for text
     def bible_reference
       return nil unless reference?
+      return @bible_reference if @bible_reference
 
       BibleReference.new(
         text: original_text,

data/lib/bible_ref_parser/segment_node.rb

@@ -0,0 +1,45 @@
+module BibleRefParser
+  # Wraps a raw segment hash (keyed +:reference+ or +:text+) from the Parslet
+  # parse tree and knows how to build a Segment from it.
+  class SegmentNode
+    def initialize(raw_segment)
+      @raw = raw_segment
+    end
+
+    def reference?
+      @raw.key?(:reference)
+    end
+
+    def text?
+      @raw.key?(:text)
+    end
+
+    # Character range covered by this segment in the original text
+    def position
+      if text?
+        t = @raw[:text]
+        t.offset...(t.offset + t.size)
+      else
+        reference_node.position
+      end
+    end
+
+    def to_segment(text)
+      pos = position
+      seg_text = text[pos]
+
+      if reference?
+        bible_ref = reference_node.to_bible_reference(text)
+        Segment.new(:reference, seg_text, pos, bible_reference: bible_ref)
+      else
+        Segment.new(:text, seg_text, pos)
+      end
+    end
+
+    private
+
+    def reference_node
+      @reference_node ||= ReferenceNode.new(@raw[:reference])
+    end
+  end
+end

data/lib/bible_ref_parser/segment_parser.rb

@@ -7,8 +7,8 @@ module BibleRefParser
     def parse(text)
       text = text.to_s.dup.freeze
       begin
-        @tree = @reference_parser.parse(text)[:segments]
-        segments = build_segments(text)
+        tree = @reference_parser.parse(text)[:segments]
+        segments = tree.map { |raw| SegmentNode.new(raw).to_segment(text) }
         validate_segments!(segments, text)
         segments
       rescue Parslet::ParseFailed, InvalidInputError
@@ -17,29 +17,8 @@ module BibleRefParser
       end
     end
 
-    def get_last_element(element)
-      if element.is_a?(Hash)
-        return get_last_element(element.values.last)
-      elsif element.is_a?(Array)
-        return get_last_element(element.last)
-      end
-
-      element
-    end
-
     private
 
-    def build_segments(text)
-      positions = segment_positions
-      raise InvalidInputError, "Position mismatch" unless positions.size == @tree.size
-
-      @tree.each_with_index.map do |seg, i|
-        pos = positions[i]
-        seg_text = text[pos]
-        Segment.new(seg.keys.first, seg_text, pos)
-      end
-    end
-
     def validate_segments!(segments, full_text)
       # Verify the segments cover the entire input
       coverage = segments.map(&:position).reduce(0..0) { |a, b| a.begin..b.end }
@@ -47,31 +26,5 @@ module BibleRefParser
         raise InvalidInputError, "Input contains unparsed content"
       end
     end
-
-    def position(first_slice, last_slice = first_slice)
-      first_slice.offset...(last_slice.offset + last_slice.size)
-    end
-
-    def segment_positions
-      @segment_positions ||= @tree.collect do |seg|
-        if seg.key?(:text)
-          t = seg[:text]
-          position(t)
-        elsif seg.key?(:reference)
-          ref = seg[:reference]
-          book = ref[:book]
-          last = get_last_element(ref)
-          position(book, last)
-        end
-      end
-    end
-
-    def segment_texts(text)
-      @segment_texts ||= segment_positions.collect { |pos| text[pos] }
-    end
-
-    def segment_types
-      @segment_types ||= @tree.collect { |seg| seg.keys }.flatten
-    end
   end
 end

data/lib/bible_ref_parser/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BibleRefParser
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/bible_ref_parser.rb

@@ -7,6 +7,8 @@ require_relative "bible_ref_parser/bible_reference_text"
 require_relative "bible_ref_parser/books"
 require_relative "bible_ref_parser/parser"
 require_relative "bible_ref_parser/segment"
+require_relative "bible_ref_parser/reference_node"
+require_relative "bible_ref_parser/segment_node"
 require_relative "bible_ref_parser/segment_parser"
 
 module BibleRefParser

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bible_ref_parser
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Fabio Papa
@@ -130,6 +130,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".standard.yml"
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -141,7 +142,9 @@ files:
 - lib/bible_ref_parser/bible_reference_text.rb
 - lib/bible_ref_parser/books.rb
 - lib/bible_ref_parser/parser.rb
+- lib/bible_ref_parser/reference_node.rb
 - lib/bible_ref_parser/segment.rb
+- lib/bible_ref_parser/segment_node.rb
 - lib/bible_ref_parser/segment_parser.rb
 - lib/bible_ref_parser/version.rb
 - sig/bible_ref_parser.rbs
@@ -167,7 +170,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 4.0.8
 specification_version: 4
 summary: A parser for Bible references
 test_files: []