bible_ref_parser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 444fb0ee3218f9caa74109ee60f834efad718af2f2982453ac9918980d5da614
+  data.tar.gz: 839da96a5fedb211d67b645cba63335ef12a16db86b89bf1bc8a52a86f4af783
+SHA512:
+  metadata.gz: 9a40f9a4068dc57f0316e2ac77a15ec27fd9709135eb0530c8dac2859b75fb0f2d25e0b11d5ea7e37cd4c08d145745c49d6a0c6c4e882f28195ff8cbde7e21c1
+  data.tar.gz: f5234fd33d0c25a4d2ef4ac5d89db6bb771ff2ad4e93e4aaaf4452c30bd462756688ee60cf403d2fe00c503d61112522792821f68e76b912a86ccefe1c60241e

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,19 @@
+ruby_version: 2.7
+ignore:
+  - "bin/**/*"
+  - "db/**/*"
+  - "script/**/*"
+  - "tmp/**/*"
+  - "vendor/**/*"
+  - "doc/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "**/*_spec.rb"
+    - "Rakefile"
+
+Metrics/MethodLength:
+  Max: 15

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,41 @@
+# BibleRefParser
+
+BibleRefParser is a Ruby gem for parsing and normalizing Bible references.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+$ bundle add bible_ref_parser
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+$ gem install bible_ref_parser
+```
+
+## Usage
+
+```ruby
+require 'bible_ref_parser'
+
+# Parse a Bible reference
+reference = BibleRefParser::BibleReferenceText.new("John 3:16")
+# Work with the parsed reference
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/fapapa/bible_ref_parser.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+  t.options = ["--output-dir=doc"]
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task :coverage do
+  require "simplecov"
+  SimpleCov.start do
+    add_filter "/spec/"
+  end
+end
+
+task test: [:spec, :standard]
+
+desc "Run all checks"
+task ci: [:test, :yard]
+
+task default: :ci

data/ai_artifacts/prompt_plan.md

@@ -0,0 +1,189 @@
+# Prompt Plan
+
+### Step-by-Step Blueprint
+
+1. **Project Setup & Infrastructure**
+2. **Core Parser Implementation (Incremental Grammar Rules)**
+3. **Segment & BibleReferenceText Classes**
+4. **Error Handling & Edge Cases**
+5. **Integration & Final Polish**
+
+---
+
+## Prompt 1: Gem Setup & Test Infrastructure
+```text
+Create a new gem called 'bible_ref_parser' with:
+- Required dependencies: parslet (~> 2.0), rspec
+- Basic directory structure
+- RSpec configuration
+- Empty module scaffold in lib/bible_ref_parser.rb
+- Empty InvalidInputError class
+- Empty BibleReferenceText and Segment classes
+- A spec verifying the InvalidInputError is raised for non-string inputs
+```
+
+---
+
+## Prompt 2: Book Name Recognition
+```text
+Implement the book name parser component:
+1. Create lib/bible_ref_parser/books.rb with canonical book list
+2. Build Parslet grammar rule for book names with:
+   - Full names (e.g., "Genesis")
+   - Numeric prefixes ("1 Corinthians", "III John")
+   - Common abbreviations ("Gen", "Jn")
+3. Add test cases for:
+   - Matching all 66 books in various formats
+   - Rejecting non-biblical book names
+   - Case insensitivity
+   - Whitespace tolerance
+```
+
+---
+
+## Prompt 3: Chapter/Verse Number Parsing
+```text
+Implement chapter/verse number parsing:
+1. Add Parslet rules for:
+   - Simple chapter (e.g., "3")
+   - Chapter-verse ("3:16")
+   - Verse ranges ("16-18", "3:16–4:2")
+   - Comma-separated verses ("16,17")
+2. Create test cases for:
+   - Valid/invalid number formats
+   - Range detection
+   - Punctuation handling
+   - Position tracking
+```
+
+---
+
+## Prompt 4: Basic Reference Parsing
+```text
+Combine book and number parsing for single references:
+1. Create rule: book_name >> (chapter/verse components)
+2. Handle optional whitespace between components
+3. Add position tracking for references
+4. Test cases for:
+   - "Gen 1"
+   - "John 3:16"
+   - "1 Cor 15:20-22"
+   - Invalid partial matches
+```
+
+---
+
+## Prompt 5: Segment Class Implementation
+```text
+Implement Segment class with:
+- Type discrimination (:reference/:text)
+- Original text storage
+- Position tracking
+- to_s delegation
+- Validation against empty segments
+Add tests verifying:
+- Correct type assignment
+- Position accuracy
+- Original text preservation
+- Empty segment filtering
+```
+
+---
+
+## Prompt 6: Text Segmentation Logic
+```text
+Implement reference/text segmentation:
+1. Create parser that splits input into alternating text/reference segments
+2. Handle whitespace between references
+3. Preserve original text including newlines
+4. Test cases for:
+   - Mixed text/reference content
+   - Leading/trailing whitespace
+   - Consecutive references
+   - Newline handling
+```
+
+---
+
+## Prompt 7: BibleReferenceText Class
+```text
+Implement BibleReferenceText with:
+- Enumerable mixin
+- #segments and #references methods
+- to_s reconstruction
+- Error handling (return nil on parse errors)
+Test:
+- Enumeration behavior
+- Reference filtering
+- Round-trip text reconstruction
+- Nil return on invalid references
+```
+
+---
+
+## Prompt 8: Punctuation Handling
+```text
+Add punctuation rules:
+1. Strip trailing punctuation from references (, . ; ! ?)
+2. Keep punctuation in original text
+3. Test cases:
+   - "See John 3:16!"
+   - "Hello (John 1:1) world"
+   - "Rev. 22:21?"
+   - Em dash in ranges ("Gen 1–2")
+```
+
+---
+
+## Prompt 9: Compound References
+```text
+Implement compound reference parsing:
+1. Handle "and"/"&" separators
+2. Support cross-book ranges ("Gen 1-Exod 2")
+3. Add grammar rules for reference lists
+4. Test cases:
+   - "John 3:16 and 17"
+   - "Gen 1:1 & Exod 2:2"
+   - "Matt 5-7, Luke 3"
+   - Cross-book ranges
+```
+
+---
+
+## Prompt 10: Greedy Parsing & Edge Cases
+```text
+Implement greedy parsing behavior:
+1. Longest-possible match strategy
+2. Prevent mid-reference false positives
+3. Test cases:
+   - "Johnjohn 3:16" (shouldn't parse)
+   - "1 John 2:3" vs "John 2:3"
+   - References followed by book names
+   - Invalid partial matches
+```
+
+---
+
+## Prompt 11: Error Resilience & Final Integration
+```text
+Implement final error handling:
+1. Maintain original text even with parse errors
+2. Validate all position ranges
+3. Integration tests with real-world examples
+4. Test ActionText-style HTML content
+5. Verify nil return vs error raising behavior
+```
+
+---
+
+## Prompt 12: Documentation & Examples
+```text
+Add final polish:
+1. README with usage examples
+2. YARD documentation
+3. Example test case from spec
+4. Version compatibility notes
+5. Caveats section
+```
+
+Each step builds on the previous implementation with incremental complexity. Test coverage grows progressively, ensuring stability at each stage. The final integration connects all components while preserving the original text integrity.

data/ai_artifacts/spec.md

@@ -0,0 +1,181 @@
+# bible_ref_parser — Developer Specification
+
+## Overview
+The `bible_ref_parser` gem extracts Bible references from arbitrary English-language text and returns a structured Ruby object that preserves the original content and annotates the recognized references. It's designed to be integrated into Rails applications (including ActionText) but is generic and framework-agnostic.
+
+## Key Features
+
+- Parses English Bible references in natural text.
+- Supports:
+  - Full book names and common abbreviations.
+  - Single references, compound references, verse/chapter ranges.
+  - Cross-book references.
+  - Greedy parsing behavior.
+- Case-insensitive, whitespace-tolerant, and punctuation-aware.
+- Outputs an object (`BibleReferenceText`) containing annotated segments.
+- Supports reconstruction of the original text with optional embellishment.
+
+## Architecture
+
+### Top-Level Entry Point
+
+```ruby
+BibleRefParser.parse(string)
+```
+
+- Accepts: `String`
+- Returns: `BibleReferenceText` object
+- Raises `BibleRefParser::InvalidInputError` if the input is not a string.
+- Returns `nil` if there are parsing errors.
+
+## Core Class: `BibleReferenceText`
+
+A wrapper for the parsed result that:
+- Exposes the parsed segments.
+- Implements `Enumerable` for iterating over segments.
+- Supports `#to_s` to reconstruct the original text.
+- Allows clients to decorate or transform references.
+
+### Public Interface
+
+```ruby
+class BibleReferenceText
+  include Enumerable
+
+  # Returns all parsed segments (reference and text)
+  def segments => [Segment]
+
+  # Iterate through segments
+  def each(&block)
+
+  # Returns only reference segments
+  def references => [Segment]
+
+  # Reconstructs original text
+  def to_s => String
+end
+```
+
+## Class: `Segment`
+
+Each segment represents either a Bible reference or plain text.
+
+### Attributes
+
+```ruby
+segment.type          # => :reference or :text
+segment.original_text # => Original unaltered text of the segment
+segment.position      # => [start_index, end_index] in original string (only for :reference)
+segment.to_s          # => Delegates to original_text
+```
+
+### Behavior
+
+- Empty segments are skipped.
+- Whitespace before a reference is included in the `:text` segment preceding it.
+- Punctuation immediately after a reference (like `.`, `,`, `!`, `...`) is excluded from the reference.
+- Newlines (`
+`) are treated as regular characters.
+- Em dashes (`—`) are valid range indicators.
+- Parentheses around references are parsed as separate text segments.
+- No references may span line breaks.
+
+## Grammar & Parsing Details
+
+- Built using [Parslet](https://github.com/kschiess/parslet)
+- Case-insensitive parsing
+- Normalizes excess internal whitespace (but preserves original in output)
+- Greedy recognition: references are parsed as long as valid format continues, ending only at a new book name or unrecognized structure.
+
+### Recognized Reference Forms
+
+- Book names: full names or standard abbreviations (e.g., `John`, `Jn`, `1 Cor`, `I Samuel`)
+- Chapters and verses:
+  - `John 3`
+  - `John 3:16`
+  - `John 3:16-18`
+  - `John 3:16–4:2` (multi-chapter)
+  - `John 3-4`
+  - `John 3:16, 17`
+  - `John 3:16 and 17`
+  - `John 3:16 & 17`
+- Compound references:
+  - `John 3:16 and 17` → one reference
+  - `John 3:16 and Gen 1:1` → two references
+- Cross-book references:
+  - `Gen 1:1–Exod 2:3` → single compound reference
+- Supports dashes and em dashes as range separators
+- Allows hyphens/dashes between book name and chapter: `John-3:16`, `John—3:16`
+
+### Not Supported (Treated as plain text)
+
+- Invalid or broken references (e.g., split across lines)
+- Book names without chapter/verse (e.g., just `Genesis`)
+- Roman numerals in chapter/verse (but allowed in book names)
+- URLs or text that resembles a reference but isn't
+- Parentheses, brackets or quotes are not part of the reference
+
+## Error Handling
+
+- Non-string inputs: Raise `BibleRefParser::InvalidInputError`
+- Parser errors (e.g., malformed reference syntax): return `nil`
+- Even on errors, `to_s` must still return the original input string
+- Segments preserve all original content exactly
+
+## Configuration (Future Feature)
+
+- Eventually allow for:
+  - Custom book lists (e.g., apocrypha)
+  - Custom abbreviations
+- For now, built-in list of the 66 canonical books only
+
+## Implementation Notes
+
+- Keep a **small, clear class hierarchy**.
+- Parslet grammar should be isolated and tested.
+- No normalization to OSIS or other external formats (for now).
+- No database or external dependencies.
+- Minimize gem dependencies wherever possible.
+
+## Compatibility
+
+- Ruby `>= 3.0`
+- SemVer-compliant versioning
+- Designed for integration with Rails (including ActionText), but not Rails-dependent
+
+## Testing Plan
+
+- RSpec test suite with 100% segment and parser coverage
+- Fixtures for:
+  - Valid single references
+  - Compound references
+  - Punctuation-adjacent references
+  - Invalid or partial references
+  - Multi-line inputs
+  - References inside ActionText-style content
+- Test `#segments`, `#references`, `#to_s`, and mutation behavior
+
+## Documentation
+
+- Usage examples in README
+- YARD-style comments for all public classes and methods
+- Document edge cases clearly
+- Include a section for "Gotchas" or "Caveats" in the README
+
+## Example Usage
+
+```ruby
+input = "Check out John 3:16 and Gen 1:1!"
+parsed = BibleRefParser.parse(input)
+
+parsed.segments.each do |segment|
+  if segment.type == :reference
+    puts "Reference: #{segment.original_text} at #{segment.position}"
+  else
+    puts "Text: #{segment.original_text}"
+  end
+end
+
+# Reconstruct the original:
+puts parsed.to_s
+```

data/ai_artifacts/todo.md

@@ -0,0 +1,131 @@
+# bible_ref_parser — Development Checklist
+
+## Setup & Infrastructure
+- [ ] Initialize gem: `bundle gem bible_ref_parser`
+- [ ] Add dependencies: `parslet (~> 2.0)`, `rspec`
+- [ ] Set up RSpec with `bundle exec rspec --init`
+- [ ] Create `lib/bible_ref_parser.rb` with module scaffold
+- [ ] Define `BibleRefParser::InvalidInputError` class
+- [ ] Add empty placeholder classes: `BibleReferenceText`, `Segment`
+- [ ] Write spec: Raise `InvalidInputError` for non-string inputs
+
+---
+
+## Core Parser Implementation
+### Book Names
+- [ ] Create `lib/bible_ref_parser/books.rb` with canonical book list (66 books)
+- [ ] Parslet grammar rules for:
+  - [ ] Full book names (e.g., "Genesis")
+  - [ ] Numeric prefixes ("1 Corinthians", "III John")
+  - [ ] Common abbreviations ("Gen", "Jn")
+- [ ] Tests:
+  - [ ] Match all 66 books in all formats
+  - [ ] Case insensitivity (e.g., "gen" vs "GEN")
+  - [ ] Reject non-biblical names (e.g., "Harry Potter")
+
+### Chapter/Verse Parsing
+- [ ] Parslet rules for:
+  - [ ] Simple chapter (`3`)
+  - [ ] Chapter-verse (`3:16`)
+  - [ ] Ranges (`16-18`, `3:16–4:2`)
+  - [ ] Comma-separated verses (`16,17`)
+- [ ] Tests:
+  - [ ] Valid numbers (`John 3:16-18`)
+  - [ ] Invalid formats (`John 3:abc`)
+  - [ ] Position tracking accuracy
+
+### Reference Assembly
+- [ ] Combine book + chapter/verse rules into `reference` rule
+- [ ] Handle optional whitespace between components
+- [ ] Tests:
+  - [ ] Basic references (`Gen 1`, `John 3:16`)
+  - [ ] Edge cases (`1 Cor 15:20-22`)
+
+---
+
+## Segmentation & Classes
+### Segment Class
+- [ ] Implement `type` attribute (`:reference`/`:text`)
+- [ ] Store `original_text` and `position`
+- [ ] Add `to_s` delegation to `original_text`
+- [ ] Validate and skip empty segments
+- [ ] Tests:
+  - [ ] Segment type assignment
+  - [ ] Position accuracy
+  - [ ] Empty segment filtering
+
+### Text Segmentation
+- [ ] Split input into alternating text/reference segments
+- [ ] Preserve whitespace/newlines in original text
+- [ ] Tests:
+  - [ ] Mixed content (`"Hello John 3:16!"`)
+  - [ ] Consecutive references (`Gen 1:1, Exod 2:2`)
+  - [ ] Newline handling (`"John\n3:16"`)
+
+### BibleReferenceText Class
+- [ ] Implement `Enumerable` with `each` method
+- [ ] Add `#segments` and `#references` filters
+- [ ] Reconstruct original text via `to_s`
+- [ ] Return `nil` on parser errors
+- [ ] Tests:
+  - [ ] Enumeration behavior
+  - [ ] Round-trip reconstruction (`parsed.to_s == input`)
+
+---
+
+## Advanced Parsing
+### Punctuation Handling
+- [ ] Strip trailing punctuation from references (`!`, `,`, `.`)
+- [ ] Preserve punctuation in original text
+- [ ] Tests:
+  - [ ] `"John 3:16!"` → reference is `John 3:16`
+  - [ ] Parentheses handling (`(Gen 1:1)`)
+  - [ ] Em dash in ranges (`Gen 1–2`)
+
+### Compound References
+- [ ] Support `and`/`&` separators
+- [ ] Cross-book ranges (`Gen 1:1–Exod 2:3`)
+- [ ] Tests:
+  - [ ] `John 3:16 and 17` → single reference
+  - [ ] `Gen 1:1 & Exod 2:2` → two references
+  - [ ] Cross-book range parsing
+
+### Greedy Parsing
+- [ ] Longest-possible match strategy
+- [ ] Prevent false positives (e.g., `Johnjohn 3:16`)
+- [ ] Tests:
+  - [ ] Ambiguous cases (`1 John 2:3` vs `John 2:3`)
+  - [ ] References followed by book names (`Gen 1:1 Exodus`)
+
+---
+
+## Error Handling & Integration
+- [ ] Ensure `to_s` returns original text even on errors
+- [ ] Validate all `position` ranges are within input bounds
+- [ ] Integration tests:
+  - [ ] Real-world examples (e.g., sermon text)
+  - [ ] ActionText-style HTML content
+- [ ] Finalize error behavior:
+  - [ ] Raise `InvalidInputError` for non-strings
+  - [ ] Return `nil` for malformed references
+
+---
+
+## Documentation & Polish
+- [ ] Write README with:
+  - [ ] Usage examples
+  - [ ] Key features/limitations
+  - [ ] Version compatibility (Ruby >= 3.0)
+- [ ] Add YARD comments to public methods
+- [ ] Include example from spec (`John 3:16 and Gen 1:1`)
+- [ ] Document caveats:
+  - [ ] No support for standalone book names
+  - [ ] Parentheses treated as plain text
+
+---
+
+## Final Checks
+- [ ] Verify 100% test coverage for segments/parser
+- [ ] Run RuboCop for style consistency
+- [ ] Test installation in a dummy Rails app
+- [ ] Publish gem to RubyGems (optional)

data/lib/bible_ref_parser/bible_reference_text.rb

@@ -0,0 +1,35 @@
+module BibleRefParser
+  class BibleReferenceText
+    include Enumerable
+
+    def initialize(text)
+      raise InvalidInputError, "Expected a string, got #{text.class}" unless text.respond_to?(:to_str)
+      @original_text = text.to_str
+      @segments = parse_segments
+    end
+
+    def segments
+      @segments || []
+    end
+
+    def references
+      segments.select(&:reference?)
+    end
+
+    def each(&block)
+      segments.each(&block)
+    end
+
+    def to_s
+      segments.map(&:to_s).join
+    end
+
+    private
+
+    def parse_segments
+      SegmentParser.new.parse(@original_text)
+    rescue Parslet::ParseFailed
+      nil
+    end
+  end
+end

data/lib/bible_ref_parser/books.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module BibleRefParser
+  BOOKS = {
+    # Old Testament (39 books)
+    "Genesis" => ["Gen", "Ge", "Gn"],
+    "Exodus" => ["Ex", "Exod", "Exo"],
+    "Leviticus" => ["Lev", "Le", "Lv"],
+    "Numbers" => ["Num", "Nu", "Nm", "Nb"],
+    "Deuteronomy" => ["Deut", "De", "Dt"],
+    "Joshua" => ["Josh", "Jos", "Jsh"],
+    "Judges" => ["Judg", "Jdg", "Jg", "Jdgs"],
+    "Ruth" => ["Rth", "Ru"],
+    "1 Samuel" => ["1 Sam", "1 Sm", "1 Sa", "1S"],
+    "2 Samuel" => ["2 Sam", "2 Sm", "2 Sa", "2S"],
+    "1 Kings" => ["1 Kgs", "1 Ki", "1K"],
+    "2 Kings" => ["2 Kgs", "2 Ki", "2K"],
+    "1 Chronicles" => ["1 Chron", "1 Chr", "1 Ch", "1Ch"],
+    "2 Chronicles" => ["2 Chron", "2 Chr", "2 Ch", "2Ch"],
+    "Ezra" => ["Ezr", "Ez"],
+    "Nehemiah" => ["Neh", "Ne"],
+    "Esther" => ["Est", "Es"],
+    "Job" => ["Jb"],
+    "Psalms" => ["Psalm", "Ps", "Psa", "Psm", "Pss"],
+    "Proverbs" => ["Prov", "Pr", "Prv"],
+    "Ecclesiastes" => ["Eccl", "Ecc", "Qoh"],
+    "Song of Solomon" => ["Song", "SOS", "Song of Songs"],
+    "Isaiah" => ["Isa", "Is"],
+    "Jeremiah" => ["Jer", "Je", "Jr"],
+    "Lamentations" => ["Lam", "La"],
+    "Ezekiel" => ["Ezek", "Eze", "Ezk"],
+    "Daniel" => ["Dan", "Da", "Dn"],
+    "Hosea" => ["Hos", "Ho"],
+    "Joel" => ["Jl"],
+    "Amos" => ["Am"],
+    "Obadiah" => ["Obad", "Ob"],
+    "Jonah" => ["Jon", "Jnh"],
+    "Micah" => ["Mic", "Mc"],
+    "Nahum" => ["Nah", "Na"],
+    "Habakkuk" => ["Hab", "Hb"],
+    "Zephaniah" => ["Zeph", "Zep", "Zp"],
+    "Haggai" => ["Hag", "Hg"],
+    "Zechariah" => ["Zech", "Zec", "Zc"],
+    "Malachi" => ["Mal", "Ml"],
+
+    # New Testament (27 books)
+    "Matthew" => ["Matt", "Mt"],
+    "Mark" => ["Mrk", "Mk", "Mr"],
+    "Luke" => ["Luk", "Lk"],
+    "John" => ["Jn", "Jhn"],
+    "Acts" => ["Act", "Ac"],
+    "Romans" => ["Rom", "Ro", "Rm"],
+    "1 Corinthians" => ["1 Cor", "1 Co", "1C"],
+    "2 Corinthians" => ["2 Cor", "2 Co", "2C"],
+    "Galatians" => ["Gal", "Ga"],
+    "Ephesians" => ["Eph", "Ep"],
+    "Philippians" => ["Phil", "Php", "Pp"],
+    "Colossians" => ["Col", "Co"],
+    "1 Thessalonians" => ["1 Thess", "1 Thes", "1 Th", "1Th"],
+    "2 Thessalonians" => ["2 Thess", "2 Thes", "2 Th", "2Th"],
+    "1 Timothy" => ["1 Tim", "1 Ti", "1T"],
+    "2 Timothy" => ["2 Tim", "2 Ti", "2T"],
+    "Titus" => ["Tit", "Ti"],
+    "Philemon" => ["Philem", "Phm", "Pm"],
+    "Hebrews" => ["Heb"],
+    "James" => ["Jas", "Jm"],
+    "1 Peter" => ["1 Pet", "1 Pe", "1P", "1 Pt"],
+    "2 Peter" => ["2 Pet", "2 Pe", "2P", "2 Pt"],
+    "1 John" => ["1 Jn", "1 Jhn", "1J", "1 Jo"],
+    "2 John" => ["2 Jn", "2 Jhn", "2J", "2 Jo"],
+    "3 John" => ["3 Jn", "3 Jhn", "3J", "3 Jo"],
+    "Jude" => ["Jd"],
+    "Revelation" => ["Rev", "Re", "Rv"]
+  }.freeze
+
+  def self.book_names(alternative_names: true)
+    BOOKS.keys
+      .then { |full_names| alternative_names ? full_names + BOOKS.values.flatten : full_names }
+  end
+end

data/lib/bible_ref_parser/parser.rb

@@ -0,0 +1,121 @@
+# lib/parser.rb
+
+require "parslet"
+
+module BibleRefParser
+  class Parser < Parslet::Parser
+    def initialize(book_names: BibleRefParser.book_names)
+      @book_names = book_names
+      super()
+    end
+
+    def istr(string)
+      # Case-insensitve, whitespace-optional, allow to be terminated with a dot
+      string
+        .chars
+        .map { |char| (char == " ") ? space? : match["#{char.downcase}#{char.upcase}"] }
+        .reduce(:>>) >> dot?
+    end
+
+    rule(:space) { match('\s').repeat(1) }
+    rule(:space?) { space.maybe }
+
+    rule(:dot) { match('\.').repeat(1) }
+    rule(:dot?) { dot.maybe }
+
+    rule(:book_name) do
+      # Sort book names by length (longest first) for greedy matching
+      @book_names
+        .sort_by { |name| -name.length }
+        .map { |book_name| istr(book_name) }
+        .reduce(:|)
+        .as(:book)
+    end
+
+    rule(:range_sep) do
+      # Dash, en dash or em dash, surrounded by optional whitespace
+      space? >> match["-–—"] >> space?
+    end
+
+    rule(:list_sep) do
+      space? >> (match[",;&"] | str("and")) >> space? >> book_name.absent?
+    end
+
+    rule(:colon) do
+      space? >> str(":") >> space?
+    end
+
+    rule(:reference_int) do
+      match("[1-9]") >> match("[0-9]").repeat(0)
+    end
+
+    rule(:chapter) do
+      reference_int.as(:chapter)
+    end
+
+    rule(:chapter_range) do
+      (chapter.as(:start) >> range_sep >> chapter.as(:end)).as(:chapter_range)
+    end
+
+    rule(:verse) do
+      reference_int.as(:verse)
+    end
+
+    rule(:verse_range) do
+      (verse.as(:start) >> range_sep >> verse.as(:end)).as(:verse_range)
+    end
+
+    rule(:explicit_verse) do
+      (chapter >> colon >> verse).as(:explicit_verse)
+    end
+
+    rule(:explicit_verse_range) do
+      (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)
+    end
+
+    rule(:chapter_with_verse_list) do
+      (chapter >> colon >> verse_list).as(:chapter_with_verse_list)
+    end
+
+    rule(:chapter_with_verse_range) do
+      (chapter >> colon >> verse_range).as(:chapter_with_verse_range)
+    end
+
+    rule(:chapter_with_verses) do
+      chapter_with_verse_list | chapter_with_verse_range
+    end
+
+    rule(:indicator) do
+      explicit_verse_range | chapter_range | chapter_with_verses | explicit_verse | chapter
+    end
+
+    rule(:indicator_list) do
+      indicator.repeat(1).as(:indicator_list) |
+        (indicator >> (list_sep >> indicator).repeat(1)).as(:indicator_list)
+    end
+
+    rule(:cross_book_range) do
+      (
+        (book_name >> space? >> (explicit_verse | chapter)).as(:start) >>
+        range_sep >>
+        (book_name >> space? >> (explicit_verse | chapter)).as(:end)
+      ).as(:cross_book_range)
+    end
+
+    rule(:reference) { cross_book_range | (book_name >> space? >> indicator_list) }
+
+    rule(:non_reference_text) { (reference.absent? >> any).repeat(1) }
+
+    rule(:html_tag) { str("<") >> (str(">").absent? >> any).repeat >> str(">") }
+
+    rule(:document) do
+      (html_tag.absent? >> (reference.as(:reference) | non_reference_text.as(:text))).repeat.as(:segments)
+    end
+
+    root(:document)
+  end
+end

data/lib/bible_ref_parser/segment.rb

@@ -0,0 +1,60 @@
+# lib/segment.rb
+
+module BibleRefParser
+  # Class to represent a segment of a Bible reference
+  class Segment
+    attr_reader :type, :original_text, :position
+
+    # @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)
+      @type = type
+      @original_text = original_text
+      @position = position
+      validate!
+    end
+
+    # Returns the original text
+    def to_s
+      original_text
+    end
+
+    # @return [Boolean] true if this is a Bible reference segment
+    def reference?
+      type == :reference
+    end
+
+    # @return [Boolean] true if this is a plain text segment
+    def text?
+      type == :text
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "Type must be :reference or :text" unless [:reference, :text].include?(type)
+      validate_position!
+      validate_text!
+    end
+
+    private
+
+    def validate_position!
+      unless position.is_a?(Range) &&
+          position.begin.is_a?(Integer) &&
+          position.end.is_a?(Integer) &&
+          position.begin >= 0 &&
+          position.end >= position.begin
+        raise InvalidInputError, "Invalid position range: #{position.inspect}"
+      end
+    end
+
+    def validate_text!
+      if reference?
+        raise InvalidInputError, "Empty reference" if original_text.strip.empty?
+        raise InvalidInputError, "Reference contains HTML" if original_text.match?(/<[^>]+>/)
+      end
+    end
+  end
+end

data/lib/bible_ref_parser/segment_parser.rb

@@ -0,0 +1,77 @@
+module BibleRefParser
+  class SegmentParser
+    def initialize(book_names: BibleRefParser.book_names)
+      @reference_parser = Parser.new(book_names: book_names)
+    end
+
+    def parse(text)
+      text = text.to_s.dup.freeze
+      begin
+        @tree = @reference_parser.parse(text)[:segments]
+        segments = build_segments(text)
+        validate_segments!(segments, text)
+        segments
+      rescue Parslet::ParseFailed, InvalidInputError
+        # Return single text segment containing full original text on error
+        [Segment.new(:text, text, 0...text.length)]
+      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 }
+      unless coverage.begin == 0 && coverage.end == full_text.length
+        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

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

data/lib/bible_ref_parser.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "bible_ref_parser/version"
+
+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/segment_parser"
+
+module BibleRefParser
+  # Custom error class for invalid input
+  class InvalidInputError < StandardError; end
+end

data/sig/bible_ref_parser.rbs

@@ -0,0 +1,4 @@
+module BibleRefParser
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: bible_ref_parser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fabio Papa
+bindir: exe
+cert_chain: []
+date: 2025-05-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: parslet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.15.0
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: reline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby gem for parsing an normalizing Bible references
+email:
+- fabtheman@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- ai_artifacts/prompt_plan.md
+- ai_artifacts/spec.md
+- ai_artifacts/todo.md
+- lib/bible_ref_parser.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/segment.rb
+- lib/bible_ref_parser/segment_parser.rb
+- lib/bible_ref_parser/version.rb
+- sig/bible_ref_parser.rbs
+homepage: https://github.com/fapapa/bible_ref_parser
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/fapapa/bible_ref_parser
+  source_code_uri: https://github.com/fapapa/bible_ref_parser
+  changelog_uri: https://github.com/fapapa/bible_ref_parser/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A parser for Bible references
+test_files: []