bible-abbreviation

Easily obtain the universal identifiers and full names of the books of the Bible in a variety of formats and languages.

Table of Contents

• Installation
• Usage
  • Get universal book tag
  • Get title for a given book
  • Error handling
• Internationalization
• Notes
• Contribute
• License

⚙️ Installation

npm install bible-abbreviation

📑 Usage

const { Abbreviator } = require('bible-abbreviation');
const abbrv = new Abbreviator();

1️⃣ Get universal tag for a given abbreviation

The first feature of the Abbreviator is the getTag method, which provides a universal code for a Bible book based on an abbreviation you give it:

const abbrv = new Abbreviator();
const matthewTag = abbrv.getTag('Matthew');
console.log(matthewTag); // output : 'MT'

This method supports a very wide variety of abbreviations, for example MT will be returned for the following values: matthieu, mt, matt, mat, matthew. You can view all the supported abbreviations per book in the file canonAbbrv.json.

2️⃣ Generate a title for a given book

The second feature of this module is the getTitle method, which generates a title in a given language and format, for a book given as a parameter:

const abbrv = new Abbreviator();
const matthewTitle = abbrv.getTitle('Matt');
console.log(matthewTitle); // output : 'Matthew'

By default, the Abbreviator is set to English, but you can also directly instantiate the object with the language of your choice from among those available (see Internationalization section) by giving the constructor the identifier of the desired language.

// abbreviator in french
const abbrv = new Abbreviator('fr');
const matthewTitle = abbrv.getTitle('Matt');
console.log(matthewTitle); // output : 'Matthieu'

You can of course change the language at any time by using the setLang method on the instantiated object.

const abbrv = new Abbreviator(); // abbrv in english
abbrv.setLang('fr'); // abbrv is now in french

By default, the title format is set to short, but you can set the default format to long, short or tiny at any time according to your preference using the setSize method:

const abbrv = new Abbreviator();
abbrv.setSize('long'); // abbrv's title size are now set to 'long'
const matthewTitle = abbrv.getTitle('Matt');
console.log(matthewTitle) // output : Gospel according to Matthew

Here's the different available formats

• long — Detailed title (ex: Mt → Gospel according to Matthew)
• short — Short book title (ex: 2 Thess → 2 Thessalonians)
• tiny — Abbréviation standard (ex: Genesis → Gn)

You can also access a particular format without having to change the default value by providing the desired size as the second parameter of the getTitle function:

const abbrv = new Abbreviator();
abbrv.setSize('long'); // abbrv's title size are now set to 'long'

let matthewTitle = abbrv.getTitle('Matt', 'short'); // return a short title even if you set size to long because you explicitly asked for a short size here
console.log(matthewTitle) // output : "Matthew"

matthewTitle = abbrv.getTitle('Matthew'); // no explicit format here so the method return the title with the default size
console.log(matthewTitle) // output : Gospel according to Matthew

⚡ Error handling

For a better user experience, the Abbreviator class methods don't throw any exceptions. The getTag and getTitle methods will return null if the book provided as a parameter does not exist. For getTitle, if the given format is unknown, the default parameter previously defined (by the constructor or by you) will be used. In the same way, for setSize and setLang, if the respective parameters provided are not supported, the default parameters will be reset to their initial values, short and en_US respectively. Finally, to optimize loading of i18n data, if you try to set the language to the same value as the current one, the class will detect it and will not make any changes.

🌍 Internationalization

English and French are the only two languages supported at the moment. We'll be working on integrating other languages in the future, but if you'd like to see a language available on the module quickly, please open a PR on our Github.

❓ Notes

As the class is designed so that parameters can be modified at any time, it is theoretically unnecessary to instantiate multiple Abbreviator objects. As each instance of Abbreviator loads a JSON file in the corresponding language, it is strongly recommended not to instantiate multiple objects of the Abbreviator class for performance optimization reasons.

We're working on a new structure for the i18n internationalization folder to optimize data loading. This improvement is not a high priority, since the module currently supports only two languages, but the release of this optimization will be backward-compatible.

💻 Contribute

Want to improve the module? submit a pull-request on github or open an issue.

📜 License

Copyright © 2023 RyanHmd This project is MIT licensed.