mushaf_engine

A Dart implementation of a Quran Mushaf navigation engine. This library provides functionality for navigating through the Quran by page, verse, and lines with advanced features like cycling navigation, custom bounds, and configurable header handling. It's based on the King Fahad Quran Printing Complex's Mushaf edition.

Features

Line-based Navigation: Navigate through the Quran by number of lines in either upward or downward direction
Cycling Navigation: Configure navigation to cycle through bounded ranges with iteration limits
Custom Bounds: Set upper and lower bounds to restrict navigation to specific verse ranges
Sura Header Control: Choose whether to include or exclude sura headers from line calculations
Comprehensive Results: Get detailed information about navigation results including overflow conditions
Rich Metadata: Access metadata about suras, verses, and pages
Verse Lookup: Find verses by sura and verse number
Distance Calculation: Calculate distances between verses in lines

Installation

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

dependencies:
  mushaf_engine: ^1.0.0

Then run:

dart pub get

Basic Usage

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 automatically
  final data = MushafData.loadKingFahadMushafSync();
  final mushaf = KingFahadMushaf.loadFromJson(data);
  final engine = BaseMushafEngine(mushaf);

  // Navigate 15 lines from Sura 5, Verse 3 in upward direction
  final result = engine.navigate(NavigateParams(
    lines: 15,
    from: VersePosition(5, 3),
    direction: Direction.upwards,
    settings: NavigationSettings.builder().build(),
  ));

  print(result);
}

Output:

Target verse: Sura 5:5 Position: (1.0, 15) Lines: 5
Distance Moved: 15
Remaining Distance: 0
End of page: Lines distance: 0, Verse: Sura 5:5 Position: (1.0, 15) Lines: 5
End of sura: Lines distance: 300, Verse: Sura 5:120 Position: (1.0, 15) Lines: 1.1

Advanced Features

NavigationSettings provides a builder pattern to configure navigation behavior:

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

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

Output:

Target verse: Sura 2:58 Position: (0.8, 3) Lines: 2.8
Distance Moved: 98.8
Remaining Distance: 1.2
Overflow: Overflow lines: 0.7, Verse: Sura 2:59 Position: (0.7, 5) Lines: 1.9
End of page: Lines distance: -4, Verse: Sura 2:57 Position: (1.0, 15) Lines: 2.3
End of sura: Lines distance: 612.2, Verse: Sura 2:286 Position: (1.0, 15) Lines: 5.2

NavigationBounds controls how navigation behaves when reaching boundaries:

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

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

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

Output:

Target verse: Sura 107:5 Position: (1.0, 10) Lines: 0.6
Distance Moved: 1000
Remaining Distance: 0
End of page: Lines distance: 5.6, Verse: Sura 108:3 Position: (1.0, 15) Lines: 1
End of sura: Lines distance: 1, Verse: Sura 107:7 Position: (1.0, 11) Lines: 0.5

Key Concepts:

Iteration Limit: Controls how many complete cycles through the bounded range are allowed
- 0: No cycling - navigation stops at boundaries
- n: Allows n complete cycles through the range
Bounds: upperBound must be less than lowerBound (e.g., (1,1) < (114,6))
When reaching lowerBound with remaining iterations, navigation cycles back to upperBound

Ignoring Sura Headers

Control whether sura headers (bismillah and sura titles) are included in line calculations:

// Exclude sura headers from calculations
final withoutHeaders = NavigationSettings.builder()
  .setIgnoreSuraHeader(true)
  .build();

// Include sura headers in calculations (default)
final withHeaders = NavigationSettings.builder()
  .setIgnoreSuraHeader(false)
  .build();

// Calculate lines between verses
final linesWithHeaders = engine.calculateLines(
  start: VersePosition(2, 1),
  end: VersePosition(3, 1),
  direction: Direction.downwards,
  settings: withHeaders,
);

final linesWithoutHeaders = engine.calculateLines(
  start: VersePosition(2, 1),
  end: VersePosition(3, 1),
  direction: Direction.downwards,
  settings: withoutHeaders,
);

// Difference accounts for sura header lines
print('Lines with headers: $linesWithHeaders');
print('Lines without headers: $linesWithoutHeaders');
print('Difference: ${linesWithHeaders - linesWithoutHeaders} lines');

Output:

Lines with headers: 715.2
Lines without headers: 711.2
Difference: 4.0 lines

Note: Sura 9 (At-Tawbah) has no bismillah, only a title (1 line instead of 2).

Calculate Distance Between Verses

Calculate the number of lines between any two verses:

final lines = engine.calculateLines(
  start: VersePosition(2, 255),  // Ayat al-Kursi
  end: VersePosition(3, 200),    // End of Al-Imran
  direction: Direction.downwards,
  settings: NavigationSettings.builder().build(),
);

print('Distance: $lines lines');

Output:

Distance: 517.3 lines

Data Format

The Mushaf engine expects data in the following format:

class JsonVerse {
  final int sura;    // Sura number (1-114)
  final int ayah;    // Verse number within the sura
  final double lines;   // Number of lines this verse spans (can be fractional)
  final double y;       // Line number on the page (1-15)
  final double x;       // Horizontal position on the line (0.0-1.0)
}

// Mushaf data is a list of pages, each page is a list of verses
List<List<JsonVerse>> mushafData;

The library includes the King Fahad Mushaf data which you can load using the MushafData helper class:

// Synchronous loading
final data = MushafData.loadKingFahadMushafSync();
final mushaf = KingFahadMushaf.loadFromJson(data);

// Or async loading
final data = await MushafData.loadKingFahadMushaf();
final mushaf = KingFahadMushaf.loadFromJson(data);

API Reference

Core Classes

BaseMushafEngine

Main engine implementing the MushafEngine interface.

Methods:

navigate(NavigateParams params): Navigate by lines with comprehensive settings
calculateLines({...}): Calculate distance between verses
getVerse(int sura, int verse): Find a specific verse
getPage(int pageNumber): Get a page by number

NavigationSettings

Configuration for navigation behavior with builder pattern.

Builder Methods:

setIgnoreSuraHeader(bool): Control sura header inclusion
setBounds(NavigationBounds): Set complete bounds configuration
setIterationLimit(int): Set cycling iteration limit
setUpperBound(VersePosition): Set upper navigation bound
setLowerBound(VersePosition): Set lower navigation bound
build(): Create the settings instance

NavigationBounds

Defines boundaries and iteration limits for navigation.

Constructor:

NavigationBounds({
  required int iterationLimit,
  required VersePosition upperBound,
  required VersePosition lowerBound,
})

Static Methods:

defaultBounds(): Creates default bounds (no cycling, full Quran range)

Supporting Classes

Verse: Represents a single verse with metadata
Page: Represents a page in the Mushaf with its verses
Mushaf: Represents the complete Quran Mushaf
VersePosition: Identifies a verse by sura and verse number
QuranMetadata: Provides metadata about suras
VersesNavigator: Handles low-level navigation between verses
MushafData: Helper class to load bundled King Fahad Mushaf data
KingFahadMushaf: Loader for King Fahad Mushaf JSON format

Direction: Enum for navigation direction (downwards or upwards)
NavigationResult: Comprehensive result of a navigation operation
OverflowResult: Information about navigation that exceeds boundaries
LastVerseResult: Information about boundary verses encountered

Examples

final result = engine.navigate(NavigateParams(
  lines: 10,
  from: VersePosition(1, 1),
  direction: Direction.downwards,
  settings: NavigationSettings.builder().build(),
));

Output:

Target verse: Sura 1:7 Position: (1.0, 6) Lines: 1.3
Distance Moved: 8
Remaining Distance: 0
Overflow: Overflow lines: 1.5, Verse: Sura 2:1 Position: (0.5, 2) Lines: 1.5
End of page: Lines distance: 1.3, Verse: Sura 1:7 Position: (1.0, 6) Lines: 1.3
End of sura: Lines distance: -2, Verse: Sura 1:7 Position: (1.0, 6) Lines: 1.3

Example 2: Cycling Through a Range

final settings = NavigationSettings.builder()
  .setIterationLimit(2)
  .setUpperBound(VersePosition(67, 1))  // Sura Al-Mulk
  .setLowerBound(VersePosition(67, 30))
  .build();

final result = engine.navigate(NavigateParams(
  lines: 500,  // Will cycle through the range twice
  from: VersePosition(67, 1),
  direction: Direction.downwards,
  settings: settings,
));

Output:

Target verse: Sura 67:30 Position: (1.0, 5) Lines: 1
Distance Moved: 105
Remaining Distance: 0
End of page: Lines distance: 11, Verse: Sura 68:16 Position: (1.0, 15) Lines: 0.4
End of sura: Lines distance: -395, Verse: Sura 67:30 Position: (1.0, 5) Lines: 1

final settings = NavigationSettings.builder()
  .setIgnoreSuraHeader(true)
  .build();

final result = engine.navigate(NavigateParams(
  lines: 20,
  from: VersePosition(2, 1),
  direction: Direction.downwards,
  settings: settings,
));

Output:

Target verse: Sura 2:15 Position: (0.5, 14) Lines: 0.9
Distance Moved: 19.5
Remaining Distance: 0.5
Overflow: Overflow lines: 1, Verse: Sura 2:16 Position: (1.0, 15) Lines: 1.5
End of page: Lines distance: 1, Verse: Sura 2:16 Position: (1.0, 15) Lines: 1.5
End of sura: Lines distance: 691.5, Verse: Sura 2:286 Position: (1.0, 15) Lines: 5.2

License

MIT License

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.

mushaf_engine

Features

Installation

Basic Usage

Advanced Features

Navigation Settings

Cycling Navigation with Bounds

Ignoring Sura Headers

Calculate Distance Between Verses

Data Format

API Reference

Core Classes

BaseMushafEngine

NavigationSettings

NavigationBounds

Supporting Classes

Navigation Types

Examples

Example 1: Simple Navigation

Example 2: Cycling Through a Range

Example 3: Navigation Without Sura Headers

License

Libraries

mushaf_engine package