vparser 1.2.1

// Copyright 2023-2026 Hugo Osvaldo Barrera
//
// SPDX-License-Identifier: ISC

//! This library implements a non-validating, flexible parser for iCalendar and vCard data.
//!
//! See [`Parser`] as the main entry point to this library.
#![no_std]
#![deny(clippy::pedantic)]
// Clippy recommends rewriting boolean expressions into a form which is slightly more complex.
#![allow(clippy::nonminimal_bool)]

extern crate alloc;

use core::iter::FusedIterator;

use alloc::{
    borrow::{Cow, ToOwned},
    string::ToString,
};

/// A valid content line.
///
/// Continuation lines may be folded; wrapped with continuation lines separated by a CRLF
/// immediately followed by a single linear white-space character (i.e., SPACE or HTAB).
#[derive(Debug, PartialEq, Clone)]
pub struct ContentLine<'input> {
    // TODO: use indeces instead; they're half the size and slightly simpler.
    /// The entire raw line, unaltered.
    raw: &'input str,
    /// Everything before the first colon or semicolon.
    name: &'input str,
    /// Everything before the first colon and after the first semicolon.
    params: &'input str,
    /// Everything after the first unquoted colon.
    value: &'input str,
}

impl<'input> ContentLine<'input> {
    /// Return the raw line without any unfolding.
    #[must_use]
    pub fn raw(&self) -> &'input str {
        self.raw
    }

    /// Return this line's name, with continuation lines unfolded.
    #[must_use]
    pub fn name(&self) -> Cow<'input, str> {
        unfold_lines(self.name)
    }

    /// Return this line's parameter(s), with continuation lines unfolded.
    #[must_use]
    pub fn params(&self) -> Cow<'input, str> {
        unfold_lines(self.params)
    }

    /// Return this line's value, with continuation lines unfolded.
    #[must_use]
    pub fn value(&self) -> Cow<'input, str> {
        unfold_lines(self.value)
    }

    /// Return the entire line unfolded.
    ///
    /// Note that the line may exceed the maximum length, making it technically invalid. This is
    /// however, suitable for comparing equality between to lines.
    #[must_use]
    pub fn unfolded(&self) -> Cow<'input, str> {
        unfold_lines(self.raw)
    }

    /// Return this content line with normalised folds
    ///
    /// The returned line shall be semantically equivalent to the input line. It will be folded
    /// making each logical line as long as possible (e.g.: no more than 75 octets, excluding the
    /// line jump). Output always uses CRLF line endings.
    #[must_use]
    // INVARIANT: content lines only have valid continuation lines.
    #[allow(clippy::missing_panics_doc)]
    pub fn normalise_folds(&self) -> Cow<'input, str> {
        let mut result = Cow::Borrowed(self.raw);
        // Index where current portion begins.
        let mut cur = 0;
        // Not strictly where the line started; this is also shifted to compensate for unfolds.
        let mut line_start = 0;

        let mut chars = self.raw.char_indices().peekable();
        while let Some((i, c)) = chars.next() {
            let skip_bytes = if c == '\r' && matches!(chars.peek(), Some((_, '\n'))) {
                chars.next(); // Advance the peeked LF.
                3
            } else if c == '\n' {
                2
            } else if (i - line_start) + c.len_utf8() >= 75 {
                let portion = &self.raw[cur..i];
                match result {
                    Cow::Borrowed(_) => {
                        result = Cow::Owned(portion.to_string() + "\r\n " + &c.to_string());
                    }
                    Cow::Owned(ref mut s) => {
                        s.push_str(portion);
                        s.push_str("\r\n ");
                        s.push(c);
                    }
                }
                cur = i + c.len_utf8();
                line_start = i - 1; // -1 to account for the inserted space.
                continue;
            } else {
                continue;
            };

            assert!(
                matches!(chars.next(), Some((_, ' ' | '\t'))),
                "continuation line must start with a space or tab",
            );

            let next = chars.peek().map_or(1, |(_, c)| c.len_utf8());
            if i - line_start + next >= 75 {
                // In this case we don't need to mutate anything; the whole line and ending
                // stay the same.

                // Note that the space already counts towards the following line.
                line_start = i + skip_bytes - 1;
            } else {
                let portion = &self.raw[cur..i];
                match result {
                    Cow::Borrowed(_) => {
                        result = Cow::Owned(portion.to_owned());
                    }
                    Cow::Owned(ref mut s) => {
                        s.push_str(portion);
                    }
                }
                // Shift to avoid counting line ending + space.
                line_start += skip_bytes;
                cur = i + skip_bytes;
            }
        }

        if let Cow::Owned(ref mut s) = result {
            let portion = &self.raw[cur..];
            s.push_str(portion);
        }

        result
    }
}

/// A flexible parser for icalendar/vcard.
///
/// This parser is designed to gracefully handle bogus data. The semantics of names, parameters,
/// and values are not validated. For example, a "date" may be an arbitrary string. Users of this
/// library should validate any data with the usual considerations for handling input data.
///
/// This parser itself is zero-copy. Accessors methods return unfolded names, values and
/// parameters. These accessors return a [`Cow`], and will allocate in case of folded lines.
///
/// It should be used via its [`Iterator`] implementation which iterates over [`ContentLine`]
/// instances.
///
/// # Quirks
///
/// - A trailing empty line is lost. The Icalenadr spec mandates trailing CRLF at the end of each
///   line, but the last line is missing a CRLF, there's no way for a consumer to determine this.
///
/// # See also
///
/// - [`Parser::next`]
pub struct Parser<'data> {
    data: &'data str,
    pos: usize,
}

impl<'data> Parser<'data> {
    /// Create a new parser with the given input data.
    ///
    /// The input data MAY have unfolded continuation lines.
    #[must_use]
    pub fn new(data: &'data str) -> Parser<'data> {
        Parser { data, pos: 0 }
    }

    /// Returns the unparsed portion of the input data.
    ///
    /// Does not affect advance the position of this iterator.
    #[must_use]
    pub fn remainder(&self) -> &str {
        &self.data[self.pos..]
    }
}

impl<'data> Iterator for Parser<'data> {
    type Item = ContentLine<'data>;

    /// Returns the next content line from the input data.
    ///
    /// This method is no-copy; a [`ContentLine`] contains only pointers to the original input
    /// data.
    ///
    /// Returns `None` after the last line has been returned. Returns `None` if called after the
    /// iterator has been exhausted.
    #[allow(clippy::too_many_lines)]
    fn next(&mut self) -> Option<ContentLine<'data>> {
        let bytes = self.data.as_bytes();
        let len = bytes.len();
        let start = self.pos;

        if start >= len {
            return None;
        }

        let mut pos = start;
        let mut semicolon = None;

        // Find semicolon or colon (name end).
        while pos < len {
            let b = bytes[pos];
            pos += 1;
            if b == b';' {
                semicolon = Some(pos - 1);
                break;
            }
            if b == b':' {
                // Found colon without semicolon. Parse value and line end.
                return Some(self.parse_value(start, pos - 1, None));
            }
            if b == b'\r' {
                // Only treat as line ending if followed by \n.
                if pos < len && bytes[pos] == b'\n' {
                    pos += 1;
                    if pos < len && (bytes[pos] == b' ' || bytes[pos] == b'\t') {
                        continue;
                    }
                    self.pos = pos;
                    return Some(ContentLine {
                        raw: &self.data[start..pos - 2],
                        name: &self.data[start..pos - 2],
                        params: &self.data[start..start],
                        value: &self.data[start..start],
                    });
                }
                // Bare \r is not a line ending. Continue scanning.
            }
            if b == b'\n' {
                // Check for continuation
                if pos < len && (bytes[pos] == b' ' || bytes[pos] == b'\t') {
                    continue;
                }
                self.pos = pos;
                return Some(ContentLine {
                    raw: &self.data[start..pos - 1],
                    name: &self.data[start..pos - 1],
                    params: &self.data[start..start],
                    value: &self.data[start..start],
                });
            }
        }

        if semicolon.is_none() {
            // Reached EOF.
            self.pos = len;
            return Some(ContentLine {
                raw: &self.data[start..],
                name: &self.data[start..],
                params: &self.data[start..start],
                value: &self.data[start..start],
            });
        }

        // Found semicolon, find colon (params end).
        let semicolon_idx = semicolon.unwrap();

        while pos < len {
            let b = bytes[pos];
            pos += 1;

            if b == b'"' {
                // Skip quoted content.
                while pos < len {
                    if bytes[pos] == b'"' {
                        pos += 1;
                        break;
                    }
                    pos += 1;
                }
                continue;
            }

            if b == b':' {
                return Some(self.parse_value(start, pos - 1, Some(semicolon_idx)));
            }

            if b == b'\r' {
                // Only treat as line ending if followed by \n.
                if pos < len && bytes[pos] == b'\n' {
                    pos += 1;
                    if pos < len && (bytes[pos] == b' ' || bytes[pos] == b'\t') {
                        continue;
                    }
                    self.pos = pos;
                    return Some(ContentLine {
                        raw: &self.data[start..pos - 2],
                        name: &self.data[start..semicolon_idx],
                        params: &self.data[semicolon_idx + 1..pos - 2],
                        value: &self.data[semicolon_idx..semicolon_idx],
                    });
                }
                // Bare \r is not a line ending, continue scanning.
            }

            if b == b'\n' {
                if pos < len && (bytes[pos] == b' ' || bytes[pos] == b'\t') {
                    continue;
                }
                self.pos = pos;
                return Some(ContentLine {
                    raw: &self.data[start..pos - 1],
                    name: &self.data[start..semicolon_idx],
                    params: &self.data[semicolon_idx + 1..pos - 1],
                    value: &self.data[semicolon_idx..semicolon_idx],
                });
            }
        }

        // Reached EOF.

        self.pos = len;
        if let Some(semicolon_idx) = semicolon {
            Some(ContentLine {
                raw: &self.data[start..],
                name: &self.data[start..semicolon_idx],
                params: &self.data[semicolon_idx + 1..],
                value: &self.data[semicolon_idx..semicolon_idx],
            })
        } else {
            Some(ContentLine {
                raw: &self.data[start..],
                name: &self.data[start..],
                params: &self.data[start..start],
                value: &self.data[start..start],
            })
        }
    }
}

impl<'data> Parser<'data> {
    /// Parse the value portion of a content line after the colon.
    fn parse_value(
        &mut self,
        start: usize,
        colon: usize,
        semicolon: Option<usize>,
    ) -> ContentLine<'data> {
        let bytes = self.data.as_bytes();
        let len = bytes.len();
        let mut pos = colon + 1;

        while pos < len {
            let b = bytes[pos];
            pos += 1;

            if b == b'\r' {
                // Only treat as line ending if followed by \n.
                if pos < len && bytes[pos] == b'\n' {
                    pos += 1;
                    if pos < len && (bytes[pos] == b' ' || bytes[pos] == b'\t') {
                        continue;
                    }
                    self.pos = pos;
                    return self.make_line(start, colon, semicolon, pos - 2);
                }
                // Bare \r is not a line ending, continue scanning.
            }

            if b == b'\n' {
                if pos < len && (bytes[pos] == b' ' || bytes[pos] == b'\t') {
                    continue;
                }
                self.pos = pos;
                return self.make_line(start, colon, semicolon, pos - 1);
            }
        }

        // Reached EOF.
        self.pos = len;
        self.make_line(start, colon, semicolon, len)
    }

    fn make_line(
        &self,
        start: usize,
        colon: usize,
        semicolon: Option<usize>,
        raw_end: usize,
    ) -> ContentLine<'data> {
        match semicolon {
            Some(semicolon_idx) => ContentLine {
                raw: &self.data[start..raw_end],
                name: &self.data[start..semicolon_idx],
                params: &self.data[semicolon_idx + 1..colon],
                value: &self.data[colon + 1..raw_end],
            },
            None => ContentLine {
                raw: &self.data[start..raw_end],
                name: &self.data[start..colon],
                params: &self.data[colon..colon],
                value: &self.data[colon + 1..raw_end],
            },
        }
    }
}

impl FusedIterator for Parser<'_> {}

/// Unfold multiple continuation lines into a single line.
///
/// # Panics
///
/// If the input string has multiple non-continuation lines.
fn unfold_lines(lines: &str) -> Cow<'_, str> {
    let bytes = lines.as_bytes();
    let len = bytes.len();
    let mut result = Cow::Borrowed(lines);
    let mut cur = 0;
    let mut pos = 0;

    while pos < len {
        let b = bytes[pos];
        pos += 1;

        if b == b'\r' {
            // Only treat as line ending if followed by \n.
            if pos < len && bytes[pos] == b'\n' {
                pos += 1;
                if pos < len && (bytes[pos] == b' ' || bytes[pos] == b'\t') {
                    pos += 1;
                    let i = pos - 3; // Position of \r.
                    let portion = &lines[cur..i];
                    match result {
                        Cow::Borrowed(_) => {
                            result = Cow::Owned(portion.to_owned());
                        }
                        Cow::Owned(ref mut s) => {
                            s.push_str(portion);
                        }
                    }
                    cur = pos;
                } else {
                    panic!("continuation line is not a continuation line");
                }
            }
        } else if b == b'\n' {
            if pos < len && (bytes[pos] == b' ' || bytes[pos] == b'\t') {
                pos += 1;
                let i = pos - 2; // Position of the \n
                let portion = &lines[cur..i];
                match result {
                    Cow::Borrowed(_) => {
                        result = Cow::Owned(portion.to_owned());
                    }
                    Cow::Owned(ref mut s) => {
                        s.push_str(portion);
                    }
                }
                cur = pos;
            } else {
                panic!("continuation line is not a continuation line");
            }
        }
    }

    if let Cow::Owned(ref mut s) = result {
        let portion = &lines[cur..];
        s.push_str(portion);
    }

    result
}

/// Parser and iterator for parameters in content lines.
///
/// # Example
///
/// ```rust
/// # use vparser::{ContentLine, Parser};
/// use vparser::ParamIter;
/// # let raw = "DTEND;TZID=America/Argentina/Buenos_Aires:20241104T140000";
/// # let mut parser = Parser::new(raw);
/// # let content_line = parser.next().unwrap();
/// // …
/// let params = content_line.params();
/// let params = ParamIter::new(&params);
/// for param in params {
///     println!("Name: {}", param.name());
///     println!("Value: {}", param.value());
/// }
/// ```
pub struct ParamIter<'a> {
    input: &'a str,
    pos: usize,
}

impl<'a> Iterator for ParamIter<'a> {
    type Item = Param<'a>;

    fn next(&mut self) -> Option<Self::Item> {
        if self.pos >= self.input.len() {
            return None;
        }

        let bytes = self.input.as_bytes();
        let mut equals = None;
        let mut end_pos = None;
        let mut in_quotes = false;

        for (i, b) in bytes.iter().enumerate().skip(self.pos) {
            match b {
                b'"' => in_quotes = !in_quotes,
                b'=' if equals.is_none() && !in_quotes => equals = Some(i),
                b';' if !in_quotes => {
                    end_pos = Some(i);
                    break;
                }
                _ => {}
            }
        }

        let start = self.pos;
        let end = end_pos.unwrap_or(bytes.len());
        self.pos = if let Some(e) = end_pos {
            e + 1
        } else {
            bytes.len()
        };

        let equals = equals?;
        Some(Param {
            name: &self.input[start..equals],
            value: &self.input[equals + 1..end],
        })
    }
}

impl FusedIterator for ParamIter<'_> {}

/// Individual parameter.
pub struct Param<'a> {
    name: &'a str,
    value: &'a str,
}

impl<'a> Param<'a> {
    /// Name of this parameter — the portion before the equal sign.
    #[must_use]
    pub fn name(&self) -> &'a str {
        self.name
    }

    /// Name of this parameter — the portion after the equal sign.
    ///
    /// Quoted values shall include the surrounding quotes in the returned string.
    #[must_use]
    pub fn value(&self) -> &'a str {
        self.value
    }
}

impl<'a> ParamIter<'a> {
    /// Create a new parameter iterator from the provided input string.
    #[must_use]
    pub fn new(input: &'a str) -> Self {
        Self { input, pos: 0 }
    }
}

#[cfg(test)]
#[allow(clippy::too_many_lines)]
mod test {
    use crate::{unfold_lines, ContentLine, ParamIter, Parser};
    use alloc::borrow::Cow;

    #[test]
    fn test_complete_example() {
        let data = [
            "BEGIN:VCALENDAR",
            "VERSION:2.0",
            "PRODID:nl.whynothugo.todoman",
            "BEGIN:VTODO",
            "DTSTAMP:20231126T095923Z",
            "DUE;TZID=Asia/Shanghai:20231128T090000",
            "SUMMARY:dummy todo for parser tests",
            "UID:565f48cb5b424815a2ba5e56555e2832@destiny.whynothugo.nl",
            "END:VTODO",
            "END:VCALENDAR",
            // Note: this calendar is not entirely semantically valid;
            // it is missing the timezone which is referred to in DUE.
        ]
        .join("\r\n");

        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "BEGIN:VCALENDAR",
                name: "BEGIN",
                params: "",
                value: "VCALENDAR"
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "VERSION:2.0",
                name: "VERSION",
                params: "",
                value: "2.0",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "PRODID:nl.whynothugo.todoman",
                name: "PRODID",
                params: "",
                value: "nl.whynothugo.todoman",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "BEGIN:VTODO",
                name: "BEGIN",
                params: "",
                value: "VTODO",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTAMP:20231126T095923Z",
                name: "DTSTAMP",
                params: "",
                value: "20231126T095923Z",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DUE;TZID=Asia/Shanghai:20231128T090000",
                name: "DUE",
                params: "TZID=Asia/Shanghai",
                value: "20231128T090000",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "SUMMARY:dummy todo for parser tests",
                name: "SUMMARY",
                params: "",
                value: "dummy todo for parser tests",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "UID:565f48cb5b424815a2ba5e56555e2832@destiny.whynothugo.nl",
                name: "UID",
                params: "",
                value: "565f48cb5b424815a2ba5e56555e2832@destiny.whynothugo.nl",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "END:VTODO",
                name: "END",
                params: "",
                value: "VTODO",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "END:VCALENDAR",
                name: "END",
                params: "",
                value: "VCALENDAR",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_empty_data() {
        let data = "";
        let mut parser = Parser::new(data);
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_empty_lines() {
        // A line followed by CRLF is a different code-path than a line followed by EOF.
        let data = "\r\n";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(
            line,
            ContentLine {
                raw: "",
                name: "",
                params: "",
                value: "",
            }
        );
        assert_eq!(line.raw(), "");
        assert_eq!(line.name(), "");
        assert_eq!(line.params(), "");
        assert_eq!(line.value(), "");
        // FIXME: trailing empty lines are swallowed.
        // assert_eq!(
        //     parser.next(),
        //     Some(ContentLine {
        //         raw: "",
        //         name: "",
        //         params: "",
        //         value: "",
        //     })
        // );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_line_with_params() {
        // A line with ending in CRLF is a different code-path than a line in EOF.
        let data = [
            "DTSTART;TZID=America/New_York:19970902T090000",
            "DTSTART;TZID=America/New_York:19970902T090000",
        ]
        .join("\r\n");
        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART;TZID=America/New_York:19970902T090000",
                name: "DTSTART",
                params: "TZID=America/New_York",
                value: "19970902T090000",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART;TZID=America/New_York:19970902T090000",
                name: "DTSTART",
                params: "TZID=America/New_York",
                value: "19970902T090000",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_line_with_dquote() {
        // A line with ending in CRLF is a different code-path than a line in EOF.
        let data = [
            "SUMMARY:This has \"some quotes\"",
            "DTSTART;TZID=\"local;VALUE=DATE-TIME\":20150304T184500",
        ]
        .join("\r\n");
        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "SUMMARY:This has \"some quotes\"",
                name: "SUMMARY",
                params: "",
                value: "This has \"some quotes\"",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART;TZID=\"local;VALUE=DATE-TIME\":20150304T184500",
                name: "DTSTART",
                params: "TZID=\"local;VALUE=DATE-TIME\"",
                value: "20150304T184500",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_continuation_line() {
        // A line with ending in CRLF is a different code-path than a line in EOF.
        let data = [
            "X-JMAP-LOCATION;VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";",
            " X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c:Name of place",
            "X-JMAP-LOCATION;VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";",
            " X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c:Name of place",
        ]
        .join("\r\n");
        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: &[
                    "X-JMAP-LOCATION;VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";",
                    " X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c:Name of place",
                ]
                .join("\r\n"),
                name: "X-JMAP-LOCATION",
                params: "VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";\r\n X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c",
                value: "Name of place",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: &[
                    "X-JMAP-LOCATION;VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";",
                    " X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c:Name of place",
                ]
                .join("\r\n"),
                name: "X-JMAP-LOCATION",
                params: "VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";\r\n X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c",
                value: "Name of place",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_invalid_lone_name() {
        let data = "BEGIN";
        let mut parser = Parser::new(data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "BEGIN",
                name: "BEGIN",
                params: "",
                value: "",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_invalid_name_with_params() {
        let data = "DTSTART;TZID=America/New_York";
        let mut parser = Parser::new(data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART;TZID=America/New_York",
                name: "DTSTART",
                params: "TZID=America/New_York",
                value: "",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_invalid_name_with_trailing_semicolon() {
        let data = "DTSTART;";
        let mut parser = Parser::new(data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART;",
                name: "DTSTART",
                params: "",
                value: "",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_invalid_name_with_trailing_colon() {
        let data = "DTSTART:";
        let mut parser = Parser::new(data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART:",
                name: "DTSTART",
                params: "",
                value: "",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_remainder() {
        let data = ["BEGIN:VTODO", "SUMMARY:Do the thing"].join("\r\n");
        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "BEGIN:VTODO",
                name: "BEGIN",
                params: "",
                value: "VTODO",
            })
        );
        assert_eq!(parser.remainder(), "SUMMARY:Do the thing");
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "SUMMARY:Do the thing",
                name: "SUMMARY",
                params: "",
                value: "Do the thing",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_fold_multiline() {
        assert_eq!(
            unfold_lines("UID:horrible-\r\n example"),
            "UID:horrible-example"
        );
        assert_eq!(unfold_lines("UID:X\r\n Y"), "UID:XY");
        assert_eq!(unfold_lines("UID:X\r\n "), "UID:X");
        assert_eq!(
            unfold_lines("UID:quite\r\n a\r\n few\r\n lines"),
            "UID:quiteafewlines"
        );
    }

    #[test]
    #[should_panic(expected = "continuation line is not a continuation line")]
    fn test_fold_multiline_missing_whitespace() {
        unfold_lines("UID:two\r\nlines");
    }

    #[test]
    fn test_normalise_folds_short() {
        let data = "SUMMARY:Hello there";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        assert_eq!(line.normalise_folds(), data);
        assert!(matches!(line.normalise_folds(), Cow::Borrowed(_)));
    }

    #[test]
    fn test_normalise_folds_with_carrige_returns() {
        let data = "SUMMARY:Hello \rthere";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        assert_eq!(line.normalise_folds(), data);
        assert!(matches!(line.normalise_folds(), Cow::Borrowed(_)));
    }

    #[test]
    fn test_normalise_folds_with_newlines() {
        // Note: bare \n is now treated as a line ending, so this is two lines
        let data = "SUMMARY:Hello \nthere";
        let mut parser = Parser::new(data);
        let line1 = parser.next().unwrap();
        assert_eq!(line1.raw(), "SUMMARY:Hello ");
        assert_eq!(line1.name(), "SUMMARY");
        assert_eq!(line1.value(), "Hello ");

        let line2 = parser.next().unwrap();
        assert_eq!(line2.raw(), "there");
        assert_eq!(line2.name(), "there");

        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_normalise_folds_too_many_folds() {
        let data = "SUMMARY:Hello \r\n \r\n there";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        let expected = "SUMMARY:Hello there";
        assert_eq!(line.normalise_folds(), expected);
    }

    #[test]
    fn test_normalise_folds_long() {
        let data = [
            "SUMMARY:Some really long text that nobody ",
            " cares about, but is wrapped in two lines.",
        ]
        .join("\r\n");
        let mut parser = Parser::new(&data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        let expected = [
            "SUMMARY:Some really long text that nobody cares about, but is wrapped in t",
            " wo lines.",
        ]
        .join("\r\n");
        assert_eq!(line.normalise_folds(), expected);
    }

    #[test]
    fn test_normalise_folds_multibyte() {
        // This is 59 characters, 161 octets
        let data = "SUMMARY:動千首看院波未假遠子到花，白六到星害，馬吃牠說衣欠去皮香收司意，青個話化汁喜視娘以男雪青土已升斤法兌。";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        let expected = [
            // Keep in mind that CR counts, but LF does not.
            "SUMMARY:動千首看院波未假遠子到花，白六到星害，馬吃牠", // 74
            " 說衣欠去皮香收司意，青個話化汁喜視娘以男雪青土已",    // 73
            " 升斤法兌。",                                          // 16
        ]
        .join("\r\n");
        assert_eq!(line.normalise_folds(), expected);
    }

    #[test]
    fn test_normalise_folds_multibyte_noop() {
        // This is 59 characters, 161 octets
        let data = [
            // Keep in mind that CR counts, but LF does not.
            "SUMMARY:動千首看院波未假遠子到花，白六到星害，馬吃牠", // 74
            " 說衣欠去皮香收司意，青個話化汁喜視娘以男雪青土已",    // 73
            " 升斤法兌。",                                          // 16
        ]
        .join("\r\n");
        let mut parser = Parser::new(&data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        assert_eq!(line.normalise_folds(), data);
        assert!(matches!(line.normalise_folds(), Cow::Borrowed(_)));
    }

    #[test]
    fn test_unfold_params_with_trailing_crlf() {
        let data = ";\r\n";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(line.raw(), ";");
        assert_eq!(line.name(), "");
        assert_eq!(line.params(), "");
        assert_eq!(line.value(), "");
    }

    #[test]
    fn test_unfold_name_with_trailing_crlf() {
        let data = "\r\n";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(line.raw(), "");
        assert_eq!(line.name(), "");
        assert_eq!(line.params(), "");
        assert_eq!(line.value(), "");
    }

    #[test]
    fn test_unfold_value_with_trailing_crlf() {
        let data = ";:\r\n";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(line.raw(), ";:");
        assert_eq!(line.name(), "");
        assert_eq!(line.params(), "");
        assert_eq!(line.value(), "");
    }

    #[test]
    fn dtend_with_tzid() {
        let param_str = "TZID=America/Argentina/Buenos_Aires";
        let mut params = ParamIter::new(param_str);

        let p = params.next().unwrap();
        assert_eq!(p.name, "TZID");
        assert_eq!(p.value, "America/Argentina/Buenos_Aires");

        assert!(params.next().is_none());
    }

    #[test]
    fn params_with_multiple() {
        let param_str = "X-JMAP-ID=123;CN=Alice;EMAIL=alice@example.com;CUTYPE=INDIVIDUAL;X-JMAP-ROLE=attendee;PARTSTAT=TENTATIVE;X-DTSTAMP=20250614T210147Z;X-SEQUENCE=1";
        let mut params = ParamIter::new(param_str);

        let p = params.next().unwrap();
        assert_eq!(p.name, "X-JMAP-ID");
        assert_eq!(p.value, "123");

        let p = params.next().unwrap();
        assert_eq!(p.name, "CN");
        assert_eq!(p.value, "Alice");

        let p = params.next().unwrap();
        assert_eq!(p.name, "EMAIL");
        assert_eq!(p.value, "alice@example.com");

        let p = params.next().unwrap();
        assert_eq!(p.name, "CUTYPE");
        assert_eq!(p.value, "INDIVIDUAL");

        let p = params.next().unwrap();
        assert_eq!(p.name, "X-JMAP-ROLE");
        assert_eq!(p.value, "attendee");

        let p = params.next().unwrap();
        assert_eq!(p.name, "PARTSTAT");
        assert_eq!(p.value, "TENTATIVE");

        let p = params.next().unwrap();
        assert_eq!(p.name, "X-DTSTAMP");
        assert_eq!(p.value, "20250614T210147Z");

        let p = params.next().unwrap();
        assert_eq!(p.name, "X-SEQUENCE");
        assert_eq!(p.value, "1");

        assert!(params.next().is_none());
    }

    #[test]
    fn quoted_params() {
        let param_str = r#"X-CUSTOM="Alice;Bob;Charlie";ROLE=attendee;STATUS=TENTATIVE"#;
        let mut params = ParamIter::new(param_str);

        let p = params.next().unwrap();
        assert_eq!(p.name, "X-CUSTOM");
        assert_eq!(p.value, r#""Alice;Bob;Charlie""#);

        let p = params.next().unwrap();
        assert_eq!(p.name, "ROLE");
        assert_eq!(p.value, "attendee");

        let p = params.next().unwrap();
        assert_eq!(p.name, "STATUS");
        assert_eq!(p.value, "TENTATIVE");

        assert!(params.next().is_none());
    }

    #[test]
    fn broken_quoted_params() {
        // This input is invalid. Tests merely asserts that we do not crash.
        let param_str = r#"X-CUSTOM="Alice;Bob;Charlie"#;
        let mut params = ParamIter::new(param_str);

        let p = params.next().unwrap();
        assert_eq!(p.name, "X-CUSTOM");
        assert_eq!(p.value, r#""Alice;Bob;Charlie"#);

        assert!(params.next().is_none());
    }

    // ===== LF-only test variants =====

    #[test]
    fn test_complete_example_lf() {
        let data = [
            "BEGIN:VCALENDAR",
            "VERSION:2.0",
            "PRODID:nl.whynothugo.todoman",
            "BEGIN:VTODO",
            "DTSTAMP:20231126T095923Z",
            "DUE;TZID=Asia/Shanghai:20231128T090000",
            "SUMMARY:dummy todo for parser tests",
            "UID:565f48cb5b424815a2ba5e56555e2832@destiny.whynothugo.nl",
            "END:VTODO",
            "END:VCALENDAR",
            // Note: this calendar is not entirely semantically valid;
            // it is missing the timezone which is referred to in DUE.
        ]
        .join("\n");

        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "BEGIN:VCALENDAR",
                name: "BEGIN",
                params: "",
                value: "VCALENDAR"
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "VERSION:2.0",
                name: "VERSION",
                params: "",
                value: "2.0",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "PRODID:nl.whynothugo.todoman",
                name: "PRODID",
                params: "",
                value: "nl.whynothugo.todoman",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "BEGIN:VTODO",
                name: "BEGIN",
                params: "",
                value: "VTODO",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTAMP:20231126T095923Z",
                name: "DTSTAMP",
                params: "",
                value: "20231126T095923Z",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DUE;TZID=Asia/Shanghai:20231128T090000",
                name: "DUE",
                params: "TZID=Asia/Shanghai",
                value: "20231128T090000",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "SUMMARY:dummy todo for parser tests",
                name: "SUMMARY",
                params: "",
                value: "dummy todo for parser tests",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "UID:565f48cb5b424815a2ba5e56555e2832@destiny.whynothugo.nl",
                name: "UID",
                params: "",
                value: "565f48cb5b424815a2ba5e56555e2832@destiny.whynothugo.nl",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "END:VTODO",
                name: "END",
                params: "",
                value: "VTODO",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "END:VCALENDAR",
                name: "END",
                params: "",
                value: "VCALENDAR",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_empty_lines_lf() {
        let data = "\n";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(
            line,
            ContentLine {
                raw: "",
                name: "",
                params: "",
                value: "",
            }
        );
        assert_eq!(line.raw(), "");
        assert_eq!(line.name(), "");
        assert_eq!(line.params(), "");
        assert_eq!(line.value(), "");
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_line_with_params_lf() {
        let data = [
            "DTSTART;TZID=America/New_York:19970902T090000",
            "DTSTART;TZID=America/New_York:19970902T090000",
        ]
        .join("\n");
        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART;TZID=America/New_York:19970902T090000",
                name: "DTSTART",
                params: "TZID=America/New_York",
                value: "19970902T090000",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART;TZID=America/New_York:19970902T090000",
                name: "DTSTART",
                params: "TZID=America/New_York",
                value: "19970902T090000",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_line_with_dquote_lf() {
        let data = [
            "SUMMARY:This has \"some quotes\"",
            "DTSTART;TZID=\"local;VALUE=DATE-TIME\":20150304T184500",
        ]
        .join("\n");
        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "SUMMARY:This has \"some quotes\"",
                name: "SUMMARY",
                params: "",
                value: "This has \"some quotes\"",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: "DTSTART;TZID=\"local;VALUE=DATE-TIME\":20150304T184500",
                name: "DTSTART",
                params: "TZID=\"local;VALUE=DATE-TIME\"",
                value: "20150304T184500",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_continuation_line_lf() {
        let data = [
            "X-JMAP-LOCATION;VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";",
            " X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c:Name of place",
            "X-JMAP-LOCATION;VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";",
            " X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c:Name of place",
        ]
        .join("\n");
        let mut parser = Parser::new(&data);
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: &[
                    "X-JMAP-LOCATION;VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";",
                    " X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c:Name of place",
                ]
                .join("\n"),
                name: "X-JMAP-LOCATION",
                params: "VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";\n X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c",
                value: "Name of place",
            })
        );
        assert_eq!(
            parser.next(),
            Some(ContentLine {
                raw: &[
                    "X-JMAP-LOCATION;VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";",
                    " X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c:Name of place",
                ]
                .join("\n"),
                name: "X-JMAP-LOCATION",
                params: "VALUE=TEXT;X-JMAP-GEO=\"geo:52.123456,4.123456\";\n X-JMAP-ID=03453afa-71fc-4893-ba70-a7436bb6d56c",
                value: "Name of place",
            })
        );
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_fold_multiline_lf() {
        assert_eq!(
            unfold_lines("UID:horrible-\n example"),
            "UID:horrible-example"
        );
        assert_eq!(unfold_lines("UID:X\n Y"), "UID:XY");
        assert_eq!(unfold_lines("UID:X\n "), "UID:X");
        assert_eq!(
            unfold_lines("UID:quite\n a\n few\n lines"),
            "UID:quiteafewlines"
        );
    }

    #[test]
    #[should_panic(expected = "continuation line is not a continuation line")]
    fn test_fold_multiline_missing_whitespace_lf() {
        unfold_lines("UID:two\nlines");
    }

    #[test]
    fn test_normalise_folds_too_many_folds_lf() {
        let data = "SUMMARY:Hello \n \n there";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        let expected = "SUMMARY:Hello there";
        assert_eq!(line.normalise_folds(), expected);
    }

    #[test]
    fn test_normalise_folds_long_lf() {
        let data = [
            "SUMMARY:Some really long text that nobody ",
            " cares about, but is wrapped in two lines.",
        ]
        .join("\n");
        let mut parser = Parser::new(&data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        // Normalization always outputs CRLF per spec
        let expected = [
            "SUMMARY:Some really long text that nobody cares about, but is wrapped in t",
            " wo lines.",
        ]
        .join("\r\n");
        assert_eq!(line.normalise_folds(), expected);
    }

    #[test]
    fn test_normalise_folds_multibyte_lf() {
        // Input has no line endings, so will default to CRLF when adding folds
        // To test LF line ending preservation, input must have LF line endings
        let data = "SUMMARY:動千首看院波未假遠子到花，白六到星害，馬吃牠說衣欠去皮香收司意，青個話化汁喜視娘以男雪青土已升斤法兌。";
        let mut parser = Parser::new(data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        // Since input has no line endings, defaults to CRLF when folding
        let expected = [
            "SUMMARY:動千首看院波未假遠子到花，白六到星害，馬吃牠", // 74
            " 說衣欠去皮香收司意，青個話化汁喜視娘以男雪青土已",    // 73
            " 升斤法兌。",                                          // 16
        ]
        .join("\r\n");
        assert_eq!(line.normalise_folds(), expected);
    }

    #[test]
    fn test_normalise_folds_multibyte_noop_lf() {
        let data = [
            "SUMMARY:動千首看院波未假遠子到花，白六到星害，馬吃牠", // 73
            " 說衣欠去皮香收司意，青個話化汁喜視娘以男雪青土已",    // 72
            " 升斤法兌。",                                          // 16
        ]
        .join("\n");
        let mut parser = Parser::new(&data);
        let line = parser.next().unwrap();
        assert_eq!(parser.next(), None);

        // Input has LF, but lines are already at optimal length, so no re-folding needed
        // However, this means it's borrowed - but note the line endings remain as LF in raw
        assert_eq!(line.normalise_folds(), data);
        assert!(matches!(line.normalise_folds(), Cow::Borrowed(_)));
    }

    // ===== Mixed CRLF and LF test variants =====

    #[test]
    fn test_complete_example_mixed() {
        // Mix of CRLF and LF line endings
        let data = [
            "BEGIN:VCALENDAR\r\n",
            "VERSION:2.0\n",
            "PRODID:nl.whynothugo.todoman\r\n",
            "BEGIN:VTODO\n",
            "DTSTAMP:20231126T095923Z\r\n",
            "DUE;TZID=Asia/Shanghai:20231128T090000\n",
            "SUMMARY:dummy todo for parser tests\r\n",
            "END:VTODO\n",
            "END:VCALENDAR",
        ]
        .concat();

        let mut parser = Parser::new(&data);
        assert_eq!(parser.next().unwrap().name(), "BEGIN");
        assert_eq!(parser.next().unwrap().name(), "VERSION");
        assert_eq!(parser.next().unwrap().name(), "PRODID");
        assert_eq!(parser.next().unwrap().name(), "BEGIN");
        assert_eq!(parser.next().unwrap().name(), "DTSTAMP");
        assert_eq!(parser.next().unwrap().name(), "DUE");
        assert_eq!(parser.next().unwrap().name(), "SUMMARY");
        assert_eq!(parser.next().unwrap().name(), "END");
        assert_eq!(parser.next().unwrap().name(), "END");
        assert_eq!(parser.next(), None);
    }

    #[test]
    fn test_continuation_line_mixed() {
        // First continuation with CRLF, second with LF
        let data = "X-LONG;PARAM=value1;\r\n PARAM2=value2:Content here\nX-SHORT:Value\n";
        let mut parser = Parser::new(data);

        let line1 = parser.next().unwrap();
        assert_eq!(line1.name(), "X-LONG");
        assert_eq!(line1.value(), "Content here");

        let line2 = parser.next().unwrap();
        assert_eq!(line2.name(), "X-SHORT");
        assert_eq!(line2.value(), "Value");

        assert_eq!(parser.next(), None);
    }
}