alpm_common/traits/
metadata_file.rs

1//! Traits for metadata files.
2
3#[cfg(doc)]
4use std::str::FromStr;
5use std::{
6    io::{Read, stdin},
7    path::Path,
8};
9
10use crate::FileFormatSchema;
11
12/// A trait for metadata files.
13///
14/// Metadata files are expected to adhere to a [`FileFormatSchema`] that is encoded in them
15/// (purposefully or not).
16/// This trait provides a set of functions to allow the easy creation of objects representing
17/// metadata files from a diverse set of inputs.
18/// Some functions allow the optional creation of the metadata file objects based a provided
19/// [`FileFormatSchema`].
20pub trait MetadataFile<T>
21where
22    T: FileFormatSchema,
23{
24    /// The Error type to use.
25    type Err;
26
27    /// Creates [`Self`] from file.
28    ///
29    /// # Note
30    ///
31    /// Implementations of this function are expected to automatically detect a [`FileFormatSchema`]
32    /// that the resulting [`Self`] is based on.
33    ///
34    /// The blanket implementation calls [`Self::from_file_with_schema`] with [`None`] as `schema`.
35    fn from_file(file: impl AsRef<Path>) -> Result<Self, Self::Err>
36    where
37        Self: Sized,
38    {
39        Self::from_file_with_schema(file, None)
40    }
41
42    /// Creates [`Self`] from `file`, optionally validated by a `schema`.
43    ///
44    /// If a [`FileFormatSchema`] is provided, [`Self`] must be validated using it.
45    fn from_file_with_schema(file: impl AsRef<Path>, schema: Option<T>) -> Result<Self, Self::Err>
46    where
47        Self: Sized;
48
49    /// Creates [`Self`] from [`stdin`].
50    ///
51    /// # Note
52    ///
53    /// Implementations of this function are expected to automatically detect a [`FileFormatSchema`]
54    /// that the resulting [`Self`] is based on.
55    ///
56    /// The blanket implementation calls [`Self::from_stdin_with_schema`] with [`None`] as `schema`.
57    fn from_stdin() -> Result<Self, Self::Err>
58    where
59        Self: Sized,
60    {
61        Self::from_stdin_with_schema(None)
62    }
63
64    /// Creates [`Self`] from [`stdin`], optionally validated by a `schema`.
65    ///
66    /// If a [`FileFormatSchema`] is provided, [`Self`] must be validated using it.
67    ///
68    /// The blanket implementation calls [`Self::from_reader_with_schema`] by passing in [`stdin`]
69    /// and the provided `schema`.
70    fn from_stdin_with_schema(schema: Option<T>) -> Result<Self, Self::Err>
71    where
72        Self: Sized,
73    {
74        Self::from_reader_with_schema(stdin(), schema)
75    }
76
77    /// Creates [`Self`] from a [`Read`] implementer.
78    ///
79    /// # Note
80    ///
81    /// Implementations of this function are expected to automatically detect a [`FileFormatSchema`]
82    /// that the resulting [`Self`] is based on.
83    ///
84    /// The blanket implementation calls [`Self::from_reader_with_schema`] with [`None`] as
85    /// `schema`.
86    fn from_reader(reader: impl Read) -> Result<Self, Self::Err>
87    where
88        Self: Sized,
89    {
90        Self::from_reader_with_schema(reader, None)
91    }
92
93    /// Creates [`Self`] from a [`Read`] implementer, optionally validated by a `schema`.
94    ///
95    /// If a [`FileFormatSchema`] is provided, [`Self`] must be validated using it.
96    fn from_reader_with_schema(reader: impl Read, schema: Option<T>) -> Result<Self, Self::Err>
97    where
98        Self: Sized;
99
100    /// Creates [`Self`] from a string slice, optionally validated by a `schema`.
101    ///
102    /// If a [`FileFormatSchema`] is provided, [`Self`] must be validated using it.
103    ///
104    /// # Note
105    ///
106    /// When also implementing [`FromStr`], it is advisable to redirect its implementation to call
107    /// [`Self::from_str_with_schema`] with [`None`] as `schema`.
108    fn from_str_with_schema(s: &str, schema: Option<T>) -> Result<Self, Self::Err>
109    where
110        Self: Sized;
111}
alpm_common/traits/metadata_file.rs

alpm_common/traits/
metadata_file.rs
