alpm-common 0.2.1

Library providing common traits and functionalities for other ALPM crates
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

//! Traits for metadata files.

#[cfg(doc)]
use std::str::FromStr;
use std::{
    io::{Read, stdin},
    path::Path,
};

use crate::FileFormatSchema;

/// A trait for metadata files.
///
/// Metadata files are expected to adhere to a [`FileFormatSchema`] that is encoded in them
/// (purposefully or not).
/// This trait provides a set of functions to allow the easy creation of objects representing
/// metadata files from a diverse set of inputs.
/// Some functions allow the optional creation of the metadata file objects based a provided
/// [`FileFormatSchema`].
pub trait MetadataFile<T>
where
    T: FileFormatSchema,
{
    /// The Error type to use.
    type Err;

    /// Creates [`Self`] from file.
    ///
    /// # Note
    ///
    /// Implementations of this function are expected to automatically detect a [`FileFormatSchema`]
    /// that the resulting [`Self`] is based on.
    ///
    /// The blanket implementation calls [`Self::from_file_with_schema`] with [`None`] as `schema`.
    fn from_file(file: impl AsRef<Path>) -> Result<Self, Self::Err>
    where
        Self: Sized,
    {
        Self::from_file_with_schema(file, None)
    }

    /// Creates [`Self`] from `file`, optionally validated by a `schema`.
    ///
    /// If a [`FileFormatSchema`] is provided, [`Self`] must be validated using it.
    fn from_file_with_schema(file: impl AsRef<Path>, schema: Option<T>) -> Result<Self, Self::Err>
    where
        Self: Sized;

    /// Creates [`Self`] from [`stdin`].
    ///
    /// # Note
    ///
    /// Implementations of this function are expected to automatically detect a [`FileFormatSchema`]
    /// that the resulting [`Self`] is based on.
    ///
    /// The blanket implementation calls [`Self::from_stdin_with_schema`] with [`None`] as `schema`.
    fn from_stdin() -> Result<Self, Self::Err>
    where
        Self: Sized,
    {
        Self::from_stdin_with_schema(None)
    }

    /// Creates [`Self`] from [`stdin`], optionally validated by a `schema`.
    ///
    /// If a [`FileFormatSchema`] is provided, [`Self`] must be validated using it.
    ///
    /// The blanket implementation calls [`Self::from_reader_with_schema`] by passing in [`stdin`]
    /// and the provided `schema`.
    fn from_stdin_with_schema(schema: Option<T>) -> Result<Self, Self::Err>
    where
        Self: Sized,
    {
        Self::from_reader_with_schema(stdin(), schema)
    }

    /// Creates [`Self`] from a [`Read`] implementer.
    ///
    /// # Note
    ///
    /// Implementations of this function are expected to automatically detect a [`FileFormatSchema`]
    /// that the resulting [`Self`] is based on.
    ///
    /// The blanket implementation calls [`Self::from_reader_with_schema`] with [`None`] as
    /// `schema`.
    fn from_reader(reader: impl Read) -> Result<Self, Self::Err>
    where
        Self: Sized,
    {
        Self::from_reader_with_schema(reader, None)
    }

    /// Creates [`Self`] from a [`Read`] implementer, optionally validated by a `schema`.
    ///
    /// If a [`FileFormatSchema`] is provided, [`Self`] must be validated using it.
    fn from_reader_with_schema(reader: impl Read, schema: Option<T>) -> Result<Self, Self::Err>
    where
        Self: Sized;

    /// Creates [`Self`] from a string slice, optionally validated by a `schema`.
    ///
    /// If a [`FileFormatSchema`] is provided, [`Self`] must be validated using it.
    ///
    /// # Note
    ///
    /// When also implementing [`FromStr`], it is advisable to redirect its implementation to call
    /// [`Self::from_str_with_schema`] with [`None`] as `schema`.
    fn from_str_with_schema(s: &str, schema: Option<T>) -> Result<Self, Self::Err>
    where
        Self: Sized;
}