cabrillo sink

Author: cammeresi

README.md

@@ -84,6 +84,12 @@ every single transformation an application might desire.  The user can,
 however, write additional normalizers to implement additional
 transformations not heretofore envisioned by the author.
 
+As a convenience tool, the crate also contains a [CabrilloSink] to output
+records as a contest log in [Cabrillo][cabrillo] format.  Reading Cabrillo
+format is not supported.
+
+[cabrillo]: https://wwrof.org/cabrillo/cabrillo-v3-header/
+
 ## Testing
 
 Testing is expected to be extreme.  Code coverage is expected to be in
@@ -96,11 +102,11 @@ in the entire crate is executed by at least one test.  This fact is
 verified by both `cargo llvm-cov` and codecov.io (badge at top).
 
 The report from `cargo llvm-cov` contains a few exceptions in its summary
-data only (5 out of over 3900 regions), but it does not positively
+data only (5 out of over 4300 regions), but it does not positively
 identify any expression in this crate that is not executed by a test.
 These anomalies may be small bits of code from the standard library
 that are inlined by the compiler and that are thus out of the control
-of this crate.
+of this crate.  See file NOTES.md for details about their locations.
 
 > I reviewed your flight plan.  Not one error in a million keystrokes.
 > Phenomenal.  [[Gattaca, 1997][gattaca]]

src/cabrillo/mod.rs

@@ -0,0 +1,185 @@
+//! Writing Cabrillo contest log format
+
+use crate::{Error, Record};
+use bytes::{BufMut, BytesMut};
+use futures::sink::Sink;
+use std::pin::Pin;
+use std::task::{Context, Poll};
+use tokio::io::AsyncWrite;
+use tokio_util::codec::{Encoder, FramedWrite};
+
+#[cfg(test)]
+mod test;
+
+enum Item {
+    Record(Record),
+    Eof,
+}
+
+struct CabrilloEncoder {
+    fields: Vec<String>,
+    started: bool,
+}
+
+impl CabrilloEncoder {
+    fn new(fields: Vec<String>) -> Self {
+        Self {
+            fields,
+            started: false,
+        }
+    }
+
+    fn encode_header(
+        &mut self, r: Record, dst: &mut BytesMut,
+    ) -> Result<(), Error> {
+        if self.started {
+            return Err(Error::DuplicateHeader);
+        }
+
+        self.started = true;
+        dst.put_slice(b"START-OF-LOG: 3.0\n");
+
+        for (name, value) in r.fields() {
+            let key = name.to_uppercase();
+            let val = value.to_cabrillo();
+
+            dst.put_slice(key.as_bytes());
+            dst.put_slice(b": ");
+            dst.put_slice(val.as_bytes());
+            dst.put_slice(b"\n");
+        }
+        Ok(())
+    }
+
+    fn encode_qso(&self, r: Record, dst: &mut BytesMut) -> Result<(), Error> {
+        dst.put_slice(b"QSO: ");
+
+        for (i, f) in self.fields.iter().enumerate() {
+            let d = r.get(f).ok_or_else(|| Error::MissingField {
+                field: f.clone(),
+                record: r.clone(),
+            })?;
+
+            if i > 0 {
+                dst.put_slice(b" ");
+            }
+            let v = d.to_cabrillo();
+            dst.put_slice(v.as_bytes());
+        }
+
+        dst.put_slice(b"\n");
+        Ok(())
+    }
+}
+
+impl Encoder<Item> for CabrilloEncoder {
+    type Error = Error;
+
+    fn encode(
+        &mut self, item: Item, dst: &mut BytesMut,
+    ) -> Result<(), Self::Error> {
+        match item {
+            Item::Record(r) => {
+                if r.is_header() {
+                    self.encode_header(r, dst)
+                } else if !self.started {
+                    Err(Error::MissingHeader)
+                } else {
+                    self.encode_qso(r, dst)
+                }
+            }
+            Item::Eof => {
+                if !self.started {
+                    return Err(Error::MissingHeader);
+                }
+                dst.put_slice(b"END-OF-LOG:\n");
+                Ok(())
+            }
+        }
+    }
+}
+
+/// Sink for writing Cabrillo format records
+pub struct CabrilloSink<W> {
+    inner: FramedWrite<W, CabrilloEncoder>,
+}
+
+impl<W> CabrilloSink<W>
+where
+    W: AsyncWrite,
+{
+    /// Create a new CabrilloSink that writes the specified fields from
+    /// each record in Cabrillo format.
+    ///
+    /// Header field names are output in uppercase.  All values are output
+    /// verbatim with no transformation, although the encoder does output
+    /// typed data according to the format.
+    ///
+    /// ```
+    /// use adif::{CabrilloSink, Record};
+    /// use futures::SinkExt;
+    ///
+    /// # #[tokio::main(flavor = "current_thread")]
+    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// let mut buf = Vec::new();
+    /// let fields = vec!["freq", "mode", "time_on", "call"];
+    /// let mut sink = CabrilloSink::new(&mut buf, fields);
+    ///
+    /// let mut header = Record::new_header();
+    /// header.insert("contest", "ARRL-SS-CW")?;
+    /// sink.send(header).await?;
+    ///
+    /// let mut qso = Record::new();
+    /// qso.insert("freq", "14000")?;
+    /// qso.insert("mode", "CW")?;
+    /// qso.insert("time_on", "CW")?;
+    /// qso.insert("call", "W1AW")?;
+    /// sink.send(qso).await?;
+    ///
+    /// sink.close().await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn new(w: W, fields: Vec<&str>) -> Self {
+        let fields = fields.into_iter().map(|s| s.to_string()).collect();
+        Self {
+            inner: FramedWrite::new(w, CabrilloEncoder::new(fields)),
+        }
+    }
+}
+
+impl<W> Sink<Record> for CabrilloSink<W>
+where
+    W: AsyncWrite + Unpin,
+{
+    type Error = Error;
+
+    fn poll_ready(
+        mut self: Pin<&mut Self>, cx: &mut Context<'_>,
+    ) -> Poll<Result<(), Error>> {
+        Pin::new(&mut self.inner)
+            .poll_ready(cx)
+            .map_err(Error::from)
+    }
+
+    fn start_send(mut self: Pin<&mut Self>, r: Record) -> Result<(), Error> {
+        Pin::new(&mut self.inner).start_send(Item::Record(r))
+    }
+
+    fn poll_flush(
+        mut self: Pin<&mut Self>, cx: &mut Context<'_>,
+    ) -> Poll<Result<(), Error>> {
+        Pin::new(&mut self.inner)
+            .poll_flush(cx)
+            .map_err(Error::from)
+    }
+
+    fn poll_close(
+        mut self: Pin<&mut Self>, cx: &mut Context<'_>,
+    ) -> Poll<Result<(), Error>> {
+        Pin::new(&mut self.inner).start_send(Item::Eof)?;
+        Pin::new(&mut self.inner)
+            .poll_close(cx)
+            .map_err(Error::from)
+    }
+}

src/cabrillo/test.rs

@@ -0,0 +1,102 @@
+use chrono::{NaiveDate, NaiveTime};
+use futures::SinkExt;
+
+use crate::{CabrilloSink, Error, Record};
+
+#[tokio::test]
+async fn basic() {
+    let mut buf = Vec::new();
+    let fields = vec!["freq", "mode", "qso_date", "time_on", "call"];
+    let mut sink = CabrilloSink::new(&mut buf, fields);
+
+    let mut header = Record::new_header();
+    header.insert("contest", "ARRL-SS-CW").unwrap();
+    header.insert("callsign", "W1AW").unwrap();
+    sink.send(header).await.unwrap();
+
+    let mut qso = Record::new();
+    qso.insert("freq", "14000").unwrap();
+    qso.insert("mode", "CW").unwrap();
+    qso.insert("qso_date", NaiveDate::from_ymd_opt(2020, 1, 1).unwrap())
+        .unwrap();
+    qso.insert("time_on", NaiveTime::from_hms_opt(12, 34, 0).unwrap())
+        .unwrap();
+    qso.insert("call", "AB9BH").unwrap();
+    sink.send(qso).await.unwrap();
+
+    sink.close().await.unwrap();
+
+    let output = String::from_utf8(buf).unwrap();
+    let expected = "\
+START-OF-LOG: 3.0
+CONTEST: ARRL-SS-CW
+CALLSIGN: W1AW
+QSO: 14000 CW 2020-01-01 1234 AB9BH
+END-OF-LOG:
+";
+    assert_eq!(output, expected);
+}
+
+#[tokio::test]
+async fn missing_header() {
+    let mut buf = Vec::new();
+    let fields = vec!["call"];
+    let mut sink = CabrilloSink::new(&mut buf, fields);
+
+    let mut qso = Record::new();
+    qso.insert("call", "W1AW").unwrap();
+    let result = sink.send(qso).await;
+
+    assert_eq!(result.unwrap_err(), Error::MissingHeader);
+}
+
+#[tokio::test]
+async fn missing_field() {
+    let mut buf = Vec::new();
+    let fields = vec!["call", "freq"];
+    let mut sink = CabrilloSink::new(&mut buf, fields);
+
+    let mut header = Record::new_header();
+    header.insert("contest", "TEST").unwrap();
+    sink.send(header).await.unwrap();
+
+    let mut qso = Record::new();
+    qso.insert("call", "W1AW").unwrap();
+    let qso_clone = qso.clone();
+    let result = sink.send(qso).await;
+
+    assert_eq!(
+        result.unwrap_err(),
+        Error::MissingField {
+            field: "freq".to_string(),
+            record: qso_clone
+        }
+    );
+}
+
+#[tokio::test]
+async fn duplicate_header() {
+    let mut buf = Vec::new();
+    let fields = vec!["call"];
+    let mut sink = CabrilloSink::new(&mut buf, fields);
+
+    let mut header1 = Record::new_header();
+    header1.insert("contest", "TEST1").unwrap();
+    sink.send(header1).await.unwrap();
+
+    let mut header2 = Record::new_header();
+    header2.insert("contest", "TEST2").unwrap();
+    let result = sink.send(header2).await;
+
+    assert_eq!(result.unwrap_err(), Error::DuplicateHeader);
+}
+
+#[tokio::test]
+async fn close_error() {
+    let mut buf = Vec::new();
+    let fields = vec!["call"];
+    let mut sink = CabrilloSink::new(&mut buf, fields);
+
+    let result = sink.close().await;
+    assert_eq!(result.unwrap_err(), Error::MissingHeader);
+}