bible-io 1.1.0

A Rust library for working with Bible text data structures
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

//! Bible loading, validation, and search-index options.

use serde::{Deserialize, Serialize};

use crate::errors::ModelError;

/// Current version of the serialized Bible content contract.
pub const CURRENT_BIBLE_SCHEMA_VERSION: u32 = 1;

/// Stable phases reported while loading a Bible from external storage.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BibleLoadPhase {
    /// Reading bytes from storage.
    Reading,
    /// Decoding and validating the content model.
    Processing,
    /// The Bible is ready for use.
    Complete,
}

/// Snapshot delivered to a load-progress callback.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BibleLoadProgress {
    /// Current phase.
    pub phase: BibleLoadPhase,
    /// Overall completion fraction in the inclusive range `0.0..=1.0`.
    pub fraction: f32,
    /// Completion fraction within the current phase.
    pub phase_fraction: f32,
}

impl BibleLoadProgress {
    /// Construct a validated progress snapshot.
    pub fn new(
        phase: BibleLoadPhase,
        fraction: f32,
        phase_fraction: f32,
    ) -> Result<Self, ModelError> {
        if !fraction.is_finite() || !(0.0..=1.0).contains(&fraction) {
            return Err(ModelError::new(
                "fraction",
                "must be finite and between 0 and 1",
            ));
        }
        if !phase_fraction.is_finite() || !(0.0..=1.0).contains(&phase_fraction) {
            return Err(ModelError::new(
                "phase_fraction",
                "must be finite and between 0 and 1",
            ));
        }
        Ok(Self {
            phase,
            fraction,
            phase_fraction,
        })
    }
}

/// Strictness controls for decoded Bible content.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BibleDataValidationOptions {
    /// Require at least one book.
    pub require_books: bool,
    /// Require at least one chapter per book.
    pub require_chapters: bool,
    /// Require at least one verse per chapter.
    pub require_verses: bool,
    /// Require every verse text to contain a non-whitespace character.
    pub require_verse_text: bool,
}

impl BibleDataValidationOptions {
    /// Compatibility policy for intentionally skeletal data.
    pub const PERMISSIVE: Self = Self {
        require_books: false,
        require_chapters: false,
        require_verses: false,
        require_verse_text: false,
    };
}

impl Default for BibleDataValidationOptions {
    fn default() -> Self {
        Self {
            require_books: true,
            require_chapters: true,
            require_verses: true,
            require_verse_text: true,
        }
    }
}

/// Options shared by all Bible construction methods.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct BibleLoadOptions {
    /// Content presence requirements.
    pub validation: BibleDataValidationOptions,
    /// Search index construction policy.
    pub search_index_mode: crate::search::SearchIndexMode,
}