Skip to main content

graphrt_doc/
detect.rs

1//! Format detection: MIME type first, then file extension, then content sniffing.
2
3use std::fmt;
4
5/// A document format this crate knows about (whether or not its feature is enabled).
6#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
7#[non_exhaustive]
8pub enum Format {
9    PlainText,
10    Markdown,
11    Json,
12    Yaml,
13    Xml,
14    Csv,
15    Tsv,
16    Html,
17    Pdf,
18    Docx,
19    Pptx,
20    Xlsx,
21    Xls,
22    Ods,
23    Epub,
24    Eml,
25    Vtt,
26    Srt,
27}
28
29impl Format {
30    /// Short lowercase name, e.g. `pdf`.
31    pub fn name(self) -> &'static str {
32        match self {
33            Format::PlainText => "text",
34            Format::Markdown => "markdown",
35            Format::Json => "json",
36            Format::Yaml => "yaml",
37            Format::Xml => "xml",
38            Format::Csv => "csv",
39            Format::Tsv => "tsv",
40            Format::Html => "html",
41            Format::Pdf => "pdf",
42            Format::Docx => "docx",
43            Format::Pptx => "pptx",
44            Format::Xlsx => "xlsx",
45            Format::Xls => "xls",
46            Format::Ods => "ods",
47            Format::Epub => "epub",
48            Format::Eml => "eml",
49            Format::Vtt => "vtt",
50            Format::Srt => "srt",
51        }
52    }
53}
54
55impl Format {
56    /// Whether the format is plain text on disk (decoded as text, never fails).
57    pub fn is_textual(self) -> bool {
58        matches!(
59            self,
60            Format::PlainText
61                | Format::Markdown
62                | Format::Json
63                | Format::Yaml
64                | Format::Xml
65                | Format::Csv
66                | Format::Tsv
67                | Format::Html
68                | Format::Vtt
69                | Format::Srt
70                | Format::Eml
71        )
72    }
73}
74
75impl fmt::Display for Format {
76    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
77        f.write_str(self.name())
78    }
79}
80
81/// Map a MIME type (parameters ignored) to a format.
82pub fn from_mime(mime: &str) -> Option<Format> {
83    let essence = mime.split(';').next().unwrap_or_default().trim().to_ascii_lowercase();
84    Some(match essence.as_str() {
85        "text/plain" => Format::PlainText,
86        "text/markdown" | "text/x-markdown" => Format::Markdown,
87        "application/json" | "text/json" => Format::Json,
88        "application/yaml" | "application/x-yaml" | "text/yaml" | "text/x-yaml" => Format::Yaml,
89        "application/xml" | "text/xml" => Format::Xml,
90        "text/csv" | "application/csv" => Format::Csv,
91        "text/tab-separated-values" => Format::Tsv,
92        "text/html" | "application/xhtml+xml" => Format::Html,
93        "application/pdf" => Format::Pdf,
94        "application/vnd.openxmlformats-officedocument.wordprocessingml.document" => Format::Docx,
95        "application/vnd.openxmlformats-officedocument.presentationml.presentation" => Format::Pptx,
96        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" => Format::Xlsx,
97        "application/vnd.ms-excel" => Format::Xls,
98        "application/vnd.oasis.opendocument.spreadsheet" => Format::Ods,
99        "application/epub+zip" => Format::Epub,
100        "message/rfc822" => Format::Eml,
101        "text/vtt" => Format::Vtt,
102        "application/x-subrip" | "text/srt" => Format::Srt,
103        _ => return None,
104    })
105}
106
107/// Map a file extension (with or without the dot, any case) to a format.
108pub fn from_extension(ext: &str) -> Option<Format> {
109    let ext = ext.trim_start_matches('.').to_ascii_lowercase();
110    Some(match ext.as_str() {
111        "txt" | "text" | "log" | "properties" | "ini" | "cfg" | "conf" | "toml" => Format::PlainText,
112        "md" | "markdown" | "mdx" => Format::Markdown,
113        "json" | "jsonl" | "ndjson" => Format::Json,
114        "yaml" | "yml" => Format::Yaml,
115        "xml" => Format::Xml,
116        "csv" => Format::Csv,
117        "tsv" => Format::Tsv,
118        "html" | "htm" | "xhtml" => Format::Html,
119        "pdf" => Format::Pdf,
120        "docx" => Format::Docx,
121        "pptx" => Format::Pptx,
122        "xlsx" | "xlsm" => Format::Xlsx,
123        "xls" => Format::Xls,
124        "ods" => Format::Ods,
125        "epub" => Format::Epub,
126        "eml" => Format::Eml,
127        "vtt" => Format::Vtt,
128        "srt" => Format::Srt,
129        _ => return None,
130    })
131}
132
133/// Guess the format from the first bytes. Zip containers are not resolved here
134/// (see [`crate::extract`]), because that requires opening the archive.
135pub fn sniff(bytes: &[u8]) -> Option<Format> {
136    let head = bytes.get(..bytes.len().min(512)).unwrap_or_default();
137    if head.starts_with(b"%PDF-") {
138        return Some(Format::Pdf);
139    }
140    if head.starts_with(&[0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1]) {
141        // OLE compound file: legacy Office; only XLS is supported.
142        return Some(Format::Xls);
143    }
144    if head.starts_with(b"WEBVTT") || head.starts_with("\u{feff}WEBVTT".as_bytes()) {
145        return Some(Format::Vtt);
146    }
147    let text = String::from_utf8_lossy(head);
148    let trimmed = text.trim_start_matches('\u{feff}').trim_start();
149    let lower = trimmed.get(..trimmed.len().min(64)).unwrap_or_default().to_ascii_lowercase();
150    if lower.starts_with("<!doctype html") || lower.starts_with("<html") {
151        return Some(Format::Html);
152    }
153    if lower.starts_with("<?xml") {
154        return Some(Format::Xml);
155    }
156    if trimmed.starts_with('{') || trimmed.starts_with('[') {
157        return Some(Format::Json);
158    }
159    None
160}
161
162/// Whether an OLE compound file holds an Excel workbook stream (`Workbook` or
163/// `Book`). Word, PowerPoint and Outlook files are OLE too but are not supported.
164pub fn ole_is_workbook(bytes: &[u8]) -> bool {
165    let utf16 = |name: &str| -> Vec<u8> { name.encode_utf16().flat_map(u16::to_le_bytes).collect() };
166    let (workbook, book) = (utf16("Workbook"), utf16("Book"));
167    bytes.windows(workbook.len()).any(|w| w == workbook.as_slice())
168        || bytes.windows(book.len()).any(|w| w == book.as_slice())
169}
170
171/// Whether the bytes start like a zip archive.
172pub fn is_zip(bytes: &[u8]) -> bool {
173    bytes.starts_with(b"PK\x03\x04")
174}
175
176/// Whether the bytes look like text (no NUL bytes in the first 8 KiB).
177pub fn looks_textual(bytes: &[u8]) -> bool {
178    let head = bytes.get(..bytes.len().min(8192)).unwrap_or_default();
179    !head.contains(&0)
180}
181
182/// File extension of a file name, if any.
183pub fn extension(filename: &str) -> Option<&str> {
184    let base = filename.rsplit(['/', '\\']).next().unwrap_or(filename);
185    let (stem, ext) = base.rsplit_once('.')?;
186    if stem.is_empty() || ext.is_empty() { None } else { Some(ext) }
187}
188
189#[cfg(test)]
190mod tests {
191    use super::*;
192
193    #[test]
194    fn mime_and_extension() {
195        assert_eq!(from_mime("application/pdf; charset=binary"), Some(Format::Pdf));
196        assert_eq!(from_mime("application/octet-stream"), None);
197        assert_eq!(from_extension(".DOCX"), Some(Format::Docx));
198        assert_eq!(extension("a/b/report.final.xlsx"), Some("xlsx"));
199        assert_eq!(extension(".bashrc"), None);
200    }
201
202    #[test]
203    fn sniffing() {
204        assert_eq!(sniff(b"%PDF-1.4\n"), Some(Format::Pdf));
205        assert_eq!(sniff(b"  <!DOCTYPE html><p>x"), Some(Format::Html));
206        assert_eq!(sniff(b"WEBVTT\n\n"), Some(Format::Vtt));
207        assert_eq!(sniff(b"hello"), None);
208        assert!(is_zip(b"PK\x03\x04rest"));
209    }
210}