Bible Parser Flutter

A Flutter package for parsing Bible texts in OSIS, USFX, and ZEFANIA XML formats with both direct parsing and database-backed approaches. Now includes a desktop app for Bible database creation and management!

🆕 v0.3.0 Features

✅ Desktop App: Complete Bible database creation tool
✅ Database Export: User-controlled file saving
✅ Database Loading: Direct database file loading
✅ Cross-Platform: macOS, Windows, Linux support
✅ Production Workflow: XML → Database → Mobile App Distribution

📱 Desktop App Usage

Installation & Setup

# Clone the repository to get the desktop app
git clone https://github.com/Omarzintan/bible_parser_flutter.git
cd bible_parser_flutter

# Navigate to desktop app
cd desktop_app
flutter pub get
flutter run -d macos  # or -d windows, -d linux

Alternative: Download Desktop App Only

If you only want the desktop app without the full package:

# Clone and checkout only the desktop app
git clone --filter=blob:'desktop_app/*' https://github.com/Omarzintan/bible_parser_flutter.git
cd bible_parser_flutter/desktop_app
flutter pub get
flutter run -d macos

Workflow

Create Database: Select XML file → Click "Create Database"
Download: Click "Download" → Choose save location (Desktop, Documents, etc.)
Test: Switch to "Load from Database" mode → Test exported file
Deploy: Upload db file to any storage service (Firebase, Google Drive, etc.)

File Management

Temporary Storage: Databases created in app's dbfiles/ directory
Persistence: Files remain after stopping flutter run
Overwrite: Creating same database name overwrites previous file
Download: User saves to permanent location of their choice

📦 Package Contents

Core Library (`lib/`)

Bible parsing for OSIS, USFX, and ZEFANIA XML formats
Database repository with SQLite caching
Text segments for red-letter and added text support
Cross-platform mobile and web support

Desktop App (`desktop_app/`)

GUI tool for Bible database creation and management
Cross-platform desktop support (macOS, Windows, Linux)
File picker integration for XML selection
Database export with user-controlled saving
Database loading for testing exported files
Production workflow ready for Firebase distribution

Note: The desktop app is included in the Git repository but excluded from the published Flutter package to keep the package size reasonable. Clone the repository to access the desktop app.

🆕 Red-Letter Bible Support - Identify and style Jesus' words in OSIS and USFX formats
🆕 Added Text Support - Track translator additions (italicized text) in OSIS and USFX formats
Parse Bible texts in multiple formats (USFX, OSIS, ZEFANIA)
Automatic format detection
Memory-efficient SAX-style XML parsing using proper async streams
Note: This package has only been tested to work with the XML files under example/assets/open-bibles. Users are welcome to try the parser with other XML files and create a GitHub issue if they encounter any errors.
Database caching with automatic segment persistence
Search functionality for verses
Retrieve verses by book and chapter
Cross-platform support (iOS, Android, Web, Windows, Linux, macOS)

Getting Started

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  bible_parser_flutter: ^0.2.0

Then run:

flutter pub get

Prerequisites

Flutter SDK
A Bible XML file in one of the supported formats (USFX, OSIS, ZEFANIA)

Usage

Direct Parsing Approach

Parse a Bible file directly without database caching. This is simpler but less efficient for repeated access:

import 'dart:io';
import 'package:bible_parser_flutter/bible_parser_flutter.dart';

Future<void> parseBible() async {
   // Load the XML content from assets
   final xmlString =
       await DefaultAssetBundle.of(context).loadString(xmlPath);

   // Create the original parser with the XML string
   final parser = BibleParser.fromString(xmlString,
       format: currentFormat.name.toUpperCase());
  
  // Access books
  await for (final book in parser.books) {
    print('${book.title} (${book.id})');
    
    // Access chapters and verses
    for (final chapter in book.chapters) {
      for (final verse in chapter.verses) {
        print('${book.id} ${verse.chapterNum}:${verse.num} - ${verse.text}');
      }
    }
  }
  
  // Or access all verses directly
  await for (final verse in parser.verses) {
    print('${verse.bookId} ${verse.chapterNum}:${verse.num} - ${verse.text}');
  }
}

Database Approach (Recommended for Production)

For better performance, especially in production apps, use the database approach:

import 'package:bible_parser_flutter/bible_parser_flutter.dart';

Future<void> useBibleRepository() async {
  // Create a repository
  final repository = BibleRepository.fromString(
    xmlString: 'path/to/bible.xml',
    format: 'USFX',
  );
  
  // Initialize the database (parses XML and stores in SQLite)
  // This only needs to be done once, typically on first app launch
  await repository.initialize('some_database_name.db');
  
  // Get all books
  final books = await repository.getBooks();
  for (final book in books) {
    print('${book.title} (${book.id})');
  }
  
  // Get verses from a specific chapter
  final verses = await repository.getVerses('gen', 1);
  for (final verse in verses) {
    print('${verse.bookId} ${verse.chapterNum}:${verse.num} - ${verse.text}');
  }
  
  // Search for verses containing specific text
  final searchResults = await repository.searchVerses('love');
  print('Found ${searchResults.length} verses containing "love"');
  
  // Don't forget to close the database when done
  await repository.close();
}

Red-Letter Bible Support (New in v0.2.0)

Access Jesus' words with text segments:

// Parse a Bible with red-letter support
final parser = BibleParser.fromString(xmlString, format: 'OSIS');

await for (final verse in parser.verses) {
  // Check if verse contains Jesus' words
  if (verse.hasJesusWords) {
    print('Verse ${verse.chapterNum}:${verse.num} has Jesus speaking!');
    
    // Access individual segments
    for (final segment in verse.segments!) {
      if (segment.isJesus) {
        // Display in red or special styling
        print('Jesus said: "${segment.text}"');
      } else {
        // Display normally
        print('Narrator: "${segment.text}"');
      }
    }
  }
  
  // Or just use the full text (backward compatible)
  print(verse.text);
}

Supported formats:

OSIS: <q who="Jesus"> tags
USFX: <wj> (Words of Jesus) tags

Database persistence: Segments are automatically saved and loaded from the database when using BibleRepository.

For more details, see the Red-Letter Bible Support documentation.

Added/Italicized Text Support

The parser also tracks text marked as translator additions (typically italicized in printed Bibles):

// Get a verse with added text
final verse = await repository.getVerse('Matt', 27, 65);

if (verse.segments != null) {
  for (final segment in verse.segments!) {
    if (segment.isAdded) {
      // Display in italics (translator addition)
      print('Italic: "${segment.text}"');
    } else if (segment.isJesus) {
      // Display in red (Jesus' words)
      print('Red: "${segment.text}"');
    } else {
      // Display normally
      print('Normal: "${segment.text}"');
    }
  }
}

Supported formats:

OSIS: <transChange type="added"> tags
USFX: <add> tags

Example: In Matthew 27:65 KJV, the word "it" is marked as added text:

Pilate said unto them, Ye have a watch: go your way, make it as sure as ye can.

Performance Considerations

Direct Parsing

Simple implementation
No database setup required
Always uses the latest source files
CPU and memory intensive
Slower initial load times
Higher battery consumption
Repeated parsing on each access

Database Approach

Much faster access once data is loaded
Lower memory usage during normal operation
Better user experience with instant search and navigation
Reduced battery consumption
Works offline without re-parsing
Requires initial setup complexity

Example

See the /example folder for a complete working example of both approaches. The example app demonstrates:

Parsing Bible files in OSIS and USFX formats
Database initialization and querying
Browsing verses by book and chapter selection

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Inspired by the Ruby bible_parser library.

Bible XML files in the example are from:

open-bibles GitHub repository
eBible.org - Free Bible translations in many languages

Bible Parser Flutter

🆕 v0.3.0 Features

📱 Desktop App Usage

Installation & Setup

Alternative: Download Desktop App Only

Workflow

File Management

📦 Package Contents

Core Library (`lib/`)

Desktop App (`desktop_app/`)

Getting Started

Installation

Prerequisites

Usage

Direct Parsing Approach

Database Approach (Recommended for Production)

Red-Letter Bible Support (New in v0.2.0)

Added/Italicized Text Support

Performance Considerations

Direct Parsing

Database Approach

Example

License

Acknowledgments

Libraries

bible_parser_flutter package

Bible Parser Flutter

🆕 v0.3.0 Features

📱 Desktop App Usage

Installation & Setup

Alternative: Download Desktop App Only

Workflow

File Management

📦 Package Contents

Core Library (lib/)

Desktop App (desktop_app/)

Getting Started

Installation

Prerequisites

Usage

Direct Parsing Approach

Database Approach (Recommended for Production)

Red-Letter Bible Support (New in v0.2.0)

Added/Italicized Text Support

Performance Considerations

Direct Parsing

Database Approach

Example

License

Acknowledgments

Libraries

bible_parser_flutter package

Core Library (`lib/`)

Desktop App (`desktop_app/`)