openreadout_core/reader.rs
1//! The traits every format crate implements, and the registry that dispatches on them.
2
3use std::io::Read;
4use std::path::Path;
5
6use crate::error::{Error, Result};
7use crate::model::{
8 AttachmentInfo, CheckReport, DetectConfidence, FileInfo, FormatDescriptor, LsEntry, Spectrum,
9 Table, Trace,
10};
11use crate::pixel::Plane;
12use crate::provenance::ProvenanceMap;
13use crate::source::Input;
14
15/// Result of sniffing a file's first bytes.
16#[derive(Debug, Clone)]
17pub struct Detection {
18 /// Format id of the reader that matched.
19 pub format_id: &'static str,
20 /// How sure the match is.
21 pub confidence: DetectConfidence,
22 /// Why the match is less than definite, if it is.
23 pub note: Option<String>,
24}
25
26/// Which representation `read_spectrum_view` returns when a scan stores more than one
27/// (Fourier-transform instruments typically keep a profile *and* the instrument's centroid list).
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
29#[non_exhaustive]
30pub enum SpectrumView {
31 /// The scan's primary data: the profile when one was recorded, otherwise the centroids.
32 #[default]
33 Primary,
34 /// The centroid list stored by the instrument software, when the scan has one; otherwise
35 /// the same as `Primary`.
36 Centroid,
37}
38
39/// Which plane of an image to read. All zero-based.
40#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
41pub struct PlaneIndex {
42 /// Channel index.
43 pub c: u32,
44 /// Z index (focal plane).
45 pub z: u32,
46 /// Time index.
47 pub t: u32,
48}
49
50/// An open file. Implementations must keep `info` cheap: read headers, never pixels.
51pub trait Dataset: Send {
52 /// Header-only summary.
53 fn info(&self) -> Result<FileInfo>;
54 /// The vendor's metadata tree as JSON, names untouched.
55 fn vendor_metadata(&self) -> Result<serde_json::Value>;
56 /// Provenance of the normalized fields this reader fills.
57 fn provenance(&self) -> ProvenanceMap;
58 /// Structural listing for `info --view structure`.
59 fn entries(&self) -> Result<Vec<LsEntry>>;
60 /// Read one full-resolution plane. Mosaics are stitched; pyramids are ignored.
61 fn read_plane(&mut self, image: u32, index: PlaneIndex) -> Result<Plane>;
62 /// Integrity validation for `check`.
63 fn check(&mut self) -> Result<CheckReport>;
64 /// Integrity validation that reads headers and structure only (`check --headers-only`, and
65 /// the `index` crawl): offsets, declared sizes and counts against the file length, missing
66 /// parts; no decompression, no decoding of samples and no checksums over the data. Readers
67 /// whose `check` decodes data override it; the default is `check`, which for most formats
68 /// already reads only headers and structure.
69 fn check_headers(&mut self) -> Result<CheckReport> {
70 self.check()
71 }
72 /// Other files on disk that belong to this dataset (multi-file OME-TIFF members, CZI file
73 /// parts, OIR continuation files, a SpikeGLX `.meta`/`.bin` pair, an imzML `.ibd`, VSI
74 /// `.ets` stacks, ...), excluding the path that was opened. Only files that exist are
75 /// listed. `index` records them as members of this dataset instead of separate records.
76 /// Directory datasets (a Bruker `.d`, a ChemStation `.D`) keep the default: the directory
77 /// itself is the dataset.
78 fn member_files(&self) -> Vec<std::path::PathBuf> {
79 Vec::new()
80 }
81 /// Evidence that the file is not finished: the structures its software writes last that
82 /// are absent and the planes already complete ([`crate::live::WriteState`]). `None` for
83 /// finished files and for formats that do not know their write order (the default).
84 /// [`crate::live::assess`] turns it into `acquisition: in_progress | interrupted`.
85 fn write_state(&self) -> Option<crate::live::WriteState> {
86 None
87 }
88 /// Rows `[first_row, first_row + max_rows)` of table `index`. Formats without tables keep the default.
89 fn read_table(&mut self, index: u32, first_row: u64, max_rows: u64) -> Result<Table> {
90 let _ = (index, first_row, max_rows);
91 Err(Error::unsupported(
92 "core",
93 "tabular data",
94 "This format exposes images, not tables.",
95 ))
96 }
97 /// Samples `[first_sample, first_sample + max_samples)` of sweep `sweep` of trace `index`.
98 fn read_trace(
99 &mut self,
100 index: u32,
101 sweep: u32,
102 first_sample: u64,
103 max_samples: u64,
104 ) -> Result<Trace> {
105 let _ = (index, sweep, first_sample, max_samples);
106 Err(Error::unsupported(
107 "core",
108 "sampled signals",
109 "This format does not expose traces.",
110 ))
111 }
112 /// Spectrum `spectrum` of run `index`. Formats without spectra keep the default.
113 fn read_spectrum(&mut self, index: u32, spectrum: u64) -> Result<Spectrum> {
114 let _ = (index, spectrum);
115 Err(Error::unsupported(
116 "core",
117 "mass spectra",
118 "This format exposes images, not spectra.",
119 ))
120 }
121 /// MS level of every spectrum of run `run`, in spectrum-index order, when the reader knows
122 /// them without decoding peaks (a scan index, per-scan events, header summaries). `None`
123 /// (the default) means unknown: [`spectrum_by_level`] then reads the spectra one by one.
124 fn spectrum_ms_levels(&mut self, run: u32) -> Result<Option<Vec<u32>>> {
125 let _ = run;
126 Ok(None)
127 }
128 /// Zero-based index of the spectrum with instrument scan number `scan_number` in run `run`.
129 /// `Ok(None)` means the reader keeps no scan-number map; callers then assume scan numbers
130 /// are contiguous from the first spectrum's (see [`spectrum_by_scan`]).
131 fn find_spectrum(&mut self, run: u32, scan_number: u64) -> Result<Option<u64>> {
132 let _ = (run, scan_number);
133 Ok(None)
134 }
135 /// Visit the headers of run `run`'s spectra from spectrum `first` on, in index order,
136 /// without decoding any peaks (scan number, MS level, RT, polarity, precursor, isolation,
137 /// activation, filter, the file's stored TIC/base peak: [`crate::scans::ScanHeader`]).
138 /// `visit` returns false to stop. `Ok(false)` (the default) means the reader has no
139 /// header-only path; [`crate::scans::visit_scans`] then decodes the spectra.
140 fn visit_scan_headers(
141 &mut self,
142 run: u32,
143 first: u64,
144 visit: &mut dyn FnMut(crate::scans::ScanHeader) -> bool,
145 ) -> Result<bool> {
146 let _ = (run, first, visit);
147 Ok(false)
148 }
149 /// Like `read_spectrum`, choosing between stored representations. Formats that store only one
150 /// keep the default, which ignores `view`.
151 fn read_spectrum_view(
152 &mut self,
153 index: u32,
154 spectrum: u64,
155 view: SpectrumView,
156 ) -> Result<Spectrum> {
157 let _ = view;
158 self.read_spectrum(index, spectrum)
159 }
160 /// Read one plane of pyramid level `level` (0 = full resolution, larger = more downsampled;
161 /// `ImageInfo::pyramid_levels` says how many exist). Formats without pyramids keep the
162 /// default, which serves level 0 and rejects the rest.
163 fn read_plane_level(&mut self, image: u32, index: PlaneIndex, level: u32) -> Result<Plane> {
164 if level == 0 {
165 return self.read_plane(image, index);
166 }
167 Err(Error::unsupported(
168 "core",
169 "pyramid level reads",
170 "This format does not expose downsampled pyramid levels; read level 0.",
171 ))
172 }
173 /// Read the rectangle `region` of one plane of pyramid level `level`, in that level's pixel
174 /// coordinates (see [`crate::region`]). A region outside the level is a usage error (exit
175 /// 2). Readers that store pixels in tiles, subblocks or chunks override it to decode only
176 /// the tiles the region touches, which also makes regions of planes too large to assemble
177 /// whole ([`crate::pixel::MAX_PLANE_BYTES`]) readable. The default reads the whole plane at
178 /// the level and crops it.
179 fn read_region(
180 &mut self,
181 image: u32,
182 index: PlaneIndex,
183 level: u32,
184 region: crate::region::Region,
185 ) -> Result<Plane> {
186 let plane = self.read_plane_level(image, index, level)?;
187 crate::region::crop(plane, region, &format!("image {image} level {level}"))
188 }
189 /// Files embedded in the container (thumbnails, label images, time stamps, ...).
190 fn attachments(&self) -> Result<Vec<AttachmentInfo>> {
191 Ok(Vec::new())
192 }
193 /// Raw bytes of attachment `index` (see `attachments`).
194 fn read_attachment(&mut self, index: u32) -> Result<Vec<u8>> {
195 let _ = index;
196 Err(Error::unsupported(
197 "core",
198 "attachments",
199 "This format has no embedded attachments; `info --view structure` lists what the file contains.",
200 ))
201 }
202 /// Per-frame acquisition records of image `image` (acquisition time, stage position,
203 /// detector state, ...), too numerous for `info`. Each record is a JSON object in the
204 /// reader's documented vocabulary. At most `limit` records are returned (`None` = all);
205 /// the first value is the total number of records. `info --view full` stores them under
206 /// `images[i].extra.frames` (see [`attach_frames`]). Formats without per-frame records keep
207 /// the default (no records).
208 fn frames(&self, image: u32, limit: Option<usize>) -> Result<(u64, Vec<serde_json::Value>)> {
209 let _ = (image, limit);
210 Ok((0, Vec::new()))
211 }
212 /// Experiment facts this reader knows that the normalized model cannot carry (a Bruker NMR
213 /// `title` file, an mzML `sampleList`), each value with its origin in `provenance`. They are
214 /// laid over the experiment derived from `info` ([`crate::experiment::of_dataset`]). Most
215 /// readers keep the default: everything they know is already in `info`.
216 fn experiment(&self) -> Option<crate::experiment::Experiment> {
217 None
218 }
219 /// The layout of a multi-well plate (high-content screening): imaged wells, the images of
220 /// each, and how complete the copy on disk is. `info` reports it under `plate`. Readers
221 /// of other files keep the default (none).
222 fn plate(&self) -> Option<crate::plate::PlateSummary> {
223 None
224 }
225 /// What the reader itself knows about this file's variant beyond `info` (structures met
226 /// but not decoded, values assumed, calibrations, block types), laid over its assurance
227 /// profile's observations ([`crate::assurance::assess`]). Most readers keep the default:
228 /// their profile reads everything it needs from `info`. Wrappers forward it.
229 fn assurance_observations(&self) -> crate::assurance::Observations {
230 crate::assurance::Observations::default()
231 }
232 /// This file's assurance ([`crate::assurance::assess_dataset`] over `info`); `None` when
233 /// `info` cannot be read. The strict-mode wrapper returns the assessment it gates on, so
234 /// `check` reports it even when strict mode refuses `info`.
235 fn file_assurance(&self) -> Option<crate::assurance::Assurance> {
236 let info = self.info().ok()?;
237 Some(crate::assurance::assess(
238 &info,
239 self.assurance_observations(),
240 &self.provenance(),
241 ))
242 }
243 /// Leave the peaks the instrument flags as reference or background ions out of the spectra
244 /// read from now on (Thermo `.raw`: what ThermoRawFileParser and ProteoWizard before
245 /// 3.0.20286 write). Returns false when the format flags no peaks (nothing changes).
246 fn exclude_flagged_peaks(&mut self, exclude: bool) -> bool {
247 let _ = exclude;
248 false
249 }
250 /// True for the `--strict` wrapper ([`crate::strict::StrictDataset`]): outputs built from
251 /// it withhold the fields its assurance does not validate (`Assurance::strict_withholds`).
252 fn is_strict(&self) -> bool {
253 false
254 }
255}
256
257/// Read the spectrum with instrument scan number `scan` of run `run`: through
258/// [`Dataset::find_spectrum`] when the reader has a scan-number map, otherwise assuming scan
259/// numbers are contiguous from the first spectrum's.
260pub fn spectrum_by_scan(
261 ds: &mut dyn Dataset,
262 run: u32,
263 scan: u64,
264 view: SpectrumView,
265) -> Result<Spectrum> {
266 if let Some(i) = ds.find_spectrum(run, scan)? {
267 return ds.read_spectrum_view(run, i, view);
268 }
269 let first = ds.read_spectrum_view(run, 0, view)?;
270 let i = scan.checked_sub(first.scan_number).ok_or_else(|| {
271 Error::Usage(format!(
272 "scan {scan} precedes the first scan ({})",
273 first.scan_number
274 ))
275 })?;
276 let sp = if i == 0 {
277 first
278 } else {
279 ds.read_spectrum_view(run, i, view)?
280 };
281 if sp.scan_number != scan {
282 return Err(Error::Usage(format!(
283 "scan numbers are not contiguous; spectrum {i} is scan {}. Use --index",
284 sp.scan_number
285 )));
286 }
287 Ok(sp)
288}
289
290/// Read the `nth` (1-based) spectrum of MS level `ms_level` in run `run`. MS1 and MS/MS scans
291/// are interleaved in most runs, so the first MS2 scan cannot be found by assuming the MS1 scans
292/// come first: the reader's per-spectrum MS levels ([`Dataset::spectrum_ms_levels`]) locate it
293/// and only that spectrum is decoded; a reader without them is walked from its first spectrum,
294/// `scan_count` (from `info` → `spectra[run].scan_count`) bounding the walk.
295pub fn spectrum_by_level(
296 ds: &mut dyn Dataset,
297 run: u32,
298 ms_level: u32,
299 nth: u64,
300 scan_count: u64,
301 view: SpectrumView,
302) -> Result<Spectrum> {
303 if nth == 0 {
304 return Err(Error::Usage(
305 "--nth counts from 1 (the first scan of that level)".into(),
306 ));
307 }
308 let mut seen = 0u64;
309 if let Some(levels) = ds.spectrum_ms_levels(run)? {
310 for (i, l) in levels.iter().enumerate() {
311 if *l == ms_level {
312 seen += 1;
313 if seen == nth {
314 return ds.read_spectrum_view(run, i as u64, view);
315 }
316 }
317 }
318 return Err(Error::Usage(format!(
319 "run {run} has {seen} MS{ms_level} spectra (asked for number {nth}); `info` → spectra[].extra.ms_level_counts lists the counts"
320 )));
321 }
322 for i in 0..scan_count {
323 let sp = ds.read_spectrum_view(run, i, view)?;
324 if sp.ms_level == ms_level {
325 seen += 1;
326 if seen == nth {
327 return Ok(sp);
328 }
329 }
330 }
331 Err(Error::Usage(format!(
332 "run {run} has {seen} MS{ms_level} spectra (asked for number {nth}); `info` → spectra[].extra.ms_level_counts lists the counts"
333 )))
334}
335
336/// Default number of per-frame records `info --view full` embeds per image (`--all-frames` lifts
337/// it).
338pub const DEFAULT_FRAME_RECORDS: usize = 100;
339
340/// Store each image's per-frame records under `extra.frames` (plus `extra.frame_records_total`
341/// and, when capped, `extra.frames_truncated: true`). Images without records are left untouched.
342pub fn attach_frames(ds: &dyn Dataset, info: &mut FileInfo, limit: Option<usize>) -> Result<()> {
343 for img in &mut info.images {
344 let (total, records) = ds.frames(img.index, limit)?;
345 if records.is_empty() {
346 continue;
347 }
348 let truncated = (records.len() as u64) < total;
349 img.extra
350 .insert("frames".into(), serde_json::Value::Array(records));
351 img.extra
352 .insert("frame_records_total".into(), serde_json::Value::from(total));
353 if truncated {
354 img.extra
355 .insert("frames_truncated".into(), serde_json::Value::Bool(true));
356 }
357 }
358 Ok(())
359}
360
361/// A format implementation.
362pub trait FormatReader: Send + Sync {
363 /// Static description of the format (id, name, extensions, known gaps).
364 fn descriptor(&self) -> FormatDescriptor;
365 /// Inspect the first bytes (up to 64 KiB) and the path; return `None` if this is not ours.
366 fn sniff(&self, head: &[u8], path: &Path) -> Option<Detection>;
367 /// Open for reading.
368 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>>;
369 /// Like [`sniff`](FormatReader::sniff), for an [`Input`] that may not be on the local file
370 /// system. Readers whose detection looks at other files (a directory's contents, a
371 /// sibling) override it to look through [`Input::fs`]; the default calls `sniff` with the
372 /// input's path.
373 fn sniff_input(&self, head: &[u8], input: &Input) -> Option<Detection> {
374 self.sniff(head, input.path())
375 }
376 /// Open an [`Input`]: a local path, a buffer in memory, or a source the host provides.
377 /// Readers that read through [`Input::fs`] override it (and make `open` a thin wrapper);
378 /// the default opens local inputs by path and reports every other source as unsupported
379 /// (exit 6), so a reader that does not read through byte sources never touches the local disk
380 /// for a buffer that merely has the same name.
381 fn open_input(&self, input: &Input) -> Result<Box<dyn Dataset>> {
382 if input.is_local() {
383 return self.open(input.path());
384 }
385 let d = self.descriptor();
386 Err(Error::Unsupported {
387 format: "input",
388 feature: format!(
389 "reading {} ({}) from an in-memory or host-provided source",
390 d.name, d.id
391 ),
392 hint: Some(
393 "This reader opens local files only so far: save the data to a file and open its path."
394 .into(),
395 ),
396 })
397 }
398 /// True when [`open_input`](FormatReader::open_input) reads any [`Input`] (memory, host
399 /// callbacks), not only local paths.
400 fn reads_any_source(&self) -> bool {
401 false
402 }
403 /// The reader's assurance profile (its crate's `src/assurance.rs`): how to fingerprint a
404 /// file's variant and which variants the development corpus validates. `None` (the
405 /// default) makes every file of the format `unvalidated`.
406 fn assurance(&self) -> Option<&'static crate::assurance::AssuranceProfile> {
407 None
408 }
409}
410
411/// Number of leading bytes handed to `sniff`.
412pub const SNIFF_LEN: usize = 64 * 1024;
413
414/// Ordered collection of readers. First definite match wins; otherwise best confidence.
415pub struct Registry {
416 readers: Vec<Box<dyn FormatReader>>,
417 /// `--strict`: datasets opened through this registry refuse outputs their file's
418 /// assurance does not validate ([`crate::strict`]).
419 strict: bool,
420}
421
422impl std::fmt::Debug for Registry {
423 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
424 let ids: Vec<String> = self.readers.iter().map(|r| r.descriptor().id).collect();
425 f.debug_struct("Registry")
426 .field("readers", &ids)
427 .field("strict", &self.strict)
428 .finish()
429 }
430}
431
432impl Default for Registry {
433 /// An empty registry, strict when the process-wide default says so
434 /// ([`crate::assurance::default_strict`]: `--strict`, `OPENREADOUT_STRICT=1`).
435 fn default() -> Self {
436 Registry {
437 readers: Vec::new(),
438 strict: crate::assurance::default_strict(),
439 }
440 }
441}
442
443impl Registry {
444 /// An empty registry. Readers are consulted in the order they are added.
445 pub fn new() -> Self {
446 Self::default()
447 }
448
449 /// Add a reader at the end of the detection order (and make its assurance profile known).
450 pub fn register(&mut self, reader: Box<dyn FormatReader>) {
451 if let Some(p) = reader.assurance() {
452 crate::assurance::register_profile(p);
453 }
454 self.readers.push(reader);
455 }
456
457 /// Strict mode (`--strict`, MCP `strict: true`): every dataset this registry opens refuses,
458 /// with exit 6 and a hint, to return outputs its file's assurance does not validate
459 /// (`assurance.strict_refuses`: an unvalidated variant, an undecoded structure or an unapplied
460 /// calibration affecting them). `check` and `info --view structure` are never refused.
461 #[must_use]
462 pub fn strict(mut self, on: bool) -> Self {
463 self.strict = on;
464 self
465 }
466
467 /// True in strict mode.
468 pub fn is_strict(&self) -> bool {
469 self.strict
470 }
471
472 /// Builder form of [`Registry::register`].
473 pub fn with(mut self, reader: Box<dyn FormatReader>) -> Self {
474 self.register(reader);
475 self
476 }
477
478 /// Descriptors of every registered reader, in detection order.
479 pub fn descriptors(&self) -> Vec<FormatDescriptor> {
480 self.readers.iter().map(|r| r.descriptor()).collect()
481 }
482
483 /// The reader with this format id, if registered.
484 pub fn by_id(&self, id: &str) -> Option<&dyn FormatReader> {
485 self.readers
486 .iter()
487 .find(|r| r.descriptor().id == id)
488 .map(AsRef::as_ref)
489 }
490
491 /// Read the head of the file and ask every reader. A directory (a vendor "folder format"
492 /// such as a Bruker `.d`) is offered to every reader with an empty head; readers that accept
493 /// directories recognise them by their path and contents.
494 pub fn detect(&self, path: &Path) -> Result<(&dyn FormatReader, Detection)> {
495 self.detect_input(&Input::local(path))
496 }
497
498 /// Like [`detect`](Registry::detect), for any [`Input`] (a local path, a buffer, a host
499 /// source).
500 pub fn detect_input(&self, input: &Input) -> Result<(&dyn FormatReader, Detection)> {
501 let path = input.path();
502 let meta = input.metadata()?;
503 let mut head = Vec::new();
504 if !meta.is_dir() {
505 let mut file = input.open()?;
506 head = vec![0u8; SNIFF_LEN];
507 let mut filled = 0;
508 while filled < head.len() {
509 let n = file
510 .read(&mut head[filled..])
511 .map_err(|e| Error::io(path, e))?;
512 if n == 0 {
513 break;
514 }
515 filled += n;
516 }
517 head.truncate(filled);
518 if filled == 0 {
519 // An empty file is a truncated file (interrupted copy or acquisition), not an
520 // unknown format: report it as corrupt so agents do not go looking for a reader.
521 return Err(Error::Corrupt {
522 format: "input",
523 detail: "the file is empty (0 bytes)".into(),
524 offset: Some(0),
525 });
526 }
527 }
528 let mut best: Option<(&dyn FormatReader, Detection)> = None;
529 for r in &self.readers {
530 if let Some(d) = r.sniff_input(&head, input) {
531 let better = match &best {
532 None => true,
533 Some((_, b)) => rank(d.confidence) > rank(b.confidence),
534 };
535 if better {
536 let definite = d.confidence == DetectConfidence::Definite;
537 best = Some((r.as_ref(), d));
538 if definite {
539 break;
540 }
541 }
542 }
543 }
544 best.ok_or_else(|| Error::UnknownFormat {
545 path: path.to_path_buf(),
546 })
547 }
548
549 /// Detect and open.
550 pub fn open(&self, path: &Path) -> Result<(Detection, Box<dyn Dataset>)> {
551 let (reader, det) = self.detect(path)?;
552 let ds = reader.open(path)?;
553 Ok((det, self.guard(ds)?))
554 }
555
556 /// In strict mode, wrap `ds` so it refuses unvalidated outputs; otherwise return it as is.
557 pub fn guard(&self, ds: Box<dyn Dataset>) -> Result<Box<dyn Dataset>> {
558 if self.strict {
559 crate::strict::StrictDataset::wrap(ds)
560 } else {
561 Ok(ds)
562 }
563 }
564
565 /// Detect and open any [`Input`]. Readers that only read local files report other inputs
566 /// as unsupported (exit 6).
567 pub fn open_input(&self, input: &Input) -> Result<(Detection, Box<dyn Dataset>)> {
568 let (reader, det) = self.detect_input(input)?;
569 let ds = reader.open_input(input)?;
570 Ok((det, self.guard(ds)?))
571 }
572
573 /// Detect from bytes already in memory (the first up to [`SNIFF_LEN`] bytes of a stream,
574 /// e.g. standard input). `name` stands in for the path readers may consult for an extension.
575 pub fn detect_bytes(&self, head: &[u8], name: &Path) -> Result<(&dyn FormatReader, Detection)> {
576 let head = &head[..head.len().min(SNIFF_LEN)];
577 let mut best: Option<(&dyn FormatReader, Detection)> = None;
578 for r in &self.readers {
579 if let Some(d) = r.sniff(head, name)
580 && best
581 .as_ref()
582 .is_none_or(|(_, b)| rank(d.confidence) > rank(b.confidence))
583 {
584 let definite = d.confidence == DetectConfidence::Definite;
585 best = Some((r.as_ref(), d));
586 if definite {
587 break;
588 }
589 }
590 }
591 best.ok_or_else(|| Error::UnknownFormat {
592 path: name.to_path_buf(),
593 })
594 }
595}
596
597fn rank(c: DetectConfidence) -> u8 {
598 match c {
599 DetectConfidence::Definite => 3,
600 DetectConfidence::Likely => 2,
601 DetectConfidence::ExtensionOnly => 1,
602 }
603}
604
605/// Helper for readers: does the path have one of these extensions (case-insensitive)?
606pub fn has_extension(path: &Path, exts: &[&str]) -> bool {
607 path.extension()
608 .and_then(|e| e.to_str())
609 .is_some_and(|e| exts.iter().any(|x| x.eq_ignore_ascii_case(e)))
610}
611
612#[cfg(test)]
613mod tests {
614 use super::*;
615 use crate::provenance::Confidence;
616
617 #[derive(Debug)]
618 struct PathOnly;
619
620 impl FormatReader for PathOnly {
621 fn descriptor(&self) -> FormatDescriptor {
622 FormatDescriptor {
623 id: "path-only".into(),
624 name: "Path-only test format".into(),
625 vendor: String::new(),
626 extensions: vec!["po".into()],
627 family: "test".into(),
628 can_read: true,
629 can_write: false,
630 confidence: Confidence::Low,
631 known_gaps: Vec::new(),
632 }
633 }
634 fn sniff(&self, head: &[u8], _path: &Path) -> Option<Detection> {
635 head.starts_with(b"PO").then_some(Detection {
636 format_id: "path-only",
637 confidence: DetectConfidence::Definite,
638 note: None,
639 })
640 }
641 fn open(&self, path: &Path) -> Result<Box<dyn Dataset>> {
642 Err(Error::Other(format!("opened {}", path.display())))
643 }
644 }
645
646 #[test]
647 fn unmigrated_readers_refuse_non_file_inputs() {
648 let reg = Registry::new().with(Box::new(PathOnly));
649 let input = Input::from_bytes("x.po", b"PO data".to_vec());
650 let (r, det) = reg.detect_input(&input).unwrap();
651 assert_eq!(det.format_id, "path-only");
652 assert!(!r.reads_any_source());
653 let err = reg.open_input(&input).map(|_| ()).unwrap_err();
654 assert_eq!(err.exit_code(), 6, "{err}");
655 assert!(err.hint().is_some());
656 // Local paths still reach `open`.
657 let dir = tempfile::tempdir().unwrap();
658 let path = dir.path().join("x.po");
659 std::fs::write(&path, b"PO data").unwrap();
660 let err = reg
661 .open_input(&Input::local(&path))
662 .map(|_| ())
663 .unwrap_err();
664 assert!(err.to_string().starts_with("opened "), "{err}");
665 // Empty inputs are corrupt, missing ones are I/O errors, like `detect`.
666 let empty = Input::from_bytes("e.po", Vec::new());
667 let code = |i: &Input| reg.detect_input(i).map(|_| ()).unwrap_err().exit_code();
668 assert_eq!(code(&empty), 4);
669 assert_eq!(code(&empty.with_path("other.po")), 5);
670 }
671}
672
673#[cfg(test)]
674mod level_tests {
675 use super::*;
676 use crate::model::{CheckReport, FileInfo, LsEntry, Spectrum};
677
678 /// A run with the given MS levels; counts the spectra decoded.
679 struct Run {
680 levels: Vec<u32>,
681 indexed: bool,
682 reads: u64,
683 }
684 impl Dataset for Run {
685 fn info(&self) -> Result<FileInfo> {
686 Err(Error::Other("unused".into()))
687 }
688 fn vendor_metadata(&self) -> Result<serde_json::Value> {
689 Ok(serde_json::Value::Null)
690 }
691 fn provenance(&self) -> ProvenanceMap {
692 ProvenanceMap::new()
693 }
694 fn entries(&self) -> Result<Vec<LsEntry>> {
695 Ok(vec![])
696 }
697 fn read_plane(&mut self, _: u32, _: PlaneIndex) -> Result<Plane> {
698 Err(Error::Other("unused".into()))
699 }
700 fn check(&mut self) -> Result<CheckReport> {
701 Ok(CheckReport::new("fake", "fake"))
702 }
703 fn read_spectrum(&mut self, _: u32, i: u64) -> Result<Spectrum> {
704 self.reads += 1;
705 Ok(Spectrum {
706 index: i,
707 ms_level: self.levels[i as usize],
708 ..Spectrum::default()
709 })
710 }
711 fn spectrum_ms_levels(&mut self, _: u32) -> Result<Option<Vec<u32>>> {
712 Ok(self.indexed.then(|| self.levels.clone()))
713 }
714 }
715
716 #[test]
717 fn nth_of_level_uses_the_index_when_there_is_one() {
718 for indexed in [true, false] {
719 let mut r = Run {
720 levels: vec![1, 2, 2, 1, 2],
721 indexed,
722 reads: 0,
723 };
724 let sp = spectrum_by_level(&mut r, 0, 2, 3, 5, SpectrumView::Primary).unwrap();
725 assert_eq!(sp.index, 4);
726 assert_eq!(r.reads, if indexed { 1 } else { 5 });
727 let err = spectrum_by_level(&mut r, 0, 2, 4, 5, SpectrumView::Primary).unwrap_err();
728 assert!(err.to_string().contains("has 3 MS2 spectra"), "{err}");
729 }
730 }
731}