bible_ref_parser 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 444fb0ee3218f9caa74109ee60f834efad718af2f2982453ac9918980d5da614
-  data.tar.gz: 839da96a5fedb211d67b645cba63335ef12a16db86b89bf1bc8a52a86f4af783
+  metadata.gz: 785c346d7af39dc9c8f2eee1088d443fb78ff980c33572bd27c28610ba364b04
+  data.tar.gz: 87fcbaa84fb663b042352e4f78339a940922b673a62a76dd0bca0af68ca07d36
 SHA512:
-  metadata.gz: 9a40f9a4068dc57f0316e2ac77a15ec27fd9709135eb0530c8dac2859b75fb0f2d25e0b11d5ea7e37cd4c08d145745c49d6a0c6c4e882f28195ff8cbde7e21c1
-  data.tar.gz: f5234fd33d0c25a4d2ef4ac5d89db6bb771ff2ad4e93e4aaaf4452c30bd462756688ee60cf403d2fe00c503d61112522792821f68e76b912a86ccefe1c60241e
+  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

@@ -0,0 +1,30 @@
+module BibleRefParser
+  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
+  end
+end

data/lib/bible_ref_parser/bible_reference_text.rb

@@ -1,35 +1,45 @@
+require "forwardable"
+
 module BibleRefParser
   class BibleReferenceText
+    extend Forwardable
     include Enumerable
 
+    attr_reader :segments
+
+    def_delegators :segments, :each, :size, :empty?, :[], :last
+    alias_method :length, :size
+
     def initialize(text)
       raise InvalidInputError, "Expected a string, got #{text.class}" unless text.respond_to?(:to_str)
-      @original_text = text.to_str
+      @text = text.to_str
       @segments = parse_segments
     end
 
-    def segments
-      @segments || []
-    end
-
     def references
-      segments.select(&:reference?)
+      segments.filter_map(&:bible_reference)
     end
 
-    def each(&block)
-      segments.each(&block)
+    def text_with_references
+      segments.map(&:to_s)
     end
 
     def to_s
       segments.map(&:to_s).join
     end
 
+    def inspect
+      displayed = segments.first(10).map(&:inspect)
+      displayed << "..." if segments.size > 10
+      "#<#{self.class} text=#{@text.inspect} segments=[#{displayed.join(", ")}]>"
+    end
+
     private
 
     def parse_segments
-      SegmentParser.new.parse(@original_text)
+      SegmentParser.new.parse(@text)
     rescue Parslet::ParseFailed
-      nil
+      [Segment.new(:text, @text, 0...@text.length)]
     end
   end
 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
 
@@ -20,6 +21,10 @@ module BibleRefParser
       original_text
     end
 
+    def inspect
+      "#<#{self.class} type=:#{type} text=\"#{original_text}\">"
+    end
+
     # @return [Boolean] true if this is a Bible reference segment
     def reference?
       type == :reference
@@ -30,6 +35,18 @@ module BibleRefParser
       type == :text
     end
 
+    # @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,
+        start_offset: position.begin,
+        end_offset: position.end
+      )
+    end
+
     private
 
     def validate!

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.1.0"
+  VERSION = "0.3.0"
 end

data/lib/bible_ref_parser.rb

@@ -2,10 +2,13 @@
 
 require_relative "bible_ref_parser/version"
 
+require_relative "bible_ref_parser/bible_reference"
 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,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bible_ref_parser
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Fabio Papa
 bindir: exe
 cert_chain: []
-date: 2025-05-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parslet
@@ -130,6 +130,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".standard.yml"
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -137,10 +138,13 @@ files:
 - ai_artifacts/spec.md
 - ai_artifacts/todo.md
 - lib/bible_ref_parser.rb
+- lib/bible_ref_parser/bible_reference.rb
 - 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
@@ -166,7 +170,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.8
 specification_version: 4
 summary: A parser for Bible references
 test_files: []