ical/tree/

line.rs

//! # Content line
//!
//! One raw content line of a calendar: name, parameters, value, line ending.
//!
//! [`IcalLine`] is the syntactic unit a property occupies. It owns the line
//! tokeniser ([`take`](IcalLine::take), which splits one logical line off the
//! remaining input) and the head splitter separating the name from its
//! parameters.
//!
//! It stays generic: what the name means and how the value decodes belong to
//! the property lenses and the [`codec`](crate::tree::codec).
//!
//! Folding, stray blank lines and QUOTED-PRINTABLE soft breaks are resolved
//! on parse, so every layer above sees one logical line, and recorded on the
//! line's [`wire`](IcalLine::wire) shape, so serialization puts them back.
//!
//! A calendar therefore round-trips byte for byte however it was laid out.
//! The final line needs no trailing break.

use core::{fmt, str};

use alloc::{borrow::Cow, string::String, vec, vec::Vec};

use crate::tree::{
    codec::mode::Escaper,
    error::IcalParseError,
    leaf::{IcalLeaf, IcalValueLeaf},
    param::{lens::IcalParamLens, node::IcalParamNode},
    value::node::IcalValueNode,
    wire::IcalWire,
};

/// One raw content line: a name, parameters, a value and the line ending.
///
/// This is a *logical* line: [`take`](Self::take) unfolds RFC 5545 3.1
/// continuations and QUOTED-PRINTABLE soft breaks, so a line holds no internal
/// break, only its terminating [`eol`](Self::eol), and what it unfolded is
/// kept on [`wire`](Self::wire) to put the folds back on output.
///
/// It is also the syntactic unit for the `BEGIN` / `VERSION` / `END` envelope
/// lines, not only decoded properties.
#[derive(Clone, Debug)]
pub struct IcalLine<'a> {
    /// The property name leaf, with any group prefix.
    pub name: IcalLeaf<'a>,
    /// The parameters, in source order.
    pub params: Vec<IcalParamNode<'a>>,
    /// The value.
    pub value: IcalValueNode<'a>,
    /// The line ending (`\r\n` or `\n`).
    pub eol: IcalLeaf<'a>,
    /// How the line was laid out on the wire: its folds, the blank lines before
    /// it, its soft breaks. Empty for a built line, and dropped on output once
    /// an edit changes the line's length (see [`IcalWire`]).
    pub wire: IcalWire<'a>,
}

impl<'a> IcalLine<'a> {
    /// Build a property line with a raw text value and the default `\r\n`
    /// ending. Used to seed BEGIN/VERSION/END and to encode simple values.
    pub fn text(name: impl Into<Cow<'a, str>>, value: impl Into<Cow<'a, str>>) -> Self {
        Self {
            name: IcalLeaf(name.into()),
            params: Vec::new(),
            value: IcalValueNode::from_components(
                vec![vec![IcalValueLeaf::from(value.into())]],
                Escaper::Modern,
            ),
            eol: IcalLeaf(Cow::Borrowed("\r\n")),
            wire: IcalWire::default(),
        }
    }

    /// Tokenise the logical line at the start of `rest`, unfolding as it goes.
    ///
    /// Returns the line and the remaining input. RFC 5545 3.1 folds a long line
    /// by inserting a CRLF and a single leading space or tab; unfolding drops
    /// them. A line with no folds borrows the source; a folded one is rebuilt
    /// owned, its bytes no longer contiguous.
    pub fn take(rest: &'a [u8]) -> Result<(Self, &'a [u8]), IcalParseError> {
        // NOTE: Everything this tokeniser resolves is recorded here, so
        // serialization can put it back.
        let mut wire = IcalWire::default();

        // NOTE: skip blank lines: real-world exports sometimes emit them.
        let mut head = rest;
        let (first, eol, mut tail) = loop {
            if head.is_empty() {
                return Err(IcalParseError::MissingCrlf(lossy(rest)));
            }
            let (content, eol, next) = physical_line(head);
            if content.is_empty() {
                head = next;
                continue;
            }
            break (content, eol, next);
        };

        if head.len() < rest.len() {
            wire.skipped(0, ascii(&rest[..rest.len() - head.len()]));
        }

        // NOTE: A line that begins with folding whitespace but has no line to
        // continue (a dangling continuation, e.g. left after a dropped blank
        // line) would fold into the previous line on reparse; strip the leading
        // whitespace so it stays its own line, and record it so it still
        // round-trips.
        let indented = first;
        let first = strip_leading_wsp(first);

        if first.len() < indented.len() {
            wire.skipped(0, ascii(&indented[..indented.len() - first.len()]));
        }

        // NOTE: QUOTED-PRINTABLE soft line breaks: a line whose head declares
        // ENCODING=QUOTED-PRINTABLE and whose value ends with `=` continues on
        // the next physical line. Param-driven, so it applies to any version's
        // calendar that uses the encoding, not just 2.1.
        if first.ends_with(b"=") && head_is_quoted_printable(first) {
            let mut logical = Vec::from(&first[..first.len() - 1]);
            wire.soft(logical.len(), is_crlf(eol));

            let mut last_eol;
            loop {
                let (continuation, eol, next) = physical_line(tail);
                last_eol = eol;
                tail = next;
                match continuation.strip_suffix(b"=") {
                    Some(head) => {
                        logical.extend_from_slice(head);
                        if tail.is_empty() {
                            // NOTE: The last continuation ends with a
                            // soft-break marker and nothing follows: the `=` is
                            // on the wire, the break after it is the line's own
                            // ending.
                            wire.skipped(logical.len(), "=");
                            break;
                        }
                        wire.soft(logical.len(), is_crlf(eol));
                    }
                    None => {
                        logical.extend_from_slice(continuation);
                        break;
                    }
                }
            }

            let mut line = Self::parse(&logical, b"")?.into_static();
            line.eol = eol_leaf(last_eol);
            line.wire.prepend(wire.into_static());
            return Ok((line, tail));
        }

        if !starts_with_wsp(tail) {
            let mut line = Self::parse(first, eol)?;
            line.wire.prepend(wire);
            return Ok((line, tail));
        }

        let mut logical = Vec::from(first);
        let mut last_eol = eol;

        while starts_with_wsp(tail) {
            let (continuation, eol, next) = physical_line(&tail[1..]);
            wire.fold(logical.len(), is_crlf(last_eol), tail[0]);
            logical.extend_from_slice(continuation);
            last_eol = eol;
            tail = next;
        }

        let mut line = Self::parse(&logical, b"")?.into_static();
        line.eol = eol_leaf(last_eol);
        line.wire.prepend(wire.into_static());

        Ok((line, tail))
    }

    /// Split the first physical line off `rest` verbatim, content and ending.
    ///
    /// Returned with what follows. This is the recovering parser's step over a
    /// line [`take`](Self::take) refuses: the bytes are kept whole rather than
    /// structured, so they still round-trip.
    pub fn take_physical(rest: &'a [u8]) -> (&'a [u8], &'a [u8]) {
        let (content, eol, tail) = physical_line(rest);
        (&rest[..content.len() + eol.len()], tail)
    }

    /// Convert into an owned line whose every leaf is owned (`'static`).
    pub(crate) fn into_static(self) -> IcalLine<'static> {
        IcalLine {
            name: self.name.into_static(),
            params: self
                .params
                .into_iter()
                .map(IcalParamNode::into_static)
                .collect(),
            value: self.value.into_static(),
            eol: self.eol.into_static(),
            wire: self.wire.into_static(),
        }
    }

    /// The raw bytes of the line's first value, for simple single-value lines.
    pub fn raw_value(&self) -> &[u8] {
        self.value.first_value_bytes()
    }

    /// The raw first value as UTF-8 text, lossily; for the ASCII envelope
    /// values (`VERSION`) and diagnostics.
    pub fn raw_value_str(&self) -> Cow<'_, str> {
        String::from_utf8_lossy(self.value.first_value_bytes())
    }

    /// Serialize the whole line to bytes, exactly as parsed: its logical
    /// content, laid back out in the wire shape it arrived in.
    pub(crate) fn write_bytes(&self, out: &mut Vec<u8>) {
        if self.wire.is_empty() {
            self.write_logical(out);
        } else {
            let mut logical = Vec::new();
            self.write_logical(&mut logical);
            self.wire.write_bytes(&logical, out);
        }

        out.extend_from_slice(self.eol.get().as_bytes());
    }

    /// Serialize the logical line (its name, parameters and value), with no
    /// line ending and no wire shape. This is the byte string the wire offsets
    /// index.
    fn write_logical(&self, out: &mut Vec<u8>) {
        out.extend_from_slice(self.name.get().as_bytes());

        for param in &self.params {
            out.push(b';');
            param.write_bytes(out);
        }

        out.push(b':');
        self.value.write_bytes(out);
    }

    /// The first parameter of type `P`, decoded.
    pub fn param<P: IcalParamLens>(&self) -> Option<P::Target<'_>> {
        self.params
            .iter()
            .find(|param| param.name.get().eq_ignore_ascii_case(&P::KIND))
            .map(|param| P::decode(param))
    }

    /// The first parameter of type `P`, mutably (raw, for editing its leaves).
    pub fn param_mut<P: IcalParamLens>(&mut self) -> Option<&mut IcalParamNode<'a>> {
        self.params
            .iter_mut()
            .find(|param| param.name.get().eq_ignore_ascii_case(&P::KIND))
    }

    /// Split one logical line into a typed line at the colon, separating the
    /// name, its parameters and the value. The head (name and parameters) must
    /// be valid UTF-8, as every version's grammar guarantees; only the value
    /// may carry a foreign charset, so it is kept as raw bytes.
    fn parse<'b>(content: &'b [u8], eol: &'b [u8]) -> Result<IcalLine<'b>, IcalParseError> {
        let Some(colon) = value_colon(content) else {
            return Err(IcalParseError::MissingPropertyColon(lossy(content)));
        };

        let head = str::from_utf8(&content[..colon])
            .map_err(|_| IcalParseError::NonUtf8Header(lossy(&content[..colon])))?;
        let (name, params) = split_head(head);

        let mut value = &content[colon + 1..];
        let mut wire = IcalWire::default();

        // NOTE: A QUOTED-PRINTABLE value ending in `=` is a dangling soft-break
        // marker, however it got there (a soft-break join, a folded
        // continuation, or raw input): valid content would encode a literal `=`
        // as `=3D`. Left in, it would re-trigger soft-break joining on reparse
        // and swallow the next line, so the logical line drops it and the wire
        // shape keeps it. This never touches base64 padding, since
        // `ENCODING=BASE64` is not quoted-printable.
        if head_is_quoted_printable(content) {
            let full = value.len();
            while value.last() == Some(&b'=') {
                value = &value[..value.len() - 1];
            }
            if value.len() < full {
                let end = colon + 1 + value.len();
                wire.skipped(end, ascii(&content[end..colon + 1 + full]));
            }
        }

        wire.seal(colon + 1 + value.len());

        Ok(IcalLine {
            name: IcalLeaf::from(name),
            params,
            value: IcalValueNode::parse(value),
            eol: IcalLeaf::from(str::from_utf8(eol).unwrap_or("")),
            wire,
        })
    }
}

impl fmt::Display for IcalLine<'_> {
    /// The line as text, wire shape included, lossily for a non-UTF-8 value.
    /// `IcalLine::write_bytes` is the byte-faithful path.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if self.wire.is_empty() {
            f.write_str(self.name.get())?;

            for param in &self.params {
                write!(f, ";{param}")?;
            }

            return write!(f, ":{}{}", self.value, self.eol.get());
        }

        let mut bytes = Vec::new();
        self.write_bytes(&mut bytes);
        f.write_str(&String::from_utf8_lossy(&bytes))
    }
}

/// Split a head into its name and its `;`-separated parameters.
fn split_head(head: &str) -> (&str, Vec<IcalParamNode<'_>>) {
    let (name, mut rest) = match param_semicolon(head) {
        Some(semi) => (&head[..semi], &head[semi..]),
        None => return (head, Vec::new()),
    };

    let mut params = Vec::new();

    while let Some(after) = rest.strip_prefix(';') {
        let (param, tail) = match param_semicolon(after) {
            Some(semi) => (&after[..semi], &after[semi..]),
            None => (after, ""),
        };

        params.push(IcalParamNode::parse(param));
        rest = tail;
    }

    (name, params)
}

/// The index of the `:` separating a line's head from its value.
///
/// The first one outside a double-quoted parameter value, which RFC 5545 3.2
/// lets carry both a colon and a semicolon. A head with an unbalanced quote
/// would swallow the rest of the line, so with no colon outside quotes the
/// scan falls back to the first colon anywhere and the line still parses.
fn value_colon(content: &[u8]) -> Option<usize> {
    let mut quoted = false;

    for (i, &byte) in content.iter().enumerate() {
        match byte {
            b'"' => quoted = !quoted,
            b':' if !quoted => return Some(i),
            _ => {}
        }
    }

    memchr::memchr(b':', content)
}

/// The byte index of the first `;` of a head that sits outside a double-quoted
/// parameter value, the one separating one parameter from the next.
fn param_semicolon(head: &str) -> Option<usize> {
    let mut quoted = false;

    for (i, byte) in head.bytes().enumerate() {
        match byte {
            b'"' => quoted = !quoted,
            b';' if !quoted => return Some(i),
            _ => {}
        }
    }

    None
}

/// Split the first physical line off `rest`: its content (without the line
/// ending), its line ending, and the remaining input. A final line with no
/// trailing break is taken whole, with an empty ending.
fn physical_line(rest: &[u8]) -> (&[u8], &[u8], &[u8]) {
    let Some(lf) = memchr::memchr(b'\n', rest) else {
        return (rest, b"", b"");
    };

    let tail = &rest[lf + 1..];

    let (content, eol) = if lf > 0 && rest[lf - 1] == b'\r' {
        (&rest[..lf - 1], &rest[lf - 1..lf + 1])
    } else {
        (&rest[..lf], &rest[lf..lf + 1])
    };

    (content, eol, tail)
}

/// Whether `rest` begins with a folding whitespace (space or tab).
fn starts_with_wsp(rest: &[u8]) -> bool {
    matches!(rest.first(), Some(b' ' | b'\t'))
}

/// Strip any leading folding whitespace (space, tab) or stray line-break byte
/// (`\r`, `\n`) from a line's content, so its name never begins with a byte
/// that another layer (folding, blank-line skipping) would re-strip on reparse.
fn strip_leading_wsp(mut bytes: &[u8]) -> &[u8] {
    while matches!(bytes.first(), Some(b' ' | b'\t' | b'\r' | b'\n')) {
        bytes = &bytes[1..];
    }
    bytes
}

/// Whether a line's head (its name and parameters, before the `:`) declares the
/// `QUOTED-PRINTABLE` encoding, as an `ENCODING=` parameter or a bare token.
fn head_is_quoted_printable(line: &[u8]) -> bool {
    let head = match value_colon(line) {
        Some(colon) => &line[..colon],
        None => return false,
    };

    head.split(|&b| b == b';').any(|token| {
        token.eq_ignore_ascii_case(b"QUOTED-PRINTABLE")
            || token.eq_ignore_ascii_case(b"ENCODING=QUOTED-PRINTABLE")
    })
}

/// An owned line-ending leaf from raw bytes (always an ASCII `\r\n` / `\n`).
fn eol_leaf(bytes: &[u8]) -> IcalLeaf<'static> {
    IcalLeaf::from(String::from_utf8_lossy(bytes).into_owned())
}

/// Whether a line ending is a `\r\n` rather than a bare `\n`.
fn is_crlf(eol: &[u8]) -> bool {
    eol.starts_with(b"\r")
}

/// Bytes the tokeniser resolved away, as text. Every one of them is a line
/// break, a space, a tab or an `=`, so the conversion never fails; a lone `""`
/// on the impossible path keeps this total rather than panicking.
fn ascii(bytes: &[u8]) -> &str {
    str::from_utf8(bytes).unwrap_or("")
}

/// A lossy owned string of raw bytes, for error diagnostics.
fn lossy(bytes: &[u8]) -> String {
    String::from_utf8_lossy(bytes).into_owned()
}

#[cfg(test)]
mod tests {
    use alloc::string::ToString;

    use crate::tree::{line::IcalLine, value::node::IcalValueNode};

    #[test]
    fn takes_one_line_and_leaves_the_rest() {
        let (line, rest) = IcalLine::take(b"FN:John\r\nEND:VCALENDAR\r\n").unwrap();
        assert_eq!(line.name.get(), "FN");
        assert_eq!(line.to_string(), "FN:John\r\n");
        assert_eq!(rest, b"END:VCALENDAR\r\n");
    }

    #[test]
    fn splits_parameters_off_the_head_then_round_trips() {
        let (line, _) = IcalLine::take(b"TEL;TYPE=work,home:123\r\n").unwrap();
        assert_eq!(line.params.len(), 1);
        assert_eq!(line.to_string(), "TEL;TYPE=work,home:123\r\n");
    }

    #[test]
    fn keeps_a_quoted_parameter_value_whole() {
        // NOTE: RFC 5545 section 3.2 lets a quoted parameter value carry a
        // colon; section 3.2.1 uses one in its ALTREP example.
        let raw = "DESCRIPTION;ALTREP=\"cid:part1.0001@example.org\";LANGUAGE=en:Meeting notes\r\n";
        let (line, _) = IcalLine::take(raw.as_bytes()).unwrap();

        assert_eq!(line.name.get(), "DESCRIPTION");
        assert_eq!(line.params.len(), 2);
        assert_eq!(line.params[0].name.get(), "ALTREP");
        assert_eq!(
            line.params[0].values[0].get(),
            "\"cid:part1.0001@example.org\""
        );
        assert_eq!(line.params[1].name.get(), "LANGUAGE");
        assert_eq!(line.raw_value_str(), "Meeting notes");
        assert_eq!(line.to_string(), raw);
    }

    #[test]
    fn keeps_a_quoted_semicolon_out_of_the_parameter_split() {
        let raw = "ATTENDEE;DIR=\"ldap://host:389/cn=Ada;o=Example\":mailto:ada@example.com\r\n";
        let (line, _) = IcalLine::take(raw.as_bytes()).unwrap();

        assert_eq!(line.params.len(), 1);
        assert_eq!(line.params[0].name.get(), "DIR");
        assert_eq!(line.raw_value_str(), "mailto:ada@example.com");
        assert_eq!(line.to_string(), raw);
    }

    #[test]
    fn an_unbalanced_quote_still_parses() {
        // NOTE: quote tracking alone would swallow the rest of the line, so
        // with no colon outside quotes the scan falls back to the first one.
        let raw = "ATTENDEE;CN=\"Ada:mailto:ada@example.com\r\n";
        let (line, _) = IcalLine::take(raw.as_bytes()).unwrap();

        assert_eq!(line.name.get(), "ATTENDEE");
        assert_eq!(line.to_string(), raw);
    }

    #[test]
    fn accepts_a_bare_lf_ending() {
        let (line, _) = IcalLine::take(b"FN:John\n").unwrap();
        assert_eq!(line.to_string(), "FN:John\n");
    }

    #[test]
    fn unfolds_space_and_tab_continuations() {
        let (line, rest) =
            IcalLine::take(b"NOTE:foo\r\n bar\r\n\tbaz\r\nEND:VCALENDAR\r\n").unwrap();
        assert_eq!(line.name.get(), "NOTE");
        assert_eq!(line.raw_value_str(), "foobarbaz");
        assert_eq!(rest, b"END:VCALENDAR\r\n");
    }

    #[test]
    fn serializes_a_folded_line_back_folded() {
        let (line, _) = IcalLine::take(b"NOTE:foo\r\n bar\r\n").unwrap();
        assert_eq!(line.raw_value_str(), "foobar");
        assert_eq!(line.to_string(), "NOTE:foo\r\n bar\r\n");
    }

    #[test]
    fn keeps_the_folding_whitespace_and_the_break_it_arrived_with() {
        let (line, _) = IcalLine::take(b"NOTE:foo\n\tbar\r\n").unwrap();
        assert_eq!(line.to_string(), "NOTE:foo\n\tbar\r\n");
    }

    #[test]
    fn serializes_a_skipped_blank_line_back() {
        let (line, _) = IcalLine::take(b"\r\n\r\nFN:John\r\n").unwrap();
        assert_eq!(line.to_string(), "\r\n\r\nFN:John\r\n");
    }

    #[test]
    fn drops_the_fold_points_once_the_value_is_edited() {
        // NOTE: The old offsets index bytes that are no longer there, so the
        // edited line goes out unfolded rather than folded in the wrong places.
        let (mut line, _) = IcalLine::take(b"NOTE:foo\r\n bar\r\n").unwrap();
        line.value = IcalValueNode::parse(b"something else entirely");
        assert_eq!(line.to_string(), "NOTE:something else entirely\r\n");
    }

    #[test]
    fn keeps_the_fold_points_when_an_edit_keeps_the_length() {
        let (mut line, _) = IcalLine::take(b"NOTE:foo\r\n bar\r\n").unwrap();
        line.value = IcalValueNode::parse(b"BARFOO");
        assert_eq!(line.to_string(), "NOTE:BAR\r\n FOO\r\n");
    }

    #[test]
    fn keeps_whitespace_beyond_the_single_fold_indicator() {
        let (line, _) = IcalLine::take(b"NOTE:foo\r\n  bar\r\n").unwrap();
        assert_eq!(line.raw_value_str(), "foo bar");
    }

    #[test]
    fn skips_blank_lines_before_the_next_line() {
        let (line, rest) = IcalLine::take(b"\r\n\r\nFN:John\r\nEND:VCALENDAR\r\n").unwrap();
        assert_eq!(line.name.get(), "FN");
        assert_eq!(rest, b"END:VCALENDAR\r\n");
    }

    #[test]
    fn tolerates_a_missing_final_line_break() {
        let (line, rest) = IcalLine::take(b"END:VCALENDAR").unwrap();
        assert_eq!(line.name.get(), "END");
        assert_eq!(line.to_string(), "END:VCALENDAR");
        assert_eq!(rest, b"");
    }

    #[test]
    fn joins_a_quoted_printable_soft_broken_line() {
        // NOTE: Two soft breaks: the first continuation itself ends with `=`
        // (the Some arm), the second does not (the None arm).
        let (line, _) = IcalLine::take(
            b"NOTE;ENCODING=QUOTED-PRINTABLE:caf=\r\n=C3=\r\n=A9\r\nEND:VCALENDAR\r\n",
        )
        .unwrap();
        assert_eq!(line.name.get(), "NOTE");
        assert_eq!(line.raw_value_str(), "caf=C3=A9");
        assert_eq!(line.raw_value(), b"caf=C3=A9");
    }

    #[test]
    fn errors_when_there_is_no_content_line() {
        assert!(IcalLine::take(b"").is_err());
        assert!(IcalLine::take(b"\r\n\r\n").is_err());
    }

    #[test]
    fn rejects_a_non_utf8_head() {
        let mut raw = b"X-".to_vec();
        raw.push(0xff);
        raw.extend_from_slice(b":v\r\n");
        assert!(IcalLine::take(&raw).is_err());
    }

    #[test]
    fn finds_a_parameter_mutably() {
        use crate::tree::param::language::LANGUAGE;

        let (mut line, _) = IcalLine::take(b"SUMMARY;LANGUAGE=en:Lunch\r\n").unwrap();
        assert!(line.param_mut::<LANGUAGE>().is_some());
    }

    #[test]
    fn a_trailing_equals_without_a_colon_is_not_quoted_printable() {
        // NOTE: `abc=` ends with `=` but has no colon, so the QP soft-break
        // check bails and the line then fails for want of a value separator.
        assert!(IcalLine::take(b"abc=\r\n").is_err());
    }

    #[test]
    fn quoted_printable_join_stops_at_an_empty_tail() {
        // NOTE: The final continuation ends with `=` and nothing follows, so
        // the join loop exits via the empty-tail guard rather than a non-`=`
        // line.
        let (line, rest) = IcalLine::take(b"NOTE;ENCODING=QUOTED-PRINTABLE:a=\r\nb=\r\n").unwrap();
        assert_eq!(line.raw_value_str(), "ab");
        assert_eq!(rest, b"");
    }
}