scripture-guide 1.0.85 → 1.0.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +240 -101
  2. package/dist/scriptures.cjs +11746 -1847
  3. package/dist/scriptures.mjs +11725 -1849
  4. package/package.json +20 -13
package/README.md CHANGED
@@ -1,134 +1,273 @@
1
+ # Scripture Guide
1
2
 
3
+ A multilingual scripture reference parser for looking up, generating, and detecting scripture references across multiple religious canons.
2
4
 
3
- # Scripture Reference Parser
5
+ **[scripture.guide](https://scripture.guide)**
4
6
 
5
- This universal scripture reference parser is designed to lookup any reference to a scriptural text and return the corresponding verse ids. These verse ids can then be used to query a database using a verse id index, such as those found on https://scriptures.nephi.org/
7
+ ## Features
6
8
 
7
- ## Scripture Reference Conventions
8
- Scripture references generally follow standard conventions for citing the Bible. Various style guides have different conventions for citing the bible, but they are all generally recgoniziable by the elements of `Book`, `Chapter`, and `Verse`. Multiple reference types exist for citing various combinations of book, verse, or chapter ranges, discreet passages, and non-sequential verses within a single chapter or book, or across multiple chapters and/or books.
9
+ - **Parse references** - Convert "John 3:16" to verse IDs
10
+ - **Generate references** - Convert verse IDs back to human-readable strings
11
+ - **Detect references** - Find and link scripture references in text
12
+ - **12 languages** - English, Korean, German, French, Russian, Vietnamese, Swedish, Tagalog, Japanese, Turkish, Slovenian, Esperanto
13
+ - **Multiple canons** - Bible, LDS, RLDS, Hindu, Buddhist, Islamic texts
14
+ - **Context-aware detection** - Recognizes implied references like "v. 16" and "vv. 17-18"
9
15
 
10
- ## Prerequisites
16
+ ## Installation
11
17
 
12
- - This scripture reference parser executes in a JavaScript envrionment. (Both NodeJS and major browsers supported)
13
-
14
- ## Installing
15
-
16
- Install the package:
17
18
  ```bash
18
- npm i scripture-guide
19
+ npm install scripture-guide
19
20
  ```
20
- Import and use the package:
21
- ```js
22
- import {lookupReference,generateReference} from 'scripture-guide';
23
21
 
24
- const verses = lookupReference('Jn 3:16');
25
- console.log(verses);
26
- // { query: 'Jn 3:16', ref: 'John 3:16', verse_ids: [ 26137 ] }
27
- // John 3:16 is the 26137th verse in the Bible
22
+ ## Quick Start
23
+
24
+ ```javascript
25
+ import { lookupReference, generateReference, detectReferences } from 'scripture-guide';
26
+
27
+ // Parse a reference to verse IDs
28
+ lookupReference('John 3:16');
29
+ // { query: 'John 3:16', ref: 'John 3:16', verse_ids: [26137] }
28
30
 
29
- const ref = generateReference([ 26137, 26138, 26139 ]);
30
- console.log(ref);
31
- // John 3:16-18
31
+ // Generate a reference from verse IDs
32
+ generateReference([26137, 26138, 26139]);
33
+ // 'John 3:16-18'
32
34
 
35
+ // Detect and link references in text
36
+ detectReferences('Read John 3:16 today.', (ref, ids) => `<a href="/v/${ids[0]}">${ref}</a>`);
37
+ // 'Read <a href="/v/26137">John 3:16</a> today.'
33
38
  ```
34
39
 
35
- ## INPUT—Supported Reference Types
36
- |**Reference Type**|**Example** |
37
- |--|--|
38
- |Simple reference | Exodus 1:1 |
39
- | Simple chapter | Genesis 2 |
40
- | Split chapters | Genesis 1,3 |
41
- | Chapter range | Exodus 3-5 |
42
- | Chapter range and split | Exodus 3-5,8 |
43
- | Verse range | Exodus 20:1-10 |
44
- | Verse range and split | Exodus 20:1-5,10 |
45
- | Verse Split | Exodus 20:5,10 |
46
- | Verse range spanning multiple chapters | Exodus 1:5-4:3 |
47
- | Chapter range ending in partial chapter | Exodus 3-4:10 |
48
- | Chapter range spanning multiple books | Genesis 30—Exodus 2 |
49
- | Chapter range spanning multiple books, ending in partial chapter | Genesis 30—Exodus 2:5 |
50
- | Chapter range spanning multiple books, starting in partial chapter | Genesis 30:10—Exodus 2 |
51
- | Chapter range spanning multiple books, starting and ending with partial chapters | Genesis 30:10 - Exodus 2:5 |
52
- | Compound reference in same book | Exodus 5:1;6:2;8:5 |
53
- | Compound reference in different books | Exodus 5:1; Leviticus 6:2; Numbers 8:5 |
54
- | Compound reference ranges in different books | Exodus 5:1-3; Leviticus 6:2-5; Numbers 8:5-6 |
55
- | Entire Book Range | Genesis - Numbers |
56
- | Abbreviation detection | Mt 2.5; Mk 3; Lk 4; Jn 5.2-6; 1 Jn1.5,7-8; 3 Jn1.1 |
57
-
58
- ### Example
59
- A scripture reference `string` is passed into the `scripture` object’s `lookupReference()` function like this:
60
- ```js
61
- let results = scripture.lookupReference('Ex 20.5,10');
40
+ ## API Reference
41
+
42
+ ### lookupReference(query, options?)
43
+
44
+ Parse a scripture reference string into verse IDs.
45
+
46
+ ```javascript
47
+ lookupReference('Mt 5:3-12');
48
+ // { query: 'Mt 5:3-12', ref: 'Matthew 5:3-12', verse_ids: [23239, 23240, ...] }
49
+
50
+ lookupReference('Genesis 1:1', 'ko'); // string options = language
51
+ // { query: 'Genesis 1:1', ref: '창세기 1:1', verse_ids: [1] }
52
+
53
+ lookupReference('1 Nephi 3:7', { language: 'en', canon: 'lds' });
54
+ // { query: '1 Nephi 3:7', ref: '1 Nephi 3:7', verse_ids: [23152] }
62
55
  ```
63
56
 
64
- ## OUTPUT—Verse IDs
65
- The function will return a `json` object containing the following:
66
- - `query`: the user-provided input string (*what was said*)
67
- - `ref`: the parsed, interpreted reference string (*what was meant*)
68
- - `verse_ids`: the resuluting array containing the verse ID integers corresponding to the input query
57
+ **Parameters:**
58
+ | Name | Type | Description |
59
+ |------|------|-------------|
60
+ | `query` | string | Scripture reference to parse |
61
+ | `options` | string \| object | If string, treated as language code |
62
+ | `options.language` | string | Language code |
63
+ | `options.canon` | string | Canon: `'lds'`, `'rlds'`, etc. |
64
+
65
+ > **Backward Compatibility:** The old 3-parameter signature `lookupReference(query, language, config)` is deprecated but still supported.
69
66
 
70
- ```json
67
+ **Returns:**
68
+ ```typescript
71
69
  {
72
- "query": "Ex 20.5,10",
73
- "ref": "Exodus 20:5, 10",
74
- "verse_ids": [ 2057, 2062 ]
70
+ query: string; // Original input
71
+ ref: string; // Normalized reference
72
+ verse_ids: number[]; // Verse ID array
73
+ error?: string; // Error message if failed
75
74
  }
76
75
  ```
77
76
 
78
- ## Using Verse IDs
77
+ ### generateReference(verse_ids, options?)
78
+
79
+ Convert verse IDs to a formatted reference string.
80
+
81
+ ```javascript
82
+ generateReference([1, 2, 3]);
83
+ // 'Genesis 1:1-3'
84
+
85
+ generateReference([26137], 'de'); // string options = language
86
+ // 'Johannes 3:16'
87
+
88
+ generateReference([1, 2, 3, 10, 11], { language: 'en', canon: 'lds' });
89
+ // 'Genesis 1:1-3, 10-11'
90
+ ```
79
91
 
80
- - Verse IDs are intended to be used to query a scripture database. (Database not included).
81
- - Verse IDs are calculated as a function of number of verses away from `Genesis 1:1`, inclusive, using the conventionally standard sequence of books, chapters, and verses.
92
+ **Parameters:**
93
+ | Name | Type | Description |
94
+ |------|------|-------------|
95
+ | `verse_ids` | number[] | Array of verse IDs |
96
+ | `options` | string \| object | If string, treated as language code |
97
+ | `options.language` | string | Language code |
98
+ | `options.canon` | string | Canon: `'lds'`, `'rlds'`, etc. |
82
99
 
83
- ### Example Verse IDs:
84
- |Verse|Verse ID|
85
- |--|--|
86
- |Genesis 1:1| 1 |
87
- |Genesis 1:2| 2 |
88
- |Genesis 1:10| 10 |
89
- |Genesis 1:31| 31 |
90
- |Genesis 2:1| 32 |
91
- |Genesis 50:26| 1533 |
92
- |Exodus 1:1| 1534 |
93
- |Exodus 1:2| 1535 |
94
- |Malachi 4:6| 23145 |
100
+ > **Backward Compatibility:** The old 3-parameter signature `generateReference(ids, language, options)` is deprecated but still supported.
95
101
 
96
- See also: Master Verse ID list
102
+ ### detectReferences(content, callback?, options?)
97
103
 
104
+ Find scripture references in text and optionally transform them.
105
+
106
+ ```javascript
107
+ // Default: wrap in brackets
108
+ detectReferences('See Matthew 5:3-12 and John 3:16.');
109
+ // 'See [Matthew 5:3-12] and [John 3:16].'
110
+
111
+ // Custom callback
112
+ detectReferences('Read John 3:16.', (ref, ids) => {
113
+ return `<a href="/bible/${ids.join(',')}">${ref}</a>`;
114
+ });
115
+
116
+ // Context-aware: detects "v. 16" from surrounding context
117
+ detectReferences('In John 3, Jesus explains (v. 16) that God loved the world.');
118
+ // Detects 'John 3:16'
119
+ ```
120
+
121
+ **Parameters:**
122
+ | Name | Type | Description |
123
+ |------|------|-------------|
124
+ | `content` | string | Text containing references |
125
+ | `callback` | function | `(query, verseIds) => string` |
126
+ | `options.language` | string | Language code |
127
+ | `options.contextAware` | boolean | Enable context detection (default: true) |
128
+ | `options.enableImpliedBooks` | boolean | Detect bare verse numbers (default: true) |
129
+
130
+ ### setLanguage(language)
131
+
132
+ Set the default language for all subsequent calls.
133
+
134
+ ```javascript
135
+ import { setLanguage, lookupReference } from 'scripture-guide';
136
+
137
+ setLanguage('ko');
138
+ lookupReference('요한복음 3:16');
139
+ // Works in Korean
140
+ ```
141
+
142
+ ### setCanon(canon)
143
+
144
+ Set the default canon for all subsequent calls.
145
+
146
+ ```javascript
147
+ import { setCanon, lookupReference } from 'scripture-guide';
148
+
149
+ setCanon('lds'); // LDS Standard Works (default)
150
+ setCanon('rlds'); // RLDS/Community of Christ
151
+ ```
152
+
153
+ ## Supported Reference Formats
154
+
155
+ | Format | Example |
156
+ |--------|---------|
157
+ | Simple verse | `Exodus 1:1` |
158
+ | Chapter only | `Genesis 2` |
159
+ | Verse range | `Exodus 20:1-10` |
160
+ | Split verses | `Exodus 20:5,10` |
161
+ | Split chapters | `Genesis 1,3` |
162
+ | Chapter range | `Exodus 3-5` |
163
+ | Multi-chapter range | `Exodus 1:5-4:3` |
164
+ | Multi-book range | `Genesis 30—Exodus 2` |
165
+ | Compound references | `Exodus 5:1; Leviticus 6:2` |
166
+ | Abbreviations | `Mt 2:5`, `Mk 3`, `1 Jn 1:5` |
167
+ | Entire book | `Genesis` |
168
+
169
+ ## Language Support
170
+
171
+ | Code | Language | Example Reference |
172
+ |------|----------|-------------------|
173
+ | `en` | English | John 3:16 |
174
+ | `ko` | Korean | 요한복음 3:16 |
175
+ | `de` | German | Johannes 3:16 |
176
+ | `fr` | French | Jean 3:16 |
177
+ | `ru` | Russian | Иоанна 3:16 |
178
+ | `jp` | Japanese | ヨハネによる福音書 3:16 |
179
+ | `vn` | Vietnamese | Giăng 3:16 |
180
+ | `tr` | Turkish | Yuhanna 3:16 |
181
+ | `swe` | Swedish | Johannes 3:16 |
182
+ | `tgl` | Tagalog | Juan 3:16 |
183
+ | `slv` | Slovenian | Janez 3:16 |
184
+ | `eo` | Esperanto | Johano 3:16 |
185
+
186
+ ## Canons
187
+
188
+ | Canon | Description |
189
+ |-------|-------------|
190
+ | `bible` | Protestant Bible (66 books) |
191
+ | `lds` | LDS Standard Works (Bible + Book of Mormon + D&C + Pearl of Great Price) |
192
+ | `rlds` | RLDS/Community of Christ canon |
193
+ | `hindu` | Hindu scriptures |
194
+ | `buddhist` | Buddhist texts |
195
+ | `islam` | Islamic texts |
196
+
197
+ ## Verse IDs
198
+
199
+ Verse IDs are sequential integers starting from Genesis 1:1.
200
+
201
+ | Reference | Verse ID |
202
+ |-----------|----------|
203
+ | Genesis 1:1 | 1 |
204
+ | Genesis 1:2 | 2 |
205
+ | Genesis 50:26 | 1533 |
206
+ | Exodus 1:1 | 1534 |
207
+ | Malachi 4:6 | 23145 |
208
+ | Matthew 1:1 | 23146 |
209
+ | John 3:16 | 26137 |
210
+ | Revelation 22:21 | 31102 |
211
+
212
+ Use verse IDs to query your scripture database:
98
213
 
99
- ### Example Database Usage:
100
- Assuming a `verse_id`–index database table named `scripture_verses` exists
101
214
  ```sql
102
- SELECT * FROM `scripture_verses` WHERE verse_id IN (2057, 2062);
215
+ SELECT * FROM verses WHERE verse_id IN (26137, 26138, 26139);
103
216
  ```
104
- This query will enable the retrieval of the text associated with the input reference, mediated by verse IDs.
105
217
 
106
- ### Customizing Verse IDs
218
+ ## Configuration
107
219
 
108
- - The `data/scriptdata.json` file contains the sequential index from which verse_ids are calculated.
109
- - If needed, this file may be edited to correspond to a difference database index
110
- - The data structure is:
111
- ```json
112
- {
113
- "Book 1 Name":
114
- [
115
- "verse count (int) of chapter 1",
116
- "verse count (int) of chapter 2",
117
- "verse count (int) of chapter 3",
118
- "verse count (int) of chapter 4"
119
- ],
120
- "Book 2 Name":
121
- [
122
- "verse count (int) of chapter 1",
123
- "verse count (int) of chapter 2",
124
- "verse count (int) of chapter 3"
125
- ],
126
- }
220
+ ### Custom Canon Data
221
+
222
+ Canon data is stored in `data/canons/{canon}/{language}.yml`:
223
+
224
+ ```yaml
225
+ canon: bible
226
+ language: en
227
+
228
+ books:
229
+ genesis:
230
+ name: Genesis
231
+ pattern: "[Gg]enesis"
232
+ alt: [Gen, Gn]
233
+ exodus:
234
+ name: Exodus
235
+ pattern: "[Ee]xodus"
236
+ alt: [Exod, Ex]
237
+ ```
238
+
239
+ ### Structure Data
240
+
241
+ Verse counts per chapter are in `data/structure/{canon}.yml`:
242
+
243
+ ```yaml
244
+ genesis: [31, 25, 24, 26, 32, 22, 24, ...] # verses per chapter
245
+ exodus: [22, 25, 22, 31, 23, 30, 25, ...]
246
+ ```
247
+
248
+ ## Function Aliases
249
+
250
+ For convenience, functions have shorter aliases:
251
+
252
+ | Full Name | Aliases |
253
+ |-----------|---------|
254
+ | `lookupReference` | `lookup`, `parse`, `read`, `ref2VerseId` |
255
+ | `generateReference` | `generate`, `gen`, `ref`, `verseId2Ref` |
256
+ | `detectReferences` | `detect`, `detectRefs`, `linkRefs` |
257
+ | `setLanguage` | `lang`, `setLang` |
258
+ | `setCanon` | `canon` |
259
+
260
+ ## Build
261
+
262
+ ```bash
263
+ npm run build # Build dist files
264
+ npm run test:jest # Run tests
127
265
  ```
128
- Following this structure, the verse_ids corresponding to each book, chapter and verse may be modified according to the desired sequenital index.
129
266
 
130
- ## Authors
267
+ ## License
268
+
269
+ ISC
131
270
 
132
- * **KC Kern** - *Initial work* - [kckern](https://github.com/kckern)
271
+ ## Author
133
272
 
134
- ```npm run build && node test.js```
273
+ KC Kern - [kckern](https://github.com/kckern)