mushaf_engine 1.0.0

A Dart implementation of a Quran Mushaf navigation engine for line-based navigation through the Quran

example/example.dart

// ignore_for_file: avoid_print

import 'package:mushaf_engine/mushaf_engine.dart';

void main() {
  // Load the included Mushaf data from the package
  // The data file is bundled with the package, so users don't need to provide it
  final data = MushafData.loadKingFahadMushafSync();
  final mushaf = KingFahadMushaf.loadFromJson(data);
  final engine = BaseMushafEngine(mushaf);

  print('=== Example 1: Simple Navigation ===');
  // Navigate 15 lines from Sura 5, Verse 3 in upward direction
  final result1 = engine.navigate(NavigateParams(
    lines: 15,
    from: const VersePosition(5, 3),
    direction: Direction.upwards,
    settings: NavigationSettings.builder().build(),
  ));
  print(result1);

  print('\n=== Example 2: Navigation with Settings ===');
  // Create settings with all features
  final settings = NavigationSettings.builder()
      .setIgnoreSuraHeader(true) // Exclude sura headers from calculations
      .setIterationLimit(3) // Allow 3 complete cycles
      .setUpperBound(const VersePosition(2, 1)) // Start of Al-Baqarah
      .setLowerBound(const VersePosition(2, 286)) // End of Al-Baqarah
      .build();

  // Use settings in navigation
  final result2 = engine.navigate(NavigateParams(
    lines: 100,
    from: const VersePosition(2, 1),
    direction: Direction.downwards,
    settings: settings,
  ));
  print(result2);

  print('\n=== Example 3: Cycling Navigation ===');
  // Create bounds for cycling through Juz' Amma (Sura 78-114)
  final bounds = NavigationBounds(
    iterationLimit: 5, // Allow 5 complete cycles through the range
    upperBound: const VersePosition(78, 1), // Upper bound (start)
    lowerBound: const VersePosition(114, 6), // Lower bound (end)
  );

  final cycleSettings = NavigationSettings.builder().setBounds(bounds).build();

  // Navigation will cycle within this range up to 5 times
  final result3 = engine.navigate(NavigateParams(
    lines: 1000,
    from: const VersePosition(78, 1),
    direction: Direction.downwards,
    settings: cycleSettings,
  ));
  print(result3);

  print('\n=== Example 4: Calculate Distance ===');
  // Calculate lines between verses
  final lines = engine.calculateLines(
    start: const VersePosition(2, 255), // Ayat al-Kursi
    end: const VersePosition(3, 200), // End of Al-Imran
    direction: Direction.downwards,
    settings: NavigationSettings.builder().build(),
  );
  print('Distance from Ayat al-Kursi to end of Al-Imran: $lines lines');

  print('\n=== Example 5: Get Verse ===');
  // Get a specific verse
  final verse = engine.getVerse(1, 1);
  if (verse != null) {
    print('First verse of Al-Fatiha: $verse');
  }

  print('\n=== Example 6: Get Sura Info ===');
  // Get sura metadata
  final suraInfo = engine.getSuraInfo(2);
  if (suraInfo != null) {
    print('Sura Al-Baqarah:');
    print('  Total verses: ${suraInfo.totalVerses}');
    print('  Lines: ${suraInfo.lines}');
    print('  Lines with header: ${suraInfo.linesWithHeader}');
    print('  Pages: ${suraInfo.startPage} - ${suraInfo.endPage}');
  }
}