dart_scripture_refs

A pure-Dart library for parsing, comparing, and displaying Paratext/USX scripture references using the bbbcccvvv integer-string format.

Features

• Standardized Format: Uses the 9-digit bbbcccvvv format (e.g., 001001001 for Genesis 1:1).
• Reference Parsing: Convert human-readable strings like Gen 1.1-3; Exo 2.5 into structured ranges.
• Versification: Convert between English and "Original" versification systems.
• Book Names: Look up Paratext book IDs and names in English and Spanish.
• Zero Dependencies: Pure Dart implementation with no external runtime dependencies.

Usage

import 'package:dart_scripture_refs/dart_scripture_refs.dart';

Parsing references

Convert human-readable strings into RefRange objects. References can use . or : as chapter-verse separators, and ; to delimit multiple ranges.

final ranges = parseReferences('Gen 1.1-3; Exo 2.5');
// [RefRange(001001001, 001001003), RefRange(002002005, 002002005)]

Displaying references

Convert RefRange objects back to a human-readable string. Use refRangesToDisplay to get a single joined string, or refRangesToDisplayParts when you need to format each range individually.

RefRange.refRangesToDisplay(ranges, englishBookNames);
// 'Genesis 1.1-3; Exodus 2.5'

RefRange.refRangesToDisplayParts(ranges, englishBookNames);
// ['Genesis 1.1-3', 'Exodus 2.5']

Iterating verses and chapters

Use iterator() to step through every verse in a range, or chapterIterator() to step through chapters.

final range = RefRange('001001001', '001001003');
for (final verse in range.iterator()) {
  print(verse); // 001001001, 001001002, 001001003
}

final chapterRange = RefRange('001001', '001003');
for (final chapter in chapterRange.chapterIterator()) {
  print(chapter); // 001001, 001002, 001003
}

Navigating to the next verse or chapter

nextVerse and nextChapter handle book boundaries automatically, returning '' at the end of the canon.

RefRange.nextVerse('001001031');  // '001002001' (Gen 1:31 -> Gen 2:1)
RefRange.nextVerse('001050026');  // '002001001' (Gen 50:26 -> Exo 1:1)
RefRange.nextVerse('066022021');  // '' (end of Revelation)

RefRange.nextChapter('001050');   // '002001' (Gen 50 -> Exo 1)
RefRange.nextChapter('066022');   // '' (end of Revelation)

Collapsing verse lists into ranges

Turn a flat list of bbbcccvvv strings into consolidated RefRange objects by merging consecutive verses.

final verses = ['001001001', '001001002', '001001004'];
final ranges = RefRange.refsToRefRanges(verses);
// [RefRange(001001001, 001001002), RefRange(001001004, 001001004)]

Expanding ranges into verse lists

Get every individual verse covered by a set of ranges as a sorted list.

final allVerses = RefRange.getAllVersesInRefRanges(ranges);
// ['001001001', '001001002', '001001004']

Versification conversion

Convert between the English and Original versification systems. Psalms are a common case where chapter/verse numbers differ.

convertEnglishToOriginalVersification('019003001'); // '019003002' (Ps 3:1 -> Ps 3:2)

Book names

englishBookNames and spanishBookNames are plain List<String> indexed in canonical order (Genesis = index 0). paratextBookIds provides the corresponding Paratext 3-letter IDs.

// Iterate all books with their Paratext ID and display name
for (int i = 0; i < paratextBookIds.length; i++) {
  print('${paratextBookIds[i]}: ${englishBookNames[i]}');
  // GEN: Genesis, EXO: Exodus, ...
}

// Look up by language code
final bookNames = getBookNames('es'); // returns spanishBookNames

// Parse using non-English names
final esRanges = parseReferences('Génesis 1:1', bookNames: spanishBookNames);

License

This project is licensed under the MIT License - see the LICENSE file for details. Copyright (c) 2026 United Bible Societies (UBS).