bible_parser_flutter

🆕 New Features

• Book toc fields from USFX <toc> tags
  • Book.longTitle — full descriptive title (toc level 1), e.g. "The First Book of Moses, Commonly Called Genesis"
  • Book.shortTitle — common short title (toc level 2), e.g. "Genesis"
  • Book.abbreviation — standard abbreviation (toc level 3), e.g. "Gen"
  • All three fields are optional (null when not present in the source XML)
• Database persistence for toc fields
  • New columns long_title, short_title, abbreviation on books table (database version 6)
  • Non-destructive migration via ALTER TABLE — existing data is preserved

🔄 Breaking Changes

• None — new fields are nullable and fully backward compatible.

📦 Database Schema

• Version bumped from 5 → 6
• books table gains: long_title TEXT, short_title TEXT, abbreviation TEXT

Testing

• Added 2 automated tests in usfx_toc_test.dart

🆕 New Features

• Footnote parsing for USFX format - <f> tags are now fully parsed
  • New Footnote class with id, marker, and content fields
  • Footnote positions encoded as zero-width TextSegment entries with attributes['footnote'] set
  • Superscript markers (¹, ², ³...) auto-assigned per verse
  • verse.hasFootnotes convenience getter
  • segment.isFootnoteMarker and segment.footnoteId getters on TextSegment
• Database persistence for footnotes
  • New verse_footnotes table (database version 5)
  • Automatic migration from version 4 — no data loss
  • Footnotes loaded automatically in getVerses, getVerse, and searchVerses
• Footnote exported from main library entry point

🔄 Breaking Changes

• None — fully backward compatible. Verses without footnotes return null for footnotes.

📦 Database Schema

• Version bumped from 4 → 5
• New table: verse_footnotes (id, verse_id, footnote_id, marker, content)

Testing

• Added 8 automated tests in usfx_footnote_test.dart

Major Features:

• Complete desktop app for Bible database creation
• Database export with user-controlled file saving
• Database loading from existing files
• Cross-platform support (macOS, Windows, Linux)
• Production-ready XML to database workflow

Enhancements:

• BibleRepository.fromDatabase() constructor
• Comprehensive test coverage
• Detailed documentation and workflow guides
• File management and persistence documentation

This release transforms the package from a parsing library to a complete Bible database management solution.

🆕 Major Features

• Complete Desktop App - Full-featured Bible database creation tool
  • Cross-platform support (macOS, Windows, Linux)
  • File picker integration for XML selection
  • Database export with user-controlled file saving
  • Database loading from existing files for testing
  • Production-ready XML to database workflow

📱 New Package Capabilities

• BibleRepository.fromDatabase() constructor - Direct database file loading
  • Enables mobile apps to load pre-created databases without XML parsing
  • Perfect for production apps with Firebase distribution
• Enhanced path handling - Improved database file path management
• Comprehensive test coverage - Full test suite for new desktop features

🛠️ Desktop App Features

• Dual Mode Interface - Switch between "Create from XML" and "Load from Database"
• File Management - Intelligent temporary/permanent file handling
  • Temporary storage in app's dbfiles/ directory
  • Persists across flutter run sessions
  • Overwrites when creating same database name
• User-Controlled Export - Download databases to any location (Desktop, Documents, Downloads)
• Production Workflow - XML → Database → Firebase → Mobile Apps

📚 Documentation & Examples

• Updated README with desktop app installation and usage guide
• File Management Documentation - Complete persistence behavior guide
• Mobile Integration Examples - Firebase download patterns for mobile apps
• Production Workflow Examples - End-to-end Bible database distribution

🔄 Breaking Changes

• None - Fully backward compatible with existing code

📦 Package Structure

bible_parser_flutter/
├── lib/                    # Core parsing library
├── desktop_app/            # New desktop application
│   ├── lib/main.dart       # Desktop app UI and logic
│   ├── test/               # Desktop app tests
│   └── macos/               # macOS platform files
└── doc/                    # Updated documentation

🎯 Impact

This release transforms the package from a parsing library to a complete Bible database management solution. Developers can now:

• Create production Bible databases with a desktop GUI tool
• Distribute databases via Firebase or other cloud storage
• Load databases directly in mobile apps without XML parsing overhead
• Test and validate Bible data before production deployment

Fixed

• Code quality improvements - Fixed string concatenation linting issues
  • Replaced + operator with string interpolation in USFX parser
  • Changed currentVerse.text + ' ' + trimmedText to '${currentVerse.text} $trimmedText'
  • Fixed in both parseBooks() and parseVerses() methods
  • All 76 tests passing
  • flutter analyze lib/ now reports no issues

Impact

• Expected improvement in pub.dev package score from 140/160 to ~150/160
• Better code maintainability and adherence to Dart style guidelines

Fixed

• Code quality improvements - Fixed string concatenation linting issues
  • Replaced + operator with string interpolation in USFX parser
  • Changed currentVerse.text + ' ' + trimmedText to '${currentVerse.text} $trimmedText'
  • Fixed in both parseBooks() and parseVerses() methods
  • All 76 tests passing
  • flutter analyze lib/ now reports no issues

Impact

• Expected improvement in pub.dev package score from 140/160 to ~150/160
• Better code maintainability and adherence to Dart style guidelines

Added

• Added text support for USFX format - Track translator additions (italicized text) in USFX files
  • Parser now recognizes <add> tags in USFX XML
  • Uses same transChange: 'added' attribute as OSIS format for consistency
  • Works alongside Jesus words (<wj> tags) when both are present
  • Added 7 comprehensive tests for USFX add tag functionality
• Example app improvements
  • Added 3 new USFX Bible files to example assets: eng-kjv-2006.usfx.xml, eng-asv.usfx.xml, eng-webu.usfx.xml
  • Updated asset manifest to include all new XML files
  • Italics toggle now works with both OSIS and USFX formats

Documentation

• Updated README acknowledgments to include eBible.org as a source for Bible XML files

Example Usage

// USFX added text is tracked the same way as OSIS
for (final segment in verse.segments ?? []) {
  if (segment.isAdded) {
    // Render in italics (translator addition)
    print('Italic: ${segment.text}');
  } else if (segment.isJesus) {
    // Render in red (Jesus' words)
    print('Red: ${segment.text}');
  }
}

Added

• Added text support for USFX format - Track translator additions (italicized text) in USFX files
  • Parser now recognizes <add> tags in USFX XML
  • Uses same transChange: 'added' attribute as OSIS format for consistency
  • Works alongside Jesus words (<wj> tags) when both are present
  • Added 7 comprehensive tests for USFX add tag functionality
• Example app improvements
  • Added 3 new USFX Bible files to example assets: eng-kjv-2006.usfx.xml, eng-asv.usfx.xml, eng-webu.usfx.xml
  • Updated asset manifest to include all new XML files
  • Italics toggle now works with both OSIS and USFX formats

Documentation

• Updated README acknowledgments to include eBible.org as a source for Bible XML files

Example Usage

// USFX added text is tracked the same way as OSIS
for (final segment in verse.segments ?? []) {
  if (segment.isAdded) {
    // Render in italics (translator addition)
    print('Italic: ${segment.text}');
  } else if (segment.isJesus) {
    // Render in red (Jesus' words)
    print('Red: ${segment.text}');
  }
}

Version 0.2.3 - Critical bug fix for duplicate verses

Fixed

• Critical bug fix - Fixed duplicate verses affecting all Bible versions
  • OSIS parser fix: Added verseEndedWithEID flag to prevent duplicate verse insertion when processing <verse eID=""/> format (affects KJV and similar OSIS files)
  • Database schema fix: Added UNIQUE constraint on (book_id, chapter_num, verse_num) in verses table to prevent duplicates at database level
  • Database version bumped to 4 with automatic migration that recreates tables and reparses data
  • Both parseBooks() and parseVerses() methods now handle eID format correctly
• All 69 tests passing

Root Cause

The duplicate verses issue had two contributing factors:

1. OSIS parser was adding verses twice when encountering <verse eID=""/> tags
2. Database lacked UNIQUE constraint, allowing duplicate rows even with ConflictAlgorithm.ignore

Impact

• Automatic fix: Existing databases will automatically upgrade to version 4 and reparse data without duplicates
• No manual intervention needed: Users don't need to manually delete database files
• Affects all versions: KJV, ASV, WEB, and any other Bible version will be fixed
• No breaking changes - fully backward compatible

Added

• TransChange support for OSIS format to track added/italicized text
  • Parser now recognizes <transChange type="added"> tags in OSIS XML
  • New transChange getter on TextSegment class
  • New isAdded convenience getter to identify added text segments
  • Apps can now italicize or style text marked as translator additions
• Added comprehensive tests for transChange functionality
• Updated example app to demonstrate italicized text support with toggle switch

Example Usage

// Check if a segment is added text (typically italicized)
for (final segment in verse.segments ?? []) {
  if (segment.isAdded) {
    // Render in italics
    print('Italic: ${segment.text}');
  } else {
    print('Normal: ${segment.text}');
  }
}

Fixed

• Critical iOS/Android compatibility issue - Fixed SQLite error 14 (SQLITE_CANTOPEN) on iOS devices
• Platform detection now correctly uses native sqflite for iOS and Android instead of FFI
• Desktop platforms (Windows, Linux, macOS) continue to use sqflite_common_ffi

Fixes #4

Red-Letter Bible Support

This major feature release adds support for identifying and styling Jesus' words in OSIS and USFX Bible formats.

✨ New Features

• Red-letter Bible support for OSIS and USFX formats
  • New TextSegment class for styled text segments with attributes
  • segments field in Verse class for tracking speaker information
  • Support for <q who="Jesus"> tags in OSIS XML
  • Support for <wj> (Words of Jesus) tags in USFX XML
  • hasJesusWords convenience getter on Verse class
• Database persistence for segments
  • New verse_segments table for storing text segments
  • Automatic segment loading when retrieving verses from database
  • Database version upgraded to 2 with migration support
• Extensible design allows future support for other XML styling tags
• Exported parser classes (OsisParser, UsfxParser, ZefaniaParser) for direct use

🔄 Changes

• OSIS parser now tracks quote tags and speaker attributes
• USFX parser now tracks wj tags and speaker attributes
• Verse class is backward compatible - existing code continues to work
• BibleRepository now persists and retrieves segments automatically
• Database schema updated with proper foreign key constraints and indexes

📚 Documentation

• Added comprehensive design document at /doc/red-letter-bible-support.md
• Updated README with red-letter Bible usage examples

🧪 Testing

• Added 5 tests for OSIS red-letter parsing
• Added 5 tests for USFX red-letter parsing
• Added 5 tests for database segment persistence
• Added 29 tests for TextSegment serialization
• Added 1 test for cross-platform database support
• All 65 tests passing

📦 Package

Published to pub.dev: https://pub.dev/packages/bible_parser_flutter

🔗 Links

• Full Changelog
• Documentation

Added

• Red-letter Bible support for OSIS and USFX formats
  • New TextSegment class for styled text segments with attributes
  • segments field in Verse class for tracking speaker information and other attributes
  • Support for <q who="Jesus"> tags in OSIS XML to identify Jesus' words
  • Support for <wj> (Words of Jesus) tags in USFX XML
  • hasJesusWords convenience getter on Verse class
• Database persistence for segments
  • New verse_segments table for storing text segments
  • Automatic segment loading when retrieving verses from database
  • Database version upgraded to 2 with migration support
• Extensible design allows future support for other XML styling tags (italics, notes, poetry, etc.)
• Exported parser classes (OsisParser, UsfxParser, ZefaniaParser) for direct use

Changed

• OSIS parser now tracks quote tags and speaker attributes
• USFX parser now tracks wj tags and speaker attributes
• Verse class is backward compatible - existing code continues to work
• BibleRepository now persists and retrieves segments automatically
• Database schema updated with proper foreign key constraints and indexes

Documentation

• Added comprehensive design document at /doc/red-letter-bible-support.md

Testing

• Added 5 tests for OSIS red-letter parsing
• Added 5 tests for USFX red-letter parsing
• Added 5 tests for database segment persistence
• Added 29 tests for TextSegment serialization
• Added 1 test for cross-platform database support
• All 65 tests passing

Changed

• Updated example app to demonstrate red-letter Bible feature
• Added toggle switch to enable/disable red-letter display
• Jesus' words are now visually indicated with [JESUS: ...] markers

Features

• Support for multiple Bible XML formats:
  • OSIS (Open Scripture Information Standard)
  • USFX (Unified Scripture Format XML)
  • ZXBML (Zefania XML Bible Markup Language)
• Automatic format detection
• Memory-efficient XML parsing using proper async streams
• Production-ready with proper error handling and no debug statements

Bible Repository Features

• SQLite database caching for improved performance
• Methods to retrieve books, chapters, and verses
• Verse retrieval by book and chapter
• Text search functionality across verses

Example App

• Demonstrates both direct parsing and database approaches
• UI for selecting between different Bible formats
• Book and chapter selection interface
• Verse display with proper formatting and scrolling
• Search functionality for finding verses containing specific text

Bug Fixes

N/A

Documentation

• Added note about tested XML file compatibility in README
• Removed unpublished status from README title

Bug Fixes

• Fixed verse text concatenation with proper space handling and empty text checks

Documentation

N/A

Bug Fixes

• Fixed USFX parser to properly handle chapter endings and ensure all chapters are added to books
• Fixed database handling in BibleRepository with proper null safety

Improvements

• Enhanced BibleRepository with better database initialization and connection management
• Improved database operations with proper transaction handling and batch processing
• Added explicit database naming for better multi-Bible support
• Removed unused code and dependencies

Bug Fixes

• Fixed handling of footnotes and cross-references in USFX parser