Crate writings

Expand description

The Bahá’í Sacred Writings for use in Rust projects and APIs.

§Source

All of the Writings are downloaded directly from https://www.bahai.org/library. The downloaded HTML is included in the html folder.

§Structure

Each type of Writings has its own struct, e.g. HiddenWord, PrayerParagraph, and GleaningsParagraph, which are hopefully explanatory of the unit the struct represents. In this way, an excerpt from the Writings can be precisely referenced.

The ref_id in each struct represents the exact reference ID at which the struct points to at https://www.bahai.org/r/`ref_id`. For example, Persian Hidden Word #3 can be accessed directly at https://www.bahai.org/r/607855955. Hence, its struct will have ref_id == “607855955”. This is a String, not a u32 or other integer type, because www.bahai.org currently requires leading zeroes, and to ensure future compatibility, it is not assumed integers of a fixed length will always be used.

The text field of each struct is the exact plain text as extracted from the downloaded HTML.

Other fields of each struct have their own documentation, depending on the type.

§Usage

§Embed All

When ::all() is invoked on one of the structs implementing the EmbedAllTrait, the HTML for that Work is parsed into the relevant structs once (very fast) and stored in a LazyLock<T>.

§Example: Hidden Words

use writings::{HiddenWord, HiddenWordKind, EmbedAllTrait as _};

let hw = HiddenWord::all()
    .iter()
    .find(|hw| hw.kind == HiddenWordKind::Persian && hw.number == Some(37))
    .cloned()
    .unwrap();

assert_eq!(
    hw,
    HiddenWord {
        ref_id: "998408191".to_string(),
        kind: HiddenWordKind::Persian,
        number: Some(37),
        prelude: Some(concat!("In the first line of the Tablet it is recorded and written,",
            " and within the sanctuary of the tabernacle of God is hidden:").to_string()),
        invocation: Some("O My Servant!".to_string()),
        text: concat!("Abandon not for that which perisheth an everlasting dominion,",
            " and cast not away celestial sovereignty for a worldly desire. This is the river",
            " of everlasting life that hath flowed from the wellspring of the pen of the merciful;",
            " well is it with them that drink!").to_string(),
    }
);

§Example: Gleanings

use writings::{GleaningsParagraph, EmbedAllTrait as _};

let gleanings = GleaningsParagraph::all()
    .iter()
    .filter(|hw| hw.text.contains("all things visible and invisible"))
    .cloned()
    .collect::<Vec<_>>();

assert_eq!(gleanings.len(), 3);

let results = gleanings.iter().map(|g| (g.number, g.roman.as_str(), g.paragraph)).collect::<Vec<_>>();
assert_eq!(results, vec![
    (11, "XI", 3),
    (49, "XLIX", 1),
    (90, "XC", 2),
]);

assert!(gleanings[0].text.starts_with(concat!("No sooner had her voice reached that most exalted Spot",
    " than We made reply: “Render thanks unto thy Lord, O Carmel. The fire of thy separation from Me was",
    " fast consuming thee, when the ocean of My presence surged before thy face, cheering thine eyes and",
    " those of all creation, and filling with delight all things visible and invisible.")));

§Example: Prayers

use writings::{PrayerKind, PrayerParagraph, EmbedAllTrait as _};

let prayer = PrayerParagraph::all()
    .iter()
    .find(|p| {
        p.kind == PrayerKind::General
            && p.section
                .iter()
                .any(|s| s.contains("Western States")
            && p.paragraph == 2)
    })
    .cloned()
    .unwrap();

assert_eq!(
    &prayer.text,
    concat!(
        "O God! O God! This is a broken-winged bird and his flight is very slow—assist him so that he may",
        " fly toward the apex of prosperity and salvation, wing his way with the utmost joy and happiness",
        " throughout the illimitable space, raise his melody in Thy Supreme Name in all the regions,",
        " exhilarate the ears with this call, and brighten the eyes by beholding the signs of guidance."
    )
);

§Languages

Currently, only English is available in this crate. If reliable authoritative sources can be found for other languages, it is hoped they will be added. عربي (Arabic) and فارسی (Farsi / Persian) will be added if there is demand and someone versed in these languages can help ensure the accuracy of the implementation.

TODO: More docs…

License: MIT AND Bahá’í International Community License

Modules§

roman: Conversion between integers and roman numerals. “Borrowed” from roman crate.

Structs§

AuthorIter: An iterator over the variants of Author
BookParagraph: TODO: May be used for books that can fit into a single format.
Citation: A “footnote” or “endnote” embedded in a Text.
GleaningsParagraph: A single paragraph from Gleanings from the Writings of Bahá’u’lláh
GleaningsVisitor
HiddenWord: A single Hidden Word, or the “Prologue” or “Epilogue”, from The Hidden Words of Bahá’u’lláh
HiddenWordsVisitor
MeditationParagraph: A single paragraph from Prayers and Meditations by Bahá’u’lláh
MeditationsVisitor
PrayerParagraph: A single paragraph from a PrayerSource, the most well-known perhaps being Bahá’í Prayers: A Selection of Prayers Revealed by Bahá’u’lláh, the Báb, and ‘Abdu’l‑Bahá
PrayersVisitor
TabletParagraph: TODO: Represent a paragraph from a TabletSource.
WritingsTypeIter: An iterator over the variants of WritingsType

Enums§

Author: The three Central Figures of the Bahá’í Faith. TODO: Include ShoghiEffendi, The UniversalHouseOfJustice, and Institution() in this enum?
BookTitle
HiddenWordKind: Arabic or Persian
ParagraphStyle: Whether the struct text represents an invocation (“In the name of God, the Most Glorious!”), an instruction to the reader, or “normal” text.
PrayerKind: The “kind” or “category” of the prayer from Bahá’í Prayers. PrayerKind::Prologue has been added to include the “Blessed is the spot…” and “Intone, O My servant…” selections at the beginning of the book.
PrayerSource: A compilation of Bahá’í Prayers, the most well-known perhaps being PrayerSource::BahaiPrayers
TabletSource: TODO: A work representing additional revealed Tablets.
Writings: Allows enumeration of all Writings types in the crate. See also the discriminants of this enum for use in APIs, etc.: WritingsType
WritingsError: An error type specific for this crate.
WritingsType: Auto-generated discriminant enum variants

Traits§

EmbedAllTrait
WritingsTrait
WritingsVisitor

Type Aliases§

WritingsResult: Alias for Result with WritingsError as the Error type.

Crate writingsCopy item path