Skip to content

Commit a33895f

Browse files
kckernkckern
committed
Revise and expand README with usage and API docs
The README has been rewritten to provide a clearer overview, feature list, installation instructions, and detailed API documentation for scripture-guide. It now includes quick start examples, supported reference formats, language and canon support tables, configuration details, and function aliases. The new structure improves usability for developers and clarifies how to use the library in multiple languages and canons.
1 parent 82fdd85 commit a33895f

File tree

1 file changed

+222
-101
lines changed

1 file changed

+222
-101
lines changed

‎README.md‎

Lines changed: 222 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,255 @@
1+
# Scripture Guide
12

3+
A multilingual scripture reference parser for looking up, generating, and detecting scripture references across multiple religious canons.
24

3-
# Scripture Reference Parser
5+
**[scripture.guide](https://scripture.guide)**
46

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
68

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"
915

10-
## Prerequisites
16+
## Installation
1117

12-
- This scripture reference parser executes in a JavaScript envrionment. (Both NodeJS and major browsers supported)
13-
14-
## Installing
15-
16-
Install the package:
1718
```bash
18-
npm i scripture-guide
19+
npm install scripture-guide
1920
```
20-
Import and use the package:
21-
```js
22-
import {lookupReference,generateReference} from 'scripture-guide';
2321

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';
2826

29-
const ref = generateReference([ 26137, 26138, 26139 ]);
30-
console.log(ref);
31-
// John 3:16-18
27+
// Parse a reference to verse IDs
28+
lookupReference('John 3:16');
29+
// { query: 'John 3:16', ref: 'John 3:16', verse_ids: [26137] }
3230

31+
// Generate a reference from verse IDs
32+
generateReference([26137, 26138, 26139]);
33+
// 'John 3:16-18'
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.'
3338
```
3439

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, language?, config?)
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');
51+
// { query: 'Genesis 1:1', ref: '창세기 1:1', verse_ids: [1] }
52+
53+
lookupReference('1 Nephi 3:7', 'en', { canon: 'lds' });
54+
// { query: '1 Nephi 3:7', ref: '1 Nephi 3:7', verse_ids: [23152] }
6255
```
6356

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+
| `language` | string | Language code (optional) |
62+
| `config.canon` | string | Canon: `'lds'` or `'coc'` |
6963

70-
```json
64+
**Returns:**
65+
```typescript
7166
{
72-
"query": "Ex 20.5,10",
73-
"ref": "Exodus 20:5, 10",
74-
"verse_ids": [ 2057, 2062 ]
67+
query: string; // Original input
68+
ref: string; // Normalized reference
69+
verse_ids: number[]; // Verse ID array
70+
error?: string; // Error message if failed
7571
}
7672
```
7773

78-
## Using Verse IDs
74+
### generateReference(verse_ids, language?, options?)
75+
76+
Convert verse IDs to a formatted reference string.
77+
78+
```javascript
79+
generateReference([1, 2, 3]);
80+
// 'Genesis 1:1-3'
81+
82+
generateReference([26137], 'de');
83+
// 'Johannes 3:16'
84+
85+
generateReference([1, 2, 3, 10, 11]);
86+
// 'Genesis 1:1-3, 10-11'
87+
```
88+
89+
**Parameters:**
90+
| Name | Type | Description |
91+
|------|------|-------------|
92+
| `verse_ids` | number[] | Array of verse IDs |
93+
| `language` | string | Output language code (optional) |
94+
| `options.canon` | string | Canon: `'lds'` or `'coc'` |
95+
96+
### detectReferences(content, callback?, options?)
97+
98+
Find scripture references in text and optionally transform them.
99+
100+
```javascript
101+
// Default: wrap in brackets
102+
detectReferences('See Matthew 5:3-12 and John 3:16.');
103+
// 'See [Matthew 5:3-12] and [John 3:16].'
104+
105+
// Custom callback
106+
detectReferences('Read John 3:16.', (ref, ids) => {
107+
return `<a href="/bible/${ids.join(',')}">${ref}</a>`;
108+
});
109+
110+
// Context-aware: detects "v. 16" from surrounding context
111+
detectReferences('In John 3, Jesus explains (v. 16) that God loved the world.');
112+
// Detects 'John 3:16'
113+
```
79114

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.
115+
**Parameters:**
116+
| Name | Type | Description |
117+
|------|------|-------------|
118+
| `content` | string | Text containing references |
119+
| `callback` | function | `(query, verseIds) => string` |
120+
| `options.language` | string | Language code |
121+
| `options.contextAware` | boolean | Enable context detection (default: true) |
122+
| `options.enableImpliedBooks` | boolean | Detect bare verse numbers (default: true) |
82123

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 |
124+
### setLanguage(language)
95125

96-
See also: Master Verse ID list
126+
Set the default language for all subsequent calls.
97127

128+
```javascript
129+
import { setLanguage, lookupReference } from 'scripture-guide';
130+
131+
setLanguage('ko');
132+
lookupReference('요한복음 3:16');
133+
// Works in Korean
134+
```
135+
136+
## Supported Reference Formats
137+
138+
| Format | Example |
139+
|--------|---------|
140+
| Simple verse | `Exodus 1:1` |
141+
| Chapter only | `Genesis 2` |
142+
| Verse range | `Exodus 20:1-10` |
143+
| Split verses | `Exodus 20:5,10` |
144+
| Split chapters | `Genesis 1,3` |
145+
| Chapter range | `Exodus 3-5` |
146+
| Multi-chapter range | `Exodus 1:5-4:3` |
147+
| Multi-book range | `Genesis 30—Exodus 2` |
148+
| Compound references | `Exodus 5:1; Leviticus 6:2` |
149+
| Abbreviations | `Mt 2:5`, `Mk 3`, `1 Jn 1:5` |
150+
| Entire book | `Genesis` |
151+
152+
## Language Support
153+
154+
| Code | Language | Example Reference |
155+
|------|----------|-------------------|
156+
| `en` | English | John 3:16 |
157+
| `ko` | Korean | 요한복음 3:16 |
158+
| `de` | German | Johannes 3:16 |
159+
| `fr` | French | Jean 3:16 |
160+
| `ru` | Russian | Иоанна 3:16 |
161+
| `jp` | Japanese | ヨハネによる福音書 3:16 |
162+
| `vn` | Vietnamese | Giăng 3:16 |
163+
| `tr` | Turkish | Yuhanna 3:16 |
164+
| `swe` | Swedish | Johannes 3:16 |
165+
| `tgl` | Tagalog | Juan 3:16 |
166+
| `slv` | Slovenian | Janez 3:16 |
167+
| `eo` | Esperanto | Johano 3:16 |
168+
169+
## Canons
170+
171+
| Canon | Description |
172+
|-------|-------------|
173+
| `bible` | Protestant Bible (66 books) |
174+
| `lds` | LDS Standard Works (Bible + Book of Mormon + D&C + Pearl of Great Price) |
175+
| `rlds` | RLDS/Community of Christ canon |
176+
| `hindu` | Hindu scriptures |
177+
| `buddhist` | Buddhist texts |
178+
| `islam` | Islamic texts |
179+
180+
## Verse IDs
181+
182+
Verse IDs are sequential integers starting from Genesis 1:1.
183+
184+
| Reference | Verse ID |
185+
|-----------|----------|
186+
| Genesis 1:1 | 1 |
187+
| Genesis 1:2 | 2 |
188+
| Genesis 50:26 | 1533 |
189+
| Exodus 1:1 | 1534 |
190+
| Malachi 4:6 | 23145 |
191+
| Matthew 1:1 | 23146 |
192+
| John 3:16 | 26137 |
193+
| Revelation 22:21 | 31102 |
194+
195+
Use verse IDs to query your scripture database:
98196

99-
### Example Database Usage:
100-
Assuming a `verse_id`–index database table named `scripture_verses` exists
101197
```sql
102-
SELECT * FROM `scripture_verses` WHERE verse_id IN (2057, 2062);
198+
SELECT * FROM verses WHERE verse_id IN (26137, 26138, 26139);
103199
```
104-
This query will enable the retrieval of the text associated with the input reference, mediated by verse IDs.
105200

106-
### Customizing Verse IDs
201+
## Configuration
107202

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-
}
203+
### Custom Canon Data
204+
205+
Canon data is stored in `data/canons/{canon}/{language}.yml`:
206+
207+
```yaml
208+
canon: bible
209+
language: en
210+
211+
books:
212+
genesis:
213+
name: Genesis
214+
pattern: "[Gg]enesis"
215+
alt: [Gen, Gn]
216+
exodus:
217+
name: Exodus
218+
pattern: "[Ee]xodus"
219+
alt: [Exod, Ex]
220+
```
221+
222+
### Structure Data
223+
224+
Verse counts per chapter are in `data/structure/{canon}.yml`:
225+
226+
```yaml
227+
genesis: [31, 25, 24, 26, 32, 22, 24, ...] # verses per chapter
228+
exodus: [22, 25, 22, 31, 23, 30, 25, ...]
229+
```
230+
231+
## Function Aliases
232+
233+
For convenience, functions have shorter aliases:
234+
235+
| Full Name | Aliases |
236+
|-----------|---------|
237+
| `lookupReference` | `lookup`, `parse`, `read`, `ref2VerseId` |
238+
| `generateReference` | `generate`, `gen`, `ref`, `verseId2Ref` |
239+
| `detectReferences` | `detect`, `detectRefs`, `linkRefs` |
240+
| `setLanguage` | `lang`, `setLang` |
241+
242+
## Build
243+
244+
```bash
245+
npm run build # Build dist files
246+
npm test # Run tests
127247
```
128-
Following this structure, the verse_ids corresponding to each book, chapter and verse may be modified according to the desired sequenital index.
129248

130-
## Authors
249+
## License
250+
251+
ISC
131252

132-
* **KC Kern** - *Initial work* - [kckern](https://github.com/kckern)
253+
## Author
133254

134-
```npm run build && node test.js```
255+
KC Kern - [kckern](https://github.com/kckern)

0 commit comments

Comments
 (0)