Passages AST ​

Overview ​

BibleKit utilizes a special Abstract Syntax Tree (AST) format to parse bible passages into a flexible structure. This allows for easier data extraction and the capability to perform various transformations.

AST is especially useful when you need to highlight a specific passage. By knowing the IDs of all bible verses used in a passage, we can fetch these verses from the API.

Let's illustrate this with an example passage: "Gen. 1:2,4-5". This passage consists of a book (Gen.), a chapter (1), a single verse (2), and a range of verses (4-5). Each component can be represented as a passage node (PNode) in our AST.

Passage Node (PNode) ​

The base passage node has a type, properties, and can optionally have children.

interface PNode {
  type: PNodeType;
  props: Record<string, unknown>;
  children?: PNode[];
}

Book Node (PBookNode) ​

The book node extends the base passage node and represents a specific book in the Bible. It contains properties such as the book's ID, abbreviation, and number.

interface PBookNode extends PNode {
  type: PNodeType.BOOK;
  props: {
    id: string;
    abbreviation: string;
    bookNumber: number;
  };
  children: PChapterNode[];
}

Chapter Node (PChapterNode) ​

The chapter node represents a specific chapter in the book. It contains properties such as the chapter's number.

interface PChapterNode extends PNode {
  type: PNodeType.CHAPTER;
  props: {
    number: number;
  };
  children: (PVerseNode | PVerseRangeNode)[];
}

Verse Node (PVerseNode) ​

The verse node represents a specific verse in the chapter. It contains properties such as the verse's number.

interface PVerseNode extends PNode {
  type: PNodeType.VERSE;
  props: {
    number: number;
  };
}

Verse Range Node (PVerseRangeNode) ​

The verse range node represents a range of verses in the chapter. It contains properties such as the starting and ending verse numbers.

interface PVerseRangeNode extends PNode {
  type: PNodeType.VERSE_RANGE;
  props: {
    fromNumber: number;
    toNumber: number;
  };
}

With this AST structure, you can create flexible and complex passage structures for efficient Bible text manipulation and transformation. This forms the core of BibleKit's powerful parsing capabilities.

How It Works ​

To better understand how the passage AST works, let's consider the passage "Gen. 1:2,4-5". This passage includes a book (Genesis), a chapter (Chapter 1), a single verse (Verse 2), and a range of verses (Verses 4 to 5). The structure of this passage in the form of a tree would look like this:

BOOK:GEN
   CHAPTER:1
     VERSE:2
     VERSE_RANGE:4-5

The JSON representation of this AST is as follows:

[
  {
    "type": "BOOK",
    "props": {
      "id": "GEN",
      "abbreviation": "Gen.",
      "bookNumber": 10
    },
    "children": [
      {
        "type": "CHAPTER",
        "props": {
          "number": 1
        },
        "children": [
          {
            "type": "VERSE",
            "props": {
              "number": 2
            }
          },
          {
            "type": "VERSE_RANGE",
            "props": {
              "fromNumber": 4,
              "toNumber": 5
            }
          }
        ]
      }
    ]
  }
]

Here, each object in the array represents a node in the passage AST. The "type" field denotes the type of the node (book, chapter, verse, verse range), the "props" field holds properties related to the node, and the "children" field contains an array of nodes that are hierarchically under the current node.

For instance, the BOOK node represents the Book of Genesis, the CHAPTER node represents Chapter 1 of the book, the VERSE node represents Verse 2 of the chapter, and the VERSE_RANGE node represents Verses 4 to 5 of the chapter.

This structured representation of the passage allows for flexible and complex data extraction and transformation in BibleKit.

How to Create a Passage AST ​

To generate the AST (Abstract Syntax Tree) for a bible passage, you can use the createPassageAST function from the BibleKit library. This function accepts a string argument representing a bible passage and returns the corresponding AST.

Here's how to use it:

import { createPassageAST } from '@deeepvision/bible-kit';

// specify a passage
let passage = 'Gen. 1:1-3,5; Ex. 3:6';

// create the AST
let ast = createPassageAST(passage);

// `ast` now contains the AST representation of the passage

In this example, ast is a data structure representing the hierarchical structure of the bible passage 'Gen. 1:1-3,5; Ex. 3:6'. This AST can be used for further data extraction, transformation or analysis of the bible passage.

Extracting Verse IDs from a Passage ​

The BibleKit library provides the extractVerseIdsFromPassage function for extracting verse IDs from a given bible passage. This function creates an AST from the provided passage, and then extracts verse IDs from this tree structure.

Here's a simple usage example:

import { extractVerseIdsFromPassage } from '@deeepvision/bible-kit';

// specify a bible ID and a passage
let bibleId = 'NIV';
let passage = 'Gen. 1:1-3,5; Ex. 3:6';

// extract verse IDs
let ids = extractVerseIdsFromPassage(bibleId, passage);

/** 
 * `ids` is now an array of verse IDs: 
 * [
 *   'NIV:GEN:1:1', 
 *   'NIV:GEN:1:2', 
 *   'NIV:GEN:1:3', 
 *   'NIV:GEN:1:5', 
 *   'NIV:EXO:3:6'
 * ]
 * */

In this example, the ids array now contains the IDs for each verse specified in the given passage. These IDs are in the format BibleId:BookId:Chapter:Verse, and can be used for various purposes such as retrieving specific verses from a bible database via a Bible API.