bible_ref_parser 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 925e15f2c8fe0edb168af8bb3037d888fadec26ea67b9cdf5204be3ed0f2b00d
-  data.tar.gz: a6dc3b012dbc430302a4b75d83afb3c003042c1233b002f41eb921628d61226c
+  metadata.gz: 785c346d7af39dc9c8f2eee1088d443fb78ff980c33572bd27c28610ba364b04
+  data.tar.gz: 87fcbaa84fb663b042352e4f78339a940922b673a62a76dd0bca0af68ca07d36
 SHA512:
-  metadata.gz: 96aad3474367886425c9eaa962ea0a00885a35481b1e85ea12f790fafef0b40a09270cae2aa02f805fbb4b1565ddcc9c0182c1f78e24b1e05e8f1de58db7527d
-  data.tar.gz: e03fe4f88db255410405296c1df3632dbc30dc370de075bbb258aa7d994f3fb4e203ac869e88aa7ad89b4094eec5ab678dee276675cbe1966c57011a67107ec6
+  metadata.gz: a7d0e3c59c1af88185012447a6f7db2e2feb13a351fa3b524bf3cdac98c4c5dbdb387bd1a467d6b08140c4bc8ea7a241331e2c0955c8ed0e18bc19a12d8526fc
+  data.tar.gz: 79230b5b2b8a4b3bf1f2626089a3bc776552f92ca1f6ea5ec05d2364e2de1b976f5177f8ab37fef85c85212895f4e1d1a3321ad71c9820f157489f2b7f518c9c

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,28 @@
 module BibleRefParser
-  BibleReference = Data.define(:text, :start_offset, :end_offset) do
+  BibleReference = Data.define(:text, :start_offset, :end_offset, :book_name, :_parts) do
+    def initialize(text:, start_offset:, end_offset:, book_name: nil, parts: [])
+      super(
+        text: text, start_offset: start_offset, end_offset: end_offset,
+        book_name: book_name, _parts: parts.freeze
+      )
+    end
+
+    def parts
+      _parts.empty? ? [self] : _parts
+    end
+
+    def compound?
+      parts.size > 1
+    end
+
+    def qualified_text
+      if book_name && !text.start_with?(book_name)
+        "#{book_name} #{text}"
+      else
+        text
+      end
+    end
+
     def to_s
       text
     end

data/lib/bible_ref_parser/parser.rb

@@ -73,8 +73,14 @@ module BibleRefParser
       (explicit_verse.as(:start) >> range_sep >> explicit_verse.as(:end)).as(:explicit_verse_range)
     end
 
+    # 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(:verse_list) do
-      (verse >> (list_sep >> verse).repeat(1)).as(:verse_list)
+      (verse >> (list_sep >> standalone_verse).repeat(1)).as(:verse_list)
     end
 
     rule(:chapter_with_verse_list) do
@@ -94,8 +100,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,85 @@
+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
+      @ref_hash[:book]&.to_s
+    end
+
+    # The first Parslet::Slice in the entire reference structure
+    def first_slice
+      leaf_first(@ref_hash)
+    end
+
+    # The last Parslet::Slice in the entire reference structure
+    def last_slice
+      leaf_last(@ref_hash)
+    end
+
+    # Character range covered by this reference in the original text
+    def position
+      book = @ref_hash[:book]
+      last = last_slice
+      book.offset...(last.offset + last.size)
+    end
+
+    def compound?
+      indicators.is_a?(Array) && indicators.size > 1
+    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 indicators
+      @ref_hash[:indicator_list]
+    end
+
+    def extract_parts(text)
+      return [] unless compound?
+
+      indicators.each_with_index.map do |indicator, idx|
+        first = leaf_first(indicator)
+        last = leaf_last(indicator)
+        end_pos = last.offset + last.size
+        start_pos = (idx == 0) ? @ref_hash[:book].offset : first.offset
+
+        BibleReference.new(
+          text: text[start_pos...end_pos],
+          start_offset: start_pos,
+          end_offset: end_pos,
+          book_name: book_name
+        )
+      end
+    end
+
+    def leaf_first(node)
+      case node
+      when Hash then leaf_first(node.values.first)
+      when Array then leaf_first(node.first)
+      else node
+      end
+    end
+
+    def leaf_last(node)
+      case node
+      when Hash then leaf_last(node.values.last)
+      when Array then leaf_last(node.last)
+      else node
+      end
+    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.3.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.3.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: []