aqc-text-engine-core 0.3.0

Reusable text file requirement, merge, and reconcile helpers for AQC file engines.
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
105
106
107
108
109
110
111
112
113
114
115
116
117

//! Text byte-stream requirement model.

#![allow(
    clippy::module_name_repetitions,
    reason = "Public text-engine values use the TextFile prefix."
)]

use core::any::Any;
use core::cmp::Ordering;
use core::fmt;

use aqc_file_engine_core::{
    ConflictEntry, EngineRequirement, FileItemRequirement, ItemAssertionInput, ItemRequirements,
    RequiredItemResolution, ResolvedItemRequirements, ResolvedRequirement, ScalarAssertion,
    ScalarValue,
};

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
/// Expected byte contents for a whole text file or contained item.
pub struct TextFileContents(Vec<u8>);

#[derive(Debug, Clone, PartialEq, Eq)]
/// Validation errors for text requirement values.
pub enum TextFileValueError {
    /// A required text value was empty.
    Empty { field: &'static str },
}

#[derive(Debug, Clone, Default)]
/// Requirements for a generic text byte stream.
pub struct TextFileRequirements {
    /// Optional exact file contents assertion.
    pub exact_contents: Option<ScalarAssertion<TextFileContents>>,
    /// Byte sequences that must appear when exact file contents are not required.
    pub contents: ItemRequirements<TextFileContents>,
}

#[derive(Debug, Clone, Default)]
/// Resolved requirements for a generic text byte stream.
pub struct ResolvedTextFileRequirements {
    /// Resolved exact file contents assertion.
    pub exact_contents: Option<
        ResolvedRequirement<ScalarAssertion<TextFileContents>, ScalarAssertion<TextFileContents>>,
    >,
    /// Resolved contained byte assertions.
    pub contents: ResolvedItemRequirements<TextFileContents>,
}

impl EngineRequirement for TextFileRequirements {
    fn engine_id(&self) -> &'static str {
        crate::ENGINE_ID
    }

    fn as_any(&self) -> &dyn Any {
        self
    }
}

impl TextFileContents {
    /// Build non-empty text file contents.
    ///
    /// # Errors
    ///
    /// Returns [`TextFileValueError::Empty`] when `value` is empty.
    pub fn new(value: impl Into<Vec<u8>>) -> Result<Self, TextFileValueError> {
        let value = value.into();
        if value.is_empty() {
            return Err(TextFileValueError::Empty { field: "contents" });
        }
        Ok(Self(value))
    }

    #[must_use]
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }
}

impl fmt::Display for TextFileValueError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty { field } => write!(f, "{field} must not be empty"),
        }
    }
}

impl fmt::Display for TextFileContents {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("contents")
    }
}

impl ScalarValue for TextFileContents {
    fn render(&self) -> String {
        format!("{} bytes", self.0.len())
    }

    fn compare_for_order(&self, _other: &Self) -> Option<Ordering> {
        None
    }
}

impl FileItemRequirement for TextFileContents {
    type Identity = Self;

    fn merge_identity(&self) -> Self::Identity {
        self.clone()
    }

    fn compose_item(
        key: &str,
        items: Vec<ItemAssertionInput<Self>>,
        conflicts: &mut Vec<ConflictEntry>,
    ) -> Option<RequiredItemResolution<Self>> {
        aqc_file_engine_core::compose_item_by(key, items, Clone::clone, conflicts)
    }
}