pub enum HlsLine<'a, Custom = NoCustomTag>where
Custom: CustomTag<'a>,{
KnownTag(KnownTag<'a, Custom>),
UnknownTag(UnknownTag<'a>),
Comment(Cow<'a, str>),
Uri(Cow<'a, str>),
Blank,
}Expand description
A parsed line from a HLS playlist.
The HLS specification, in Section 4.1. Definition of a Playlist, defines lines in a playlist as such:
Each line is a URI, is blank, or starts with the character ‘#’. Lines that start with the character ‘#’ are either comments or tags. Tags begin with #EXT.
This data structure follows that guidance but also adds HlsLine::UnknownTag and
KnownTag::Custom. These cases are described in more detail within their own documentation,
but in short, the first allows us to capture tags that are not yet known to the library
(providing at least a split between name and value), while the second allows a user of the
library to define their own custom tag specification that can be then parsed into a strongly
typed structure within a HlsLine::KnownTag by the library.
Variants§
KnownTag(KnownTag<'a, Custom>)
A tag known to the library, either via the included definitions of HLS tags as specified in
the draft-pantos-hls Internet-Draft, or via a custom tag registration provided by the user
of the library.
See KnownTag for more information.
UnknownTag(UnknownTag<'a>)
A tag, as defined by the #EXT prefix, but not one that is known to the library, or that is
deliberately ignored via ParsingOptions.
See UnknownTag for more information.
Comment(Cow<'a, str>)
A comment line. These are lines that begin with # and are followed by a string of UTF-8
characters (though not BOM or UTF-8 control characters). The line is terminated by either a
line feed (\n) or a carriage return followed by a line feed (\r\n).
The associated value is a std::borrow::Cow to allow for both a user constructed value
and also a copy-free reference to the original parsed data. It includes all characters after
the # (including any whitespace) and does not include the line break characters. Below
demonstrates this:
let original = "# Comment line. Note the leading space.\r\n";
let line = parse(original, &options)?.parsed;
assert_eq!(
HlsLine::Comment(Cow::Borrowed(" Comment line. Note the leading space.")),
line,
);Uri(Cow<'a, str>)
A URI line. These are lines that do not begin with # and are not empty. It is important to
note that the library does not do any validation on the line being a valid URI. The only
validation that happens is that line can be represented as a UTF-8 string (internally we use
std::str::from_utf8). This means that the line may contain characters that are invalid
in a URI, or may otherwise not make sense in the context of the parsed playlist. It is up to
the user of the library to validate the URI, perhaps using a URL parsing library (such as
url).
The associated value is a std::borrow::Cow to allow for both a user constructed value
and also a copy-free reference to the original parsed data. It includes all characters up
until, but not including, the line break characters. The following demonstrates this:
let expected = "hi.m3u8";
// Demonstrating that new line characters are not included:
assert_eq!(
HlsLine::Uri(Cow::Borrowed(expected)),
parse("hi.m3u8\n", &options)?.parsed,
);
assert_eq!(
HlsLine::Uri(Cow::Borrowed(expected)),
parse("hi.m3u8\r\n", &options)?.parsed,
);
assert_eq!(
HlsLine::Uri(Cow::Borrowed(expected)),
parse("hi.m3u8", &options)?.parsed,
);Blank
A blank line. This line contained no characters other than a new line. Note that since the library does not validate characters in a URI line, a line comprised entirely of whitespace will still be parsed as a URI line, rather than a blank line. As mentioned, it is up to the user of the library to properly validate URI lines.
// Demonstrating what is considered a blank line:
assert_eq!(
HlsLine::Blank,
parse("", &options)?.parsed,
);
assert_eq!(
HlsLine::Blank,
parse("\n", &options)?.parsed,
);
assert_eq!(
HlsLine::Blank,
parse("\r\n", &options)?.parsed,
);
// Demonstrating that a whitespace only line is still parsed as a URI:
assert_eq!(
HlsLine::Uri(Cow::Borrowed(" ")),
parse(" \n", &options)?.parsed,
);Implementations§
Source§impl<'a> HlsLine<'a>
impl<'a> HlsLine<'a>
Sourcepub fn comment(comment: impl Into<Cow<'a, str>>) -> Self
pub fn comment(comment: impl Into<Cow<'a, str>>) -> Self
Convenience constructor for HlsLine::Comment. This will construct the line with the
generic Custom in HlsLine::KnownTag being NoCustomTag.
Sourcepub fn uri(uri: impl Into<Cow<'a, str>>) -> Self
pub fn uri(uri: impl Into<Cow<'a, str>>) -> Self
Convenience constructor for HlsLine::Uri. This will construct the line with the generic
Custom in HlsLine::KnownTag being NoCustomTag.
Sourcepub fn blank() -> Self
pub fn blank() -> Self
Convenience constructor for HlsLine::Blank. This will construct the line with the
generic Custom in HlsLine::KnownTag being NoCustomTag.