bible_parser_flutter 0.1.0+2

A Flutter package for parsing Bible texts in OSIS, USFX, and ZXBML formats with direct parsing and database-backed approaches.

Bible Parser Flutter

A Flutter package for parsing Bible texts in various XML formats (USFX, OSIS, ZEFANIA). This package provides both direct parsing and database-backed approaches for handling Bible data in your Flutter applications. The parser is optimized for production use with proper error handling.

Features

• 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 for improved performance
• Search functionality for verses
• Retrieve verses by book and chapter

Getting Started

Installation

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

dependencies:
  bible_parser_flutter: ^0.0.1

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 {
  // Create a parser with automatic format detection
  final parser = BibleParser(File('path/to/bible.xml'));
  
  // 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(xmlPath: 'path/to/bible.xml');
  
  // Initialize the database (parses XML and stores in SQLite)
  // This only needs to be done once, typically on first app launch
  await repository.initialize();
  
  // 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();
}

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 the open-bibles GitHub repository.