debian-packaging 0.18.0

Debian packaging primitives
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
118
119
120
121
122
123

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

/*! Defines types representing debian/changelog files.

See <https://www.debian.org/doc/debian-policy/ch-source.html#debian-changelog-debian-changelog>
for the specification.
*/

use {
    chrono::{DateTime, Local},
    std::{borrow::Cow, io::Write},
};

#[derive(Clone, Debug)]
pub struct ChangelogEntry<'a> {
    pub package: Cow<'a, str>,
    pub version: Cow<'a, str>,
    pub distributions: Vec<Cow<'a, str>>,
    pub urgency: Cow<'a, str>,
    pub details: Cow<'a, str>,
    pub maintainer_name: Cow<'a, str>,
    pub maintainer_email: Cow<'a, str>,
    pub date: DateTime<Local>,
}

impl<'a> ChangelogEntry<'a> {
    /// Serialize the changelog entry to a writer.
    ///
    /// This incurs multiple `.write()` calls. So a buffered writer is
    /// recommended if performance matters.
    pub fn write<W: Write>(&self, writer: &mut W) -> std::io::Result<()> {
        /*
        package (version) distribution(s); urgency=urgency
          [optional blank line(s), stripped]
          * change details
          more change details
          [blank line(s), included in output of dpkg-parsechangelog]
          * even more change details
          [optional blank line(s), stripped]
         -- maintainer name <email address>[two spaces]  date
        */
        writer.write_all(self.package.as_bytes())?;
        writer.write_all(b" (")?;
        writer.write_all(self.version.as_bytes())?;
        writer.write_all(b") ")?;
        writer.write_all(self.distributions.join(" ").as_bytes())?;
        writer.write_all(b"; urgency=")?;
        writer.write_all(self.urgency.as_bytes())?;
        writer.write_all(b"\n\n")?;
        writer.write_all(self.details.as_bytes())?;
        writer.write_all(b"\n")?;
        writer.write_all(b"-- ")?;
        writer.write_all(self.maintainer_name.as_bytes())?;
        writer.write_all(b" <")?;
        writer.write_all(self.maintainer_email.as_bytes())?;
        writer.write_all(b">  ")?;
        writer.write_all(self.date.to_rfc2822().as_bytes())?;
        writer.write_all(b"\n\n")?;

        Ok(())
    }
}

/// Represents a complete `debian/changelog` file.
///
/// Changelogs are an ordered series of `ChangelogEntry` items.
#[derive(Default)]
pub struct Changelog<'a> {
    entries: Vec<ChangelogEntry<'a>>,
}

impl<'a> Changelog<'a> {
    /// Add an entry to this changelog.
    pub fn add_entry<'b: 'a>(&mut self, entry: ChangelogEntry<'b>) {
        self.entries.push(entry)
    }

    /// Serialize the changelog to a writer.
    ///
    /// Use of a buffered writer is encouraged if performance is a concern.
    pub fn write<W: Write>(&self, writer: &mut W) -> std::io::Result<()> {
        for entry in &self.entries {
            entry.write(writer)?;
        }

        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use {super::*, crate::error::Result};

    #[test]
    fn test_write() -> Result<()> {
        let mut changelog = Changelog::default();
        changelog.add_entry(ChangelogEntry {
            package: "mypackage".into(),
            version: "0.1".into(),
            distributions: vec!["mydist".into()],
            urgency: "low".into(),
            details: "details".into(),
            maintainer_name: "maintainer".into(),
            maintainer_email: "me@example.com".into(),
            date: DateTime::from_naive_utc_and_offset(
                chrono::DateTime::from_timestamp(1420000000, 0)
                    .unwrap()
                    .naive_utc(),
                chrono::TimeZone::from_offset(&chrono::FixedOffset::west_opt(3600 * 7).unwrap()),
            ),
        });

        let mut buf = vec![];
        changelog.write(&mut buf)?;

        let s = String::from_utf8(buf).unwrap();
        assert_eq!(s, "mypackage (0.1) mydist; urgency=low\n\ndetails\n-- maintainer <me@example.com>  Tue, 30 Dec 2014 21:26:40 -0700\n\n");

        Ok(())
    }
}