scripture-guide 1.0.85 → 1.0.88
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.
- package/README.md +240 -101
- package/dist/scriptures.cjs +11773 -1847
- package/dist/scriptures.mjs +11752 -1849
- 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
|
-
|
|
5
|
+
**[scripture.guide](https://scripture.guide)**
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
## Features
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
##
|
|
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
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
|
|
30
|
-
|
|
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
|
-
##
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
-
|
|
67
|
+
**Returns:**
|
|
68
|
+
```typescript
|
|
71
69
|
{
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
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
|
-
|
|
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
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
218
|
+
## Configuration
|
|
107
219
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
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
|
-
##
|
|
267
|
+
## License
|
|
268
|
+
|
|
269
|
+
ISC
|
|
131
270
|
|
|
132
|
-
|
|
271
|
+
## Author
|
|
133
272
|
|
|
134
|
-
|
|
273
|
+
KC Kern - [kckern](https://github.com/kckern)
|